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

# Estimate talent pool

> Count how many profiles match a set of filters, without returning them.

> **[First time? Set up Authentication](/authentication.md)**
>
> Learn how to authenticate your API requests with your API key.

Count the profiles that match a `filters` array. The response is a number and the mode that produced it. No profile, talent id, or `searchTransactionId` is returned, and no profile is saved.

You can post the `data` object from [extract search from prompt](/api-reference/search-talents-by-prompt-extraction.md) directly. `qualificationCriterias` is ignored. The same prompt can yield slightly different filters, so store `data` if you need a stable search.

## Request body

**filters** `object[]` *required*

Same filter objects as [`POST
    /v1/search/talents`](/api-reference/search-talents.md). At least one filter is
required. See [accepted filter values](/api-reference/accepted-filter-values.md).

**mode** `string` (default: gate)

Optional. One of `gate` or `rank`. Defaults to `gate` when omitted. See
[Search modes](/api-reference/search-talents.md#search-modes). Qualified search
always runs in gate mode, so the `gate` estimate is the one that matches the
qualified search pool.

Fields other than `filters` and `mode` are ignored, so the extraction `data` object, which also carries `qualificationCriterias`, is accepted as-is.

## Limits

| Item | Limit |
| - | - |
| `filters` | At least one filter. Each filter follows the rules of `POST /v1/search/talents`, for example `YEARS_OF_EXPERIENCE` as `"min-max"` with both bounds between 0 and 100 and min ≤ max. |
| `mode` | Optional. `gate` or `rank`. Defaults to `gate`. |
| `estimationCount` | Capped at 10,000. |
| Balance | At least 1 API credit, even though nothing is debited. |
| Rate limits | Each call counts against the API key's request windows. See [Rate limits](/rate-limits.md). |

## Response

Successful responses carry two headers:

| Header | Value |
| - | - |
| `X-Api-Credits-Used` | Always `0`. |
| `X-Api-Credits-Remaining` | Your workspace balance, read before the count. |

Error responses do not send these headers.

**success** `boolean`

Whether the request completed without errors.

**data** `object`

Present when `success` is `true`.

**data fields**

**estimationCount** `number`

Estimated number of profiles matching the filters in the requested mode. The estimate is capped at 10,000: a value of 10,000 means "10,000 or more".

**mode** `string`

The mode that produced `estimationCount`: `gate` or `rank`. `gate` when the request omitted `mode`.

**error** `object`

Error details, present when `success` is `false`.

**error fields**

**code** `string`

Machine-readable error code. One of: `validation_error`, `insufficient_api_credits`, `unsupported_location`, `missing_connected_linkedin_account`, `search_engine_timeout`, `missing_api_key`, `invalid_api_key`, `expired_token`, `plan_upgrade_required`, `rate_limit_exceeded`, `internal_error`.

**message** `string`

Human-readable error description.

**debugTrackingCode** `string`

Unique tracking code for this request. Include it when contacting support.

**available** `number`

API credits available. Only present when `code` is `insufficient_api_credits`.

**required** `number`

Minimum balance required, always `1`. Only present when `code` is `insufficient_api_credits`.

**issues** `object[]`

Zod validation details. Only present when `code` is `validation_error`.

**details** `object`

Present when `code` is `plan_upgrade_required` (billing remediation, see [Authentication](/authentication.md#error-responses)) or when `code` is `rate_limit_exceeded` on an API-key window.

**rate limit details fields**

**window** `string`

The time window that was exceeded. One of: `second`, `minute`, `hour`, `day`, `month`.

**limit** `number`

Maximum number of requests allowed in this window.

**current** `number`

Number of requests made in this window, including the rejected one.

## Credits

The call debits **0 API credits**, in `gate` and in `rank` mode. Nothing is reserved or consumed.

It is still rejected with `402` `insufficient_api_credits` unless the balance is at least 1. `required` is `1` and `available` is the balance that was read. A successful response sends `X-Api-Credits-Used: 0` and `X-Api-Credits-Remaining` equal to that balance.

See [Credits](/credits.md#estimate-a-talent-pool).

## Errors

| Status | `error.code` | When |
| - | - | - |
| 400 | `validation_error` | Missing or empty `filters`, an invalid filter, a `mode` other than `gate` or `rank`, or a body that is not a JSON object. |
| 400 | `missing_connected_linkedin_account` | A LinkedIn-relationship filter was sent and no LinkedIn account is connected. |
| 401 | `missing_api_key` | No API key was sent. |
| 401 | `invalid_api_key` | The API key or OAuth access token is not valid. |
| 401 | `expired_token` | The OAuth access token has expired. Re-authorize. |
| 402 | `insufficient_api_credits` | Balance is below 1. `required` is `1`. |
| 402 | `plan_upgrade_required` | The workspace must subscribe or upgrade its plan before using the API. Search routes, including this one, do not require a subscription today. |
| 422 | `unsupported_location` | A location filter cannot be resolved. |
| 429 | `rate_limit_exceeded` | An API-key request window, or the per-IP limit on failed authentication, was exceeded. See [Rate limits](/rate-limits.md). |
| 500 | `internal_error` | The count failed. |
| 504 | `search_engine_timeout` | The count timed out. Retry. |

## Response examples

> **200 — Success**
>
> ```bash Request theme={null}
> curl -X POST https://app.kalent.ai/api/v1/search/talents/estimation \
>   -H "Content-Type: application/json" \
>   -H "x-api-key: YOUR_API_KEY" \
>   -d '{
>     "mode": "gate",
>     "filters": [
>       {
>         "filterType": "JOB_TITLE",
>         "value": "Data Engineer",
>         "isRequired": true,
>         "isExcluded": false,
>         "isExactMatch": false,
>         "history": "CURRENT"
>       },
>       {
>         "filterType": "LOCATION",
>         "value": "Paris",
>         "isRequired": true,
>         "isExcluded": false,
>         "isExactMatch": false
>       },
>       {
>         "filterType": "YEARS_OF_EXPERIENCE",
>         "value": "5-100",
>         "isRequired": false,
>         "isExcluded": false,
>         "isExactMatch": false
>       }
>     ]
>   }'
> ```
>
> ```text Response headers theme={null}
> X-Api-Credits-Used: 0
> X-Api-Credits-Remaining: 41
> ```
>
> ```json Response theme={null}
> {
>   "success": true,
>   "data": {
>     "estimationCount": 1840,
>     "mode": "gate"
>   }
> }
> ```

> **400 — Validation error**
>
> Returned when the body does not match the schema. Here `filters` is empty.
>
> ```bash Request theme={null}
> curl -X POST https://app.kalent.ai/api/v1/search/talents/estimation \
>   -H "Content-Type: application/json" \
>   -H "x-api-key: YOUR_API_KEY" \
>   -d '{
>     "filters": []
>   }'
> ```
>
> ```json Response theme={null}
> {
>   "success": false,
>   "error": {
>     "code": "validation_error",
>     "message": "Validation failed",
>     "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT",
>     "issues": [
>       {
>         "code": "too_small",
>         "minimum": 1,
>         "type": "array",
>         "inclusive": true,
>         "exact": false,
>         "message": "filters must not be empty",
>         "path": ["filters"]
>       }
>     ]
>   }
> }
> ```
>
> An unknown `mode` returns the same envelope with this issue:
>
> ```json theme={null}
> {
>   "received": "fast",
>   "code": "invalid_enum_value",
>   "options": ["gate", "rank"],
>   "path": ["mode"],
>   "message": "Invalid enum value. Expected 'gate' | 'rank', received 'fast'"
> }
> ```
>
> A `YEARS_OF_EXPERIENCE` value such as `"5+"`, `"150-100"`, or `"10-5"` returns:
>
> ```json theme={null}
> {
>   "code": "custom",
>   "message": "Years of experience must be one string \"min-max\" with both bounds between 0 and 100 and min ≤ max",
>   "path": ["filters", 0, "value"]
> }
> ```

> **400 — Missing connected LinkedIn account**
>
> Returned when a `LINKEDIN_RELATIONS_DEGREE` filter is sent and the workspace has no connected LinkedIn account.
>
> ```json Response theme={null}
> {
>   "success": false,
>   "error": {
>     "code": "missing_connected_linkedin_account",
>     "message": "No LinkedIn account is connected. Connect LinkedIn in your Kalent settings to filter results by LinkedIn connections.",
>     "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT"
>   }
> }
> ```

> **401 — Authentication error**
>
> Returned when the API key is missing or invalid, or when an OAuth access token has expired.
>
> ```json Response (missing key) theme={null}
> {
>   "success": false,
>   "error": {
>     "code": "missing_api_key",
>     "message": "Missing API key",
>     "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT"
>   }
> }
> ```
>
> ```json Response (invalid key) theme={null}
> {
>   "success": false,
>   "error": {
>     "code": "invalid_api_key",
>     "message": "Invalid API key",
>     "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT"
>   }
> }
> ```
>
> ```json Response (expired OAuth token) theme={null}
> {
>   "success": false,
>   "error": {
>     "code": "expired_token",
>     "message": "Access token has expired. Please re-authorize.",
>     "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT"
>   }
> }
> ```

> **402 — Insufficient API credits**
>
> Returned when the balance is below 1. Nothing is counted. Top up your credits and retry.
>
> ```json Response theme={null}
> {
>   "success": false,
>   "error": {
>     "code": "insufficient_api_credits",
>     "message": "Insufficient API credits: 0 available, 1 required.",
>     "available": 0,
>     "required": 1,
>     "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT"
>   }
> }
> ```

> **402 — Plan upgrade required**
>
> Returned by authentication when the workspace must subscribe or upgrade its plan. Search routes, including this one, do not require a subscription today.
>
> ```json Response theme={null}
> {
>   "success": false,
>   "error": {
>     "code": "plan_upgrade_required",
>     "message": "A Kalent subscription or plan upgrade is required to use the Kalent API. Please subscribe or upgrade your plan in Kalent billing: https://app.kalent.ai/settings/billing",
>     "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT",
>     "details": {
>       "code": "subscription_or_plan_upgrade_required",
>       "action": "subscribe_or_upgrade",
>       "capability": "use_kalent_api",
>       "billingUrl": "https://app.kalent.ai/settings/billing"
>     }
>   }
> }
> ```

> **422 — Unsupported location**
>
> Returned when a `LOCATION` filter cannot be resolved. Remove that location or change it. Retrying the same value will not succeed.
>
> ```json Response theme={null}
> {
>   "success": false,
>   "error": {
>     "code": "unsupported_location",
>     "message": "Unsupported location: Singapore",
>     "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT"
>   }
> }
> ```

> **429 — Rate limit exceeded**
>
> Returned when an API-key request window is exceeded. A per-IP limit on failed authentication returns the same code with the message `Too many requests, please try again later` and no `details`. See [Rate limits](/rate-limits.md).
>
> ```json Response theme={null}
> {
>   "success": false,
>   "error": {
>     "code": "rate_limit_exceeded",
>     "message": "Rate limit exceeded: too many requests per minute",
>     "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT",
>     "details": {
>       "window": "minute",
>       "limit": 30,
>       "current": 31
>     }
>   }
> }
> ```

> **500 — Internal error**
>
> Returned when the count fails unexpectedly. Retry, and include `debugTrackingCode` if you contact support.
>
> ```json Response theme={null}
> {
>   "success": false,
>   "error": {
>     "code": "internal_error",
>     "message": "An error occurred during talent pool estimation",
>     "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT"
>   }
> }
> ```

> **504 — Search timeout**
>
> Returned when the count takes too long. Retry, or narrow the filters.
>
> ```json Response theme={null}
> {
>   "success": false,
>   "error": {
>     "code": "search_engine_timeout",
>     "message": "The search request timed out. Please try again.",
>     "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT"
>   }
> }
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.