Skip to main content
Kalent keeps two credit balances on the workspace. Search draws from API credits. Contact enrichment draws from contact credits. 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. The first API key or MCP connection on a workspace includes 100 free API credits. They expire one month after they are granted. The workspace owner can buy more API credits in Kalent billing. No Kalent subscription is required to buy them or to spend them on talent search and qualified 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 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 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.

​
Extract search inputs

POST /v1/search/talents/by-prompt/extraction charges one API credit when it returns filters. Billing shows that debit as “API search inputs extraction”.
  1. If the balance is 0, the route returns 402 and does not extract. required is 1.
  2. Otherwise Kalent reserves 1 credit before reading the prompt.
  3. If the prompt yields no usable filter, or the call fails, the reservation is cancelled and the balance is unchanged.
  4. On success, that credit is consumed. The response sends X-Api-Credits-Used: 1 and X-Api-Credits-Remaining.

​
Estimate a talent pool

POST /v1/search/talents/estimation charges zero API credits, whether mode is gate or rank. The call is still rejected with 402 unless the balance is at least 1 (required is 1). Nothing is reserved or consumed. A successful response sends X-Api-Credits-Used: 0 and X-Api-Credits-Remaining equal to the balance that was read.

​
Headers

Talent search (POST /v1/search/talents, POST /v1/search/talents/by-prompt, and POST /v0.1/search/talents), search-input extraction (POST /v1/search/talents/by-prompt/extraction), and talent-pool estimation (POST /v1/search/talents/estimation) send: 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

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

​
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.