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

# Get qualified search result

> Read the status and qualified talents of a search.

<Card title="First time? Set up Authentication" icon="key" href="/authentication">
  Learn how to authenticate your API requests with your API key.
</Card>

Read a qualified search started with [`POST /v1/search/talents/qualified`](/api-reference/search-talents-qualified) or [`POST /v1/search/talents/qualified/by-prompt`](/api-reference/search-talents-qualified-by-prompt).

This endpoint only reads talents that already received a verdict. It never starts an analysis, never costs credits, and does not send the `X-Api-Credits-Remaining` header (only start, by-prompt, and continue do). Calls, waves, and credits are explained on the [qualified search overview](/api-reference/qualified-search-overview). To analyse new talents, call [`POST /v1/search/talents/qualified/{castingId}/continue`](/api-reference/continue-qualified-search).

Follow `nextAction`:

| `nextAction` | What to do                                                                                                                                                     |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `wait`       | A call is running. Poll again in 10–20 seconds, or wait for the end-of-call webhook.                                                                           |
| `continue`   | The call stopped and more matching talents exist. Call continue to authorise another call. It looks for `target.greens` new greens, up to `target.maxCredits`. |
| `retry`      | The last wave failed. Call continue to retry it.                                                                                                               |
| `done`       | The talent pool is exhausted. Nothing more to analyse.                                                                                                         |

`canContinue` is kept for compatibility and equals `nextAction === "continue"`.

## Ordering

Talents are returned **green first, then amber, then red**. Within a verdict, they are in the order they were judged. Pagination follows the same order across pages.

## Path

<ParamField path="castingId" type="string" required>
  The `castingId` returned when the qualified search was started.
</ParamField>

## Query

<ParamField query="verdicts" type="string">
  Verdicts to return: one or more of `green`, `amber`, `red`. Repeat the parameter or separate values with commas (`verdicts=green,amber`). Default: all three. The filter changes only the `talents` array; `counts` and credits are unchanged.
</ParamField>

<ParamField query="cursor" type="string">
  `nextPageCursor` from a previous response. Omit it on the first page. A cursor is bound to the `verdicts` it was issued with; reusing it with a different filter returns `validation_error`.
</ParamField>

<ParamField query="pageSize" type="number" default="50">
  Number of talents to return, from 1 to 100.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Whether the request completed without errors.
</ResponseField>

<ResponseField name="data" type="object">
  Present when `success` is `true`.

  <Expandable title="data fields">
    <ResponseField name="castingId" type="string">
      Identifier of the qualified search.
    </ResponseField>

    <ResponseField name="status" type="string">
      One of `running`, `can_continue`, `pool_exhausted`, `failed_retryable`.
    </ResponseField>

    <ResponseField name="nextAction" type="string">
      One of `wait`, `continue`, `retry`, `done`. Computed by Kalent from the state of the search.
    </ResponseField>

    <ResponseField name="canContinue" type="boolean">
      `true` only when `nextAction` is `continue`.
    </ResponseField>

    <ResponseField name="scoringLanguage" type="string">
      Language of `recap`, criterion `title`, and criterion `result` for every talent of this search: `en` or `fr`. Resolved when the search started (from `scoringLanguage` on the start request, or from the language of the user who owns the API key) and fixed for the whole search. `null` for searches started before this field existed. See [Scoring language](/api-reference/search-talents-qualified#scoring-language).
    </ResponseField>

    <ResponseField name="counts" type="object">
      Totals for the whole search, not only the current page or the `verdicts` filter: `green`, `amber`, and `red`. `target.greens` on start and continue is a quota for that call only; these counts stay cumulative.
    </ResponseField>

    <ResponseField name="creditsCharged" type="number">
      Credits charged on this search so far, across all calls.
    </ResponseField>

    <ResponseField name="creditsRemaining" type="number">
      Credits the current call can still spend: the remaining budget of the call (`target.maxCredits` minus what its finished waves have charged), bounded by what your workspace can actually pay (credits already reserved for this call plus your available balance). `0` once the call is over. It can go back up while the call runs, because the balance is shared with your other calls and with talent search. To know what a call spent, read `creditsCharged`; do not subtract `creditsRemaining` from `target.maxCredits`. When `nextAction` is `retry` and the balance is empty, it is `0` and a continue answers `402 insufficient_api_credits` until credits are added. Not part of the webhook payloads.
    </ResponseField>

    <ResponseField name="talents" type="object[]">
      Qualified talents on this page, green first, then amber, then red.

      <Expandable title="talent fields">
        <ResponseField name="talentId" type="string">
          Talent identifier.
        </ResponseField>

        <ResponseField name="aiVerdict" type="string">
          One of `green`, `amber`, or `red`.
        </ResponseField>

        <ResponseField name="scoring" type="object">
          Evaluation result for this talent, or `null` when none is available: `recap` and `criterias`, each criterion with `title`, `result`, `status`, `evaluable`, and `references`. `recap`, `title`, and `result` are written in `scoringLanguage`; quotes in `references` stay in the profile's original language.
        </ResponseField>

        <ResponseField name="profile" type="object">
          Profile fields as on [`POST /v1/search/talents`](/api-reference/search-talents). Talents that cannot be loaded are omitted from the array.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="nextPageCursor" type="string">
      Pass this as `cursor` to load the next page with the same `verdicts`. `null` when there are no further talents.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="error" type="object">
  Present when `success` is `false`.

  <Expandable title="error fields">
    <ResponseField name="code" type="string">
      One of: `validation_error`, `casting_not_found`, `internal_error`, plus the authentication codes documented in [Authentication](/authentication).
    </ResponseField>

    <ResponseField name="message" type="string">
      Human-readable error description. For a missing search the message is `Casting not found.`
    </ResponseField>

    <ResponseField name="debugTrackingCode" type="string">
      Include this when contacting support.
    </ResponseField>
  </Expandable>
</ResponseField>

| HTTP status | Code                | When                                                                                     |
| ----------- | ------------------- | ---------------------------------------------------------------------------------------- |
| 400         | `validation_error`  | Invalid `verdicts`, `pageSize`, or a `cursor` that does not match this search and filter |
| 404         | `casting_not_found` | Unknown `castingId` for this workspace                                                   |
| 500         | `internal_error`    | Unexpected error                                                                         |

## Example

```bash theme={null}
curl "https://app.kalent.ai/api/v1/search/talents/qualified/CASTING_ID?verdicts=green&pageSize=50" \
  -H "x-api-key: YOUR_API_KEY"
```

```json theme={null}
{
  "success": true,
  "data": {
    "castingId": "3f9d2c1e-7b4a-4e8f-9c21-5d6a8b0e4f17",
    "status": "can_continue",
    "nextAction": "continue",
    "canContinue": true,
    "scoringLanguage": "en",
    "counts": { "green": 10, "amber": 4, "red": 6 },
    "creditsCharged": 40,
    "creditsRemaining": 0,
    "talents": [],
    "nextPageCursor": null
  }
}
```