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:
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.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.requiredis1. - 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, withX-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.
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
Qualified search charges two API credits per judged profile. When a call opens, Kalent reservesmin(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”.
- If the balance is
0, the route returns 402 and does not extract.requiredis1. - Otherwise Kalent reserves 1 credit before reading the prompt.
- If the prompt yields no usable filter, or the call fails, the reservation is cancelled and the balance is unchanged.
- On success, that credit is consumed. The response sends
X-Api-Credits-Used: 1andX-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/enrichPOST /v1/candidates/{candidateId}/enrich-contacts
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.
