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.

Read your balances

GET /v1/credits and the MCP tool get_credit_balances return the two remaining balances:
On HTTP, that object is data inside { "success": true, "data": ... }. The call spends no credits and does not require a subscription. It does count in the per-key rate-limit windows. GET /v1/credits sends no X-Api-Credits-* headers.

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 150 free API credits. They expire three months 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. The MCP response includes credits even when no profile is returned. 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 of a qualified search does not send either header. GET /v1/credits 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, and SMS sent by sequences, spend this same balance. contact.remaining is the contact-credit balance shown in the Kalent app: the credits granted at the last plan reset, plus credits added since, minus credits spent since. Enrichments still in progress are not deducted yet. It can differ from the amount Kalent checks before starting an enrichment or sending an SMS. When they differ, the enrichment response (402 insufficient_credits) or the paused sequence is what applies. The value can be 0 before the first plan reset, and it is not floored at 0.

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: POST /v1/contact/enrich does not require a Kalent subscription: only the balance is checked. POST /v1/candidates/{candidateId}/enrich-contacts and the MCP tools also fail when the workspace subscription is not active or trialing; the MCP tools then return a message asking the user to subscribe or upgrade. A super-admin user skips the check. 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.