Credits, billing & usage tracking

The credit model

Most endpoints cost a fixed number of credits per call. Search and company employees are dynamic: the charge is credits x requested_limit, so asking for more results costs proportionally more. 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 reserve at submit and debit in the worker once the result lands. 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"
}

What isn't billed yet

Some newer or observability-only pricing is computed but not yet debited. For instance, a general-search backend path calculates a cost without charging it. You may see a computed cost that never shows up on the bill - that is expected, not a discrepancy. Treat credit_tracker as the source of truth for what you were actually charged.

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.