Credits - Kalent API

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.

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.

If the balance is 0, the route returns 402 and does not search. required is 1.
Otherwise Kalent reserves min(balance, nbToFetch) credits before searching.
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.
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 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. 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`

{
  "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:

{
  "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.

​API credits

​Talent search

​Qualified search

​Headers

​402 insufficient_api_credits

​Contact credits

​LinkedIn and candidate enrichment

​Adding a candidate