--- updatedAt: 2026-10-29T07:22:13.000Z agentTools: projectIndex: https://docs.cognism.com/llms.txt --- # Credits and Search tokens How the Cognism API meters usage — search tokens for records returned, credits for contact details revealed — and how to read your balance from response headers. The Cognism API meters usage with two quotas that are easy to confuse: **search tokens** count the records you retrieve, **credits** count the contact details you reveal. A third mechanism, [rate limits](https://docs.cognism.com/docs/rate-limits), governs how fast you can send requests rather than how much data you receive. ## The three quotas side by side | | Rate limits | Search tokens | Credits | | :------------ | :------------------------ | :------------------------------------------- | :-------------------------------------------------- | | Meters | | Rows returned, or count calls | Contacts revealed | | Window | 60 seconds | Billing period | Billing period | | Signalled by | `RateLimit-*` headers | `X-Rate-Results-*` headers | — (reported in the Cognism platform) | | When exceeded | `429 rate_limit_exceeded` | `402 insufficient_budget` | — | | Reduce by | Slowing down | Lowering `limit`, narrow the search criteria | Requesting `contacts` only for the records you need | ## Search tokens Search tokens are your **result allowance**. The API charges **one token per row returned** in the `data` array from `POST /persons/filter` and `POST /companies/filter`. An empty result page costs no tokens. Each call to `POST /persons/filter/count` or `POST /companies/filter/count` costs one token, regardless of the total count returned. | | | | :---------- | :---------------------------------------------------------------------------------------------------------------------------- | | Unit | One token per row returned by `POST /persons/filter` or `POST /companies/filter`; one token per call to either count endpoint | | Scope | Per account | | Period | Your billing period. The balance resets at the account's next token reset. | | Allotment | Set by your subscription | | Not charged | Empty result pages, dictionaries, intent topics, settings, health | ### Reading your balance Every search response reports where you stand: | Header | Meaning | | :------------------------------- | :------------------------------------ | | `X-Rate-Results-Limit` | Your allotment for the current period | | `X-Rate-Results-Limit-Remaining` | Records left in the current period | | `X-Rate-Results-Limit-Reset` | Seconds until the period resets | The budget is checked before a search runs and charged after it returns, so a search is admitted whenever **any** balance remains: the last search of a period returns a full page and takes the balance to zero, and the next request is rejected. ### When the budget runs out ```http HTTP/1.1 402 Payment Required X-Rate-Results-Limit: 100000 X-Rate-Results-Limit-Remaining: 0 X-Rate-Results-Limit-Reset: 481200 ``` ```json { "error": "insufficient_budget", "message": "Your account has run out of search tokens. Retry after 481200 seconds.", "reason": "exhausted", "retryAfter": 481200 } ``` | `reason` | Meaning | What to do | | :------------------ | :--------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- | | `exhausted` | The allotment for this period is used up. | Wait `retryAfter` seconds, or talk to your account team about a larger allowance. **Do not retry in a loop** — `retryAfter` can be days. | | `stale_reset` | The billing period ended and the new one has not been provisioned yet. | Transient; `retryAfter` is `0`. Retry with exponential backoff. | | `store_unavailable` | The budget could not be verified. | Transient. Retry with exponential backoff. | ### Spend tokens deliberately Because tokens are charged per row, `limit` is a spend control as much as a page size. Requesting `limit=100` when you render 20 rows spends five times the tokens you need. Two habits keep spend predictable: 1. **Count first.** Send the same filter to the count endpoint to learn how many records match before you decide whether to page through them. Each count call costs one token. 2. **Fetch what you display.** Set `limit` to the number of records you will actually use on each page. Empty result pages cost no tokens. ## Credits Credits meter **contact data you reveal**. Requesting the `contacts` segment on a person search (`view=contacts`) returns email addresses and phone numbers, and each person record returned with that segment is charged as one reveal against your credit balance. ```http POST /persons/filter?view=demographics,contacts&limit=25 ``` Everything else costs no credits: searching without the `contacts` segment, counting, and the `demographics`, `education`, `pastCompanies`, `skills` and `events` segments. Company searches never consume credits. Search without `contacts` first, decide which people you need to reach, then request `contacts` for those records only — for example by filtering on their IDs. A person search with `view=contacts` and `limit=100` can spend 100 credits in a single call. Credit balance and consumption are reported in your Cognism account tooling rather than in API response headers. ## Guidance for AI agents An agent that spends on behalf of a user should estimate cost before it acts: * Search tokens spent = number of rows returned by a filter request. An empty result page costs zero tokens. Each count request costs one token, regardless of its total. * Credits spent = number of person records returned with the `contacts` segment. Confirm with the user before revealing contacts for more than a handful of records. > I used 1 search token to count 340 matching people. Retrieving the first 50 will use 50 search tokens and no credits. Revealing emails and phone numbers for those 50 will use up to 50 credits. Continue?