> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kalent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Credits

> API credits for search, and contact credits for enrichment. They are separate balances.

Kalent keeps two credit balances on the workspace. Search draws from API credits. Contact enrichment draws from contact credits.

| Balance             | Spent by                                                     | Not spent by                                         |
| ------------------- | ------------------------------------------------------------ | ---------------------------------------------------- |
| **API credits**     | Talent search and qualified search (HTTP and MCP)            | Contact enrichment, sourcings, candidates, sequences |
| **Contact credits** | LinkedIn contact enrichment and candidate contact enrichment | Talent search and qualified search                   |

Rate limits are separate from both balances. See [Rate limits](/rate-limits).

## API credits

API credits are the sum of the workspace's unexpired credit grants. Every API key on the workspace shares that balance.

Signup includes **100** free API credits.

### Talent search

`POST /v1/search/talents`, `POST /v1/search/talents/by-prompt`, and legacy `POST /v0.1/search/talents` charge **one API credit per profile returned**.

1. If the balance is `0`, the route returns [402](#402-insufficient_api_credits) and does not search. `required` is `1`.
2. Otherwise Kalent reserves `min(balance, nbToFetch)` credits before searching.
3. If the search returns no profiles, or fails, the reservation is cancelled and those credits go back to the balance. An empty success is still `200`, with `X-Api-Credits-Used: 0`.
4. If profiles are returned, one credit is consumed per profile. Reserved credits that were not consumed go back to the balance.

When the balance is lower than `nbToFetch`, the search is shortened to the balance. The response stays `200`, with `resultCompleteness.reason` set to `insufficient_credits`.

MCP talent search uses the same balance and the same one-credit-per-profile rule. It does not send the HTTP headers below.

### Qualified search

Qualified search charges **two API credits per judged profile**. When a call opens, Kalent reserves `min(balance, target.maxCredits)`. A start or continue that cannot reserve at least 2 credits returns [402](#402-insufficient_api_credits) with `required` `2`. Unused reserved credits are returned when each wave ends.

Call budgets, what is charged, and what is returned are specified on the [qualified search overview](/api-reference/qualified-search-overview). `GET /v1/search/talents/qualified/{castingId}` does not spend credits.

MCP qualified search uses the same balance and the same two-credit rule.

### Headers

Talent search (`POST /v1/search/talents`, `POST /v1/search/talents/by-prompt`, and `POST /v0.1/search/talents`) sends:

| Header                    | Meaning                                                              |
| ------------------------- | -------------------------------------------------------------------- |
| `X-Api-Credits-Used`      | Credits consumed by this response. `0` when no profile was returned. |
| `X-Api-Credits-Remaining` | Workspace API-credit balance after this response.                    |

Qualified search start, by-prompt, and continue send only `X-Api-Credits-Remaining`: the balance after the call's reservation. GET does not send either header.

### 402 `insufficient_api_credits`

```json theme={null}
{
  "success": false,
  "error": {
    "code": "insufficient_api_credits",
    "message": "Insufficient API credits: 0 available, 1 required.",
    "available": 0,
    "required": 1,
    "debugTrackingCode": "..."
  }
}
```

`available` and `required` are the numbers from the failed reservation. The `message` is `Insufficient API credits: {available} available, {required} required.`

## Contact credits

Contact credits are a separate balance from API credits. Enriching a contact in the Kalent app spends this same balance.

### LinkedIn and candidate enrichment

Both of these routes check contact credits before they start, and neither checks API credits:

* `POST /v1/contact/enrich`
* `POST /v1/candidates/{candidateId}/enrich-contacts`

The same check applies to the MCP tools that start those enrichments.

The balance must cover this price, on top of enrichments that are still in progress:

| `enrichmentType` | Contact credits required to start |
| ---------------- | --------------------------------- |
| `phone`          | 1                                 |
| `personalEmail`  | 1                                 |
| `all`            | 2                                 |

The check also fails when the workspace subscription is not active or trialing. A super-admin user skips it.

When enrichment records a phone number or an email address, the balance is reduced by **1** contact credit. One result that includes both is charged once. A phone and an email that arrive as separate results are charged once each.

If the balance cannot cover the start, the route returns **402**:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient workspace credits for this operation",
    "debugTrackingCode": "..."
  }
}
```

### Adding a candidate

`POST /v1/sourcings/{sourcingId}/candidates` does not spend API credits.

For a new candidate, the workspace subscription must be active or trialing. Otherwise the route returns **402** `plan_upgrade_required`. A super-admin user skips the check.