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

# Continue qualified search

> Authorise a new credit budget on a qualified search, or retry a failed wave.

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

Continue a qualified search after [`GET /v1/search/talents/qualified/{castingId}`](/api-reference/get-qualified-search) returned `nextAction` `continue` or `retry`.

A continue is a new **call**: it authorises a new quota, `target` (`target.greens` and a credit cap `target.maxCredits`), and Kalent then analyses waves on its own until this call finds that many greens, the cap of this call, or the end of the talent pool. You do not call continue for each wave, only to authorise more spending. See the [qualified search overview](/api-reference/qualified-search-overview) for calls, waves, and credits.

* If `nextAction` is `continue`, Kalent opens a new call that looks for `target.greens` **new** greens. Greens already returned do not count toward this call. The response is **202**.
* If `nextAction` is `retry`, Kalent retries the failed wave with the **remaining budget of the same call**, capped by your balance. The call index does not change and no new budget is opened. If that call had already found its `target.greens`, nothing is retried: the call is closed and the response is **200** with `status` `can_continue`; the next continue opens a new call.
* If `nextAction` is `wait` (`status` `running`), the request returns `casting_run_in_progress`.
* If `nextAction` is `done` (`status` `pool_exhausted`), the request returns `casting_pool_exhausted`.

When a call is accepted the response is **202** and `status` is `running`. Poll GET while `nextAction` is `wait`, or wait for the end-of-call webhook.

Two API credits are charged for each talent that receives a verdict in the new call. Talents already billed on a failed wave are not charged again when that wave is retried.

The `X-Api-Credits-Remaining` header is your workspace balance right after the request, that is after Kalent reserved `min(balance, target.maxCredits)` for the new call (or the remaining budget of the retried call). Unused reserved credits come back when each wave ends. GET does not send this header.

## Path

<ParamField path="castingId" type="string" required>
  The `castingId` of the qualified search.
</ParamField>

## Request body

The body is optional. An empty body is valid: it reuses the stored `target`, `webhook`, and `customParams`. The [scoring language](/api-reference/search-talents-qualified#scoring-language) is fixed at start and cannot be sent here: a body with `scoringLanguage` returns `validation_error`.

<ParamField body="target" type="object">
  Quota of **this call**. Each field is independent: a field you omit keeps its stored value, so `{ "target": { "greens": 20 } }` changes the green quota and leaves the credit cap as it was. Omitting `target` keeps both. On a retry the values are stored for the next call, but the retry itself keeps the quota and the remaining budget of the failed call.

  <Expandable title="target fields">
    <ParamField body="target.greens" type="number">
      Green talents to find during **this call**. Integer from 1 to 50. It is not added to greens already found.
    </ParamField>

    <ParamField body="target.maxCredits" type="number">
      Credit cap for **this call only**. Even integer from 2 to 300. It is not added to previous calls: after a start capped at 60 credits, a continue with `maxCredits: 100` may spend up to 100 new credits on this continue, not 160 in total.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="webhook" type="object">
  Omitted: the `webhook` stored on the search is reused. Provided: `url` replaces the stored URL for this call and the following ones; `verdicts` replaces the stored verdicts only when sent, otherwise they are kept. Payload and headers are documented on [`POST /v1/search/talents/qualified`](/api-reference/search-talents-qualified#webhooks).

  <Expandable title="webhook fields">
    <ParamField body="webhook.url" type="string" required>
      HTTPS URL that receives the events. Must not be `localhost` or a private network address.
    </ParamField>

    <ParamField body="webhook.verdicts" type="string[]">
      Verdicts for which a `talent_judged` event is sent. One to three of `green`, `amber`, `red`. Omitted: the stored verdicts are kept.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="customParams" type="object">
  Optional JSON object with string keys, echoed on webhook payloads. Replaces the stored object when provided. The JSON serialization must be at most 4096 bytes.
</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">
      `running` when a call is accepted (202).
    </ResponseField>

    <ResponseField name="nextAction" type="string">
      `wait` when a call is accepted. Otherwise the current `nextAction`, as on GET.
    </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`, `insufficient_api_credits`, `casting_not_found`, `casting_run_in_progress`, `casting_pool_exhausted`, `internal_error`, plus the authentication codes documented in [Authentication](/authentication).
    </ResponseField>

    <ResponseField name="message" type="string">
      Human-readable error description.
    </ResponseField>

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

    <ResponseField name="available" type="number">
      Present when `code` is `insufficient_api_credits`.
    </ResponseField>

    <ResponseField name="required" type="number">
      Present when `code` is `insufficient_api_credits`.
    </ResponseField>
  </Expandable>
</ResponseField>

| HTTP status | Code                       | When                                                                                                                                                                                          |
| ----------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400         | `validation_error`         | Invalid body (including an odd or out-of-range `target.maxCredits`, a `target.greens` outside 1–50, a `webhook` without a valid HTTPS `url`, or a `scoringLanguage`, which is fixed at start) |
| 402         | `insufficient_api_credits` | Fewer than 2 credits available                                                                                                                                                                |
| 404         | `casting_not_found`        | Unknown `castingId` for this workspace                                                                                                                                                        |
| 409         | `casting_run_in_progress`  | A call is already running                                                                                                                                                                     |
| 409         | `casting_pool_exhausted`   | There are no more matching talents                                                                                                                                                            |
| 500         | `internal_error`           | Unexpected error                                                                                                                                                                              |

## Example

```bash theme={null}
curl -X POST https://app.kalent.ai/api/v1/search/talents/qualified/CASTING_ID/continue \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ "target": { "greens": 20, "maxCredits": 100 } }'
```

```json theme={null}
{
  "success": true,
  "data": {
    "castingId": "3f9d2c1e-7b4a-4e8f-9c21-5d6a8b0e4f17",
    "status": "running",
    "nextAction": "wait"
  }
}
```