> For the complete documentation index, see [llms.txt](https://docs.coresignal.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coresignal.com/guides/understanding-credits-and-billing.md).

# Understanding Credits and Billing

Learn how API credits work, what each endpoint costs, and how to monitor and top up your balance.

Every billable API request uses credits from your account balance. This guide explains credit costs, free operations, and how to track and top up your balance.

### How credits work

Three rules determine when and how credits are charged:

* **Free search endpoints**. `/search/filter`, `/search/es_dsl`, and `/semantic_search/es_dsl` on the Multi-source APIs cost no credits. Credits are charged when you retrieve records or previews through Collect, Bulk Collect, Enrich, Search Preview, or Agentic Search.
* **Only successful requests are billed**. You are charged only when a request returns HTTP 200, meaning that the request was successful and returned data.
* **Credits are shared across your team**. Your balance belongs to your team’s subscription, not to an individual API key. That means that all API keys on the account draw from the same pool.

### Credit pricing by endpoint

The table below lists the credit cost, billing unit, and returned data for each endpoint.

<table data-search="false"><thead><tr><th>Endpoint</th><th>Billing unit</th><th>Credit cost</th><th>Returned</th></tr></thead><tbody><tr><td><code>/search/filter</code></td><td>Per query, any result count</td><td>Free</td><td>Matching record IDs only</td></tr><tr><td><code>/search/es_dsl</code></td><td>Per query, any result count</td><td>Free</td><td>Matching record IDs only</td></tr><tr><td><code>/semantic_search/es_dsl</code></td><td>Per query, any result count</td><td>Free</td><td>Matching record IDs only</td></tr><tr><td>Webhooks</td><td>Per query, any result count</td><td>Free</td><td>Notification</td></tr><tr><td><code>/search/filter/preview</code></td><td>Per page (up to 20 results)</td><td>20</td><td>Predefined fields and match score</td></tr><tr><td><code>/search/es_dsl/preview</code></td><td>Per page (up to 20 results)</td><td>20</td><td>Predefined fields and match score</td></tr><tr><td><code>/v2/job_multi_source/collect/</code></td><td>Per record</td><td>1</td><td>Full record; Collect – Jobs API</td></tr><tr><td><code>/v2/employee_post/collect/</code></td><td>Per record</td><td>1</td><td>Full record; Collect – Employee Posts API</td></tr><tr><td><code>/v2/company_post/collect/</code></td><td>Per record</td><td>1</td><td>Full record; Collect – Company Posts API</td></tr><tr><td><code>/v2/historical_headcount/collect/</code></td><td>Per record</td><td>10</td><td>Headcount history for one company; Collect – Historical Headcount API</td></tr><tr><td><code>/rtapi/v2/employee/scrape</code></td><td>Per record</td><td>12</td><td>Freshly scraped employee profile; Real-time Employee API</td></tr><tr><td><code>/v2/company_multi_source/collect/</code></td><td>Per record</td><td>20</td><td>Company record (<a href="#bundle-pricing">see full pricing breakdown</a>); Collect – Multi-source Company API</td></tr><tr><td><code>/v2/employee_multi_source/collect/</code></td><td>Per record</td><td>20</td><td>Employee profile (<a href="#bundle-pricing">see full pricing breakdown</a>); Collect – Multi-source Employee API</td></tr><tr><td>Bulk collect (any data set above)</td><td>Per record delivered</td><td>Same as the matching Collect</td><td>One JSONL file with the same fields as single-record Collect</td></tr><tr><td><code>/v2/company_multi_source/enrich</code></td><td>Per record</td><td>20</td><td>Full company record (<a href="#bundle-pricing">see full pricing breakdown</a>); enrich – Company API</td></tr><tr><td><code>https://api.coresignal.com/enrichment/</code></td><td>Per record</td><td>10</td><td>Publicly available email address; enrich – Contact Enrichment API</td></tr><tr><td><p>Agentic Search: fast</p><p><code>/v2/agentic_search/fast</code></p></td><td>Per query (flat)</td><td>20</td><td>Generated DSL query, plus up to 20 preview records (optional)</td></tr><tr><td><p>Agentic Search: reasoning</p><p><code>/v2/agentic_search/reasoning</code></p></td><td>Per query (flat)</td><td>100</td><td>Generated DSL query, plus up to 20 preview records (optional)</td></tr><tr><td>AI Data Search Lists</td><td>Per preview (up to 20 records) / per enriched row</td><td>1-20</td><td>Preview records/enriched rows</td></tr></tbody></table>

#### Bundle pricing

Company and employee records are organized into categories such as growth signals or career intelligence, which are grouped into bundles. Your per-record cost for the Multi-source Company and Employee APIs depends on the number of bundles you request.

| Bundles                   | Company API | Employee API |
| ------------------------- | ----------- | ------------ |
| Core only                 | 10 credits  | 10 credits   |
| Core + 1                  | 14 credits  | 14 credits   |
| Core + 2                  | 16 credits  | 17 credits   |
| Core + 3                  | 18 credits  | –            |
| All bundles (full record) | 20 credits  | 20 credits   |

### Free operations

There are some operations that do not use any credits:

* Search endpoints (`/search/filter`, `/search/es_dsl`, `/semantic_search/es_dsl`), regardless of result count
* Requests that return `0` results or failed attempts
* Agentic Search and AI Data Search clarification turns
* Webhooks

### How charges are calculated

Some endpoints have billing rules beyond the per-unit cost:

* **Search Preview** up to 20 results per page (the limit is 50 pages/1,000 results total). The cost depends on the number of pages pulled.
* **Bulk Collect** charges credits when the result file is ready, not when you submit the request. Each request can include up to 10,000 records, so split larger lists across multiple requests. Duplicate requests are rejected with HTTP 409 and are not processed or billed twice.
* **Agentic Search** charges the same flat rate whether or not you use `return_data`.
* **Multi-source Company and Employee APIs** are charged per-record, based on how many data bundles you add. A core data bundle is always included and it costs 10 credits.
* [**AI Data Search Lists**](https://docs.coresignal.com/self-service/features-and-tools/ai-data-search/lists-pricing.md) lets you preview up to 20 records, and 1–20 credits per enriched row depending on the data you request. A full 10,000-row list is capped at 200,000 credits.

### Checking your balance

To check the balance, refer to `x-credits-remaining` response header, which is returned in every API call, showing credits left in the account after that request.

| Header                | Appears on                | Meaning                                                        |
| --------------------- | ------------------------- | -------------------------------------------------------------- |
| `x-credits-remaining` | Every response            | Credits left in the account after this request                 |
| `x-total-results`     | Search/Search Preview     | Total records matching the query                               |
| `x-snapshot-token`    | Search Preview pagination | Token for requesting the next page of a stable result snapshot |

To check your balance without spending credits, call a free Search endpoint and read the header, or check the dashboard.

#### How to top up your balance

You can top up your credit balance by:

* Renewing your current plan or upgrading to a higher-tier plan in the [Plans & credits](https://dashboard.coresignal.com/pricing) section of the dashboard.
* Setting up auto top-up, which pre-authorizes a credit purchase when your balance drops below a chosen threshold. Go to **Settings > Billing > Auto credit top-up**.

### Using your credits efficiently

Check your results before paying for full records. Search is free and previews are low-cost, so refining a query costs less than collecting a few full profiles that do not match your search intent.

* **Size your result set first**. The `x-total-results` header on a free search shows the match count, so you can estimate a job’s cost before running it.
* **Preview before you collect**. Refining a query is cheaper than collecting records that do not match your intent.
  * **Search Preview:** returns predefined fields and a match score you can use to verify your query before running Collect or Bulk Collect.
  * **Agentic Search fast:** turns a prompt into a validated query and returns up to 20 preview records. Fields vary by prompt.
* **Match bundles to your use case**. Requesting fewer data bundles in Multi-source Company or Employee Collect requests lowers the credit cost.

### Cost planning examples

The examples below show how to estimate credit costs for common workflows. All examples assume that a full record is collected.

Formula: $$Total\ credits = records\ collected \times credits\ per\ record$$

**Example 1: Search and collect**

A search finds 250 matching employee IDs. You collect 50 of them with the Multi-source Employee API:

$$
50 × 20 = 1,000\ credits
$$

You only pay for the records you collect.

**Example 2: Bulk collection**

You collect 5,000 company records with the Multi-source Company API in one Bulk Collect request:

$$
5,000 × 20 = 100,000\ credits
$$

For a list of 12,000 company IDs, split the job into two Bulk Collect requests (for example, 10,000 and 2,000 records), since each request is capped at 10,000.

**Example 3: Preview, then collect**

You review 2 pages of Search Preview results to confirm your query, then collect 1,000 employee records with the Multi-source Employee API:

$$
(2 × 20) + (1,000 × 20) = 40 + 20,000 = 20,040\ credits
$$

The preview adds only 0.2% of the total cost.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coresignal.com/guides/understanding-credits-and-billing.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
