Credits, billing & usage tracking

The credit model

Most endpoints cost a fixed number of credits per call. Search and company employees are dynamic: the pre-flight check uses credits x requested_limit as the maximum, while the final charge is credits x results_returned. These are the documented default costs - your workspace may have negotiated overrides, and the live figures load from your account into the endpoint pages.

Person

Company

Feature surcharges

On search endpoints, feature toggles change the price. The more you turn on, the more each result costs. The billing action key is a function of the feature combination - deduped and canonically ordered - so the same set of toggles always maps to the same key:

For example, a search with emails and phones on bills under person_search:show_emails:show_phone_numbers. Which toggles are available and what each one adds is covered in Request depth.

Pre-flight checks & deduction

Credits are handled in two moments. Before any work starts, the request runs a pre-flight allowance check: if the workspace cannot cover the estimated cost, the call fails immediately with 402 insufficient_credits and nothing is spent. Credits are only deducted on completion, after a meaningful result. Async endpoints check the estimated cost at submission. Dynamic search and employee endpoints deduct credits for the actual completed result count. Every charge carries a billing_action_key naming exactly what was billed:

{
  "success": true,
  "data": {
    "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
    "status": "completed",
    "billing_action_key": "person_search:show_emails:show_phone_numbers",
    "credits_charged": 20,
    "requested_limit": 10
  },
  "timestamp": "2026-05-28T18:04:45"
}

When the pre-flight check fails, the shape is the standard error envelope - branch on error.code:

{
  "success": false,
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits to complete this request."
  },
  "timestamp": "2026-05-28T18:04:45"
}

The monthly quota

On top of per-request credits, your plan has a monthly request quota - a cap on how many calls you can make in a billing month, independent of credit balance. Exceeding it returns monthly_limit_exceeded with HTTP 429:

{
  "success": false,
  "error": {
    "code": "monthly_limit_exceeded",
    "message": "Monthly request quota exceeded."
  },
  "timestamp": "2026-05-28T18:04:45"
}

Every response carries the quota state in headers, so you can watch your remaining budget without a separate call:

The quota is distinct from per-minute and per-hour throttling. For those, see Rate limits.

Usage tracking & analytics

You can see per-call spend and history through the Usage Analytics API, which reports credits grouped by billing_action_key:

{
  "success": true,
  "data": {
    "period": "2026-05",
    "total_credits": 142,
    "by_action": [
      {
        "billing_action_key": "person_search",
        "credits": 40,
        "calls": 40
      },
      {
        "billing_action_key": "person_search:show_emails",
        "credits": 60,
        "calls": 30
      },
      {
        "billing_action_key": "person_enrichment",
        "credits": 42,
        "calls": 21
      }
    ]
  },
  "timestamp": "2026-05-28T18:04:45"
}

Computed cost versus charged usage

An estimate or computed cost is not itself a charge. Treat total_credits and by_action from Usage Analytics as the authoritative record of deducted credits.

What's next

• Rate limits - per-minute and per-hour throttling, and how the monthly quota fits in.
• Request depth - the feature toggles and enrichment tiers that move the price.
• Effective requests - shaping calls to get the results you need for the fewest credits.
• Responses - the envelope, error codes, and status fields you branch on.