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

# search_qualified_talents_by_filters

> Start a qualified talent search from structured Kalent filters via your AI assistant.

The `search_qualified_talents_by_filters` tool starts a **qualified search** from structured Kalent filters plus qualification criteria. Kalent returns a `castingId` immediately. Ask the assistant to call [`get_qualified_search_result`](/mcp/get-qualified-search-result) every 10–20 seconds while `nextAction` is `wait`.

The start is a **call** with its own quota, `target` (`target.greens`, credit cap `target.maxCredits`). Within that cap Kalent analyses talents in successive waves on its own, until this call finds `target.greens` green talents, the cap is spent, or the talent pool is exhausted. Two credits are charged per judged talent, whatever the verdict, and never for a judgement started after the call's green quota was met; Kalent reserves `min(workspace balance, target.maxCredits)` when the call opens and returns unused reserved credits when each wave ends. To spend more afterwards, use [`continue_qualified_search`](/mcp/continue-qualified-search).

This tool does not accept a webhook: poll [`get_qualified_search_result`](/mcp/get-qualified-search-result) instead. Calls, waves, credits, and edge cases are explained on the [qualified search overview](/api-reference/qualified-search-overview).

Call this tool when you want structured Kalent filters (`filters`, `filterType`, `isRequired`, `isExcluded`, `isExactMatch`, `radius`, `history`). For a natural-language qualified search, use [`search_qualified_talents_by_prompt`](/mcp/search-qualified-talents-by-prompt).

Filters use the same model as [`search_talents_by_filters`](/mcp/search-talents-by-filters) and [`POST /v1/search/talents`](/api-reference/search-talents). This tool does **not** accept `relatedSearchTransactionIds` or `nbToFetch`.

The HTTP counterpart is [`POST /v1/search/talents/qualified`](/api-reference/search-talents-qualified).

## Input

| Parameter                | Type      | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------ | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `filters`                | object\[] | Yes      | Structured Kalent filters (see [`search_talents_by_filters`](/mcp/search-talents-by-filters)).                                                                                                                                                                                                                                                                                                                                               |
| `qualificationCriterias` | string\[] | Yes      | At least one item, maximum 10. Each string is trimmed, 1 to 300 characters.                                                                                                                                                                                                                                                                                                                                                                  |
| `scoringLanguage`        | string    | No       | `en` or `fr`: language of `recap`, criterion `title`, and criterion `result`. Omitted: the language of the user who owns the API key, changeable at [app.kalent.ai/settings/profile](https://app.kalent.ai/settings/profile) (English when unset). Fixed for the whole search; the same request in another language is a different search with its own analysis and credits. Quotes in `references` stay in the profile's original language. |
| `target`                 | object    | No       | Quota of this call. Omitted: defaults below.                                                                                                                                                                                                                                                                                                                                                                                                 |
| `target.greens`          | number    | No       | Green talents to find during this call, from 1 to 50. Default 10. Greens from earlier calls do not count.                                                                                                                                                                                                                                                                                                                                    |
| `target.maxCredits`      | number    | No       | Credit cap for this call, even integer from 2 to 300. Default 60 (at most 30 analysed talents).                                                                                                                                                                                                                                                                                                                                              |
| `forceNew`               | boolean   | No       | Default `false`. When `true`, starts a new qualified search even if the same filters, criteria, and scoring language are already running.                                                                                                                                                                                                                                                                                                    |

## Response

The tool returns JSON with:

| Field       | Type    | Description                                                                |
| ----------- | ------- | -------------------------------------------------------------------------- |
| `castingId` | string  | Identifier of the qualified search                                         |
| `status`    | string  | `running`, `can_continue`, `pool_exhausted`, or `failed_retryable`         |
| `reused`    | boolean | `true` when an existing qualified search for the same request was returned |

## Errors

The tool response is marked as an error when:

* There is no MCP session
* API credits are insufficient (`Insufficient API credits: {available} available, {required} required.`)
* No qualification criterion remains
* The search times out (`The search request timed out. Please try again. (ref: …)`)