> ## Documentation Index > Fetch the complete documentation index at: https://docs.support.onclarity.com/llms.txt > Use this file to discover all available pages before exploring further. # Get the failed checks of an eval run and the calls to read for them > Returns what failed in an eval run, counted by check, and picks up to `n` of the calls with failures to read: first one call for each failed check, then the calls with the most failures. "Improve from evals" shows these numbers and reads these calls. Only `passed` and `failed` verdicts count. `error`, `not_sure` and `not_relevant` verdicts are never failures; they are counted in `excluded_verdicts`. Calls that did not connect, were not judged or have no conversation are not read; they are listed in `unusable_calls`, each with a `reason` code. New codes may be added: treat an unknown one like `not_connected`. On a paused run verdicts keep arriving. Pass `verdicts_before` to count only the verdicts judged up to that moment, so two reads return the same calls. ## OpenAPI ````yaml api-reference/voice-openapi.json GET /v1/projects/{projectId}/agents/{agentId}/eval-submissions/{id}/improve-candidates openapi: 3.0.3 info: title: Clarity Voice API version: '1.0' description: >- Voice agents and their tools, outbound calls, conversations, campaigns, telephony, and evals. servers: - url: https://voice-api.onclarity.com security: - organizationApiKey: [] tags: - name: Projects description: >- The projects your organization owns. Every other resource lives in a project. - name: Agents description: Create, configure, version and publish voice agents. - name: Outbound calls description: Have a published agent phone a number now. - name: Conversations description: >- One record per call session, with its calls, recordings, transcripts and artifacts. - name: Calls description: The calls of a project, with their status, direction, timing and outcome. - name: Campaigns description: Outbound calling campaigns that phone a list of numbers on a schedule. - name: Eval suites description: >- Reusable sets of eval scenarios and test cases to measure an agent against. - name: Eval judges description: The LLM judges that score eval calls against your test cases. - name: Eval scenarios description: The simulated-caller scenarios of your eval suites. - name: Eval test cases description: The checks a judge applies to each eval call. - name: Eval submissions description: Run an eval suite against an agent and read the verdicts. - name: Phone numbers description: >- The phone numbers of a project, where their calls come from, and how agents call out from them. - name: Inbound SIP trunks description: Bring calls from your own SIP infrastructure to Clarity agents. - name: Outbound SIP trunks description: >- The SIP endpoints Clarity dials through for outbound calls from your numbers. - name: Tools description: The tools agents call during a conversation, and which agents use them. paths: /v1/projects/{projectId}/agents/{agentId}/eval-submissions/{id}/improve-candidates: parameters: - $ref: '#/components/parameters/ProjectIdPath' - name: agentId in: path required: true schema: type: string description: Agent id - name: id in: path required: true schema: type: string description: Eval submission id get: tags: - Eval submissions summary: Get the failed checks of an eval run and the calls to read for them description: > Returns what failed in an eval run, counted by check, and picks up to `n` of the calls with failures to read: first one call for each failed check, then the calls with the most failures. "Improve from evals" shows these numbers and reads these calls. Only `passed` and `failed` verdicts count. `error`, `not_sure` and `not_relevant` verdicts are never failures; they are counted in `excluded_verdicts`. Calls that did not connect, were not judged or have no conversation are not read; they are listed in `unusable_calls`, each with a `reason` code. New codes may be added: treat an unknown one like `not_connected`. On a paused run verdicts keep arriving. Pass `verdicts_before` to count only the verdicts judged up to that moment, so two reads return the same calls. operationId: getAgentEvalSubmissionImproveCandidates parameters: - name: 'n' in: query required: false description: How many calls with failures to pick. schema: type: integer minimum: 1 maximum: 200 default: 20 - name: verdicts_before in: query required: false description: Count only verdicts judged at or before this moment (ISO 8601). schema: type: string format: date-time responses: '200': description: The failed checks and the calls picked content: application/json: schema: type: object required: - submission_id - submission_name - state - 'n' - verdicts_before - tested_version - live_version - draft_version - draft_changed_since_run - failed_checks - calls_with_failures - usable_calls - calls - coverage - uncovered_test_case_ids - unusable_calls - excluded_verdicts - pending_calls properties: submission_id: type: string submission_name: type: string state: type: string enum: - not_started - in_progress - paused - failed - completed description: The run's state, as the status endpoint reports it. 'n': type: integer minimum: 1 maximum: 200 verdicts_before: type: string format: date-time nullable: true tested_version: type: object description: >- The version the run tested. `id` is null when that draft was discarded. required: - id - number - pinned_draft properties: id: type: string nullable: true number: type: integer nullable: true pinned_draft: type: boolean live_version: type: object nullable: true description: The agent's published version now; null when it has none. required: - id - number properties: id: type: string number: type: integer draft_version: type: object nullable: true description: The agent's draft now; null when it has none. required: - id - number - updated_at properties: id: type: string number: type: integer updated_at: type: string format: date-time nullable: true draft_changed_since_run: type: boolean nullable: true description: >- For a run on a draft, whether that draft was edited after the run; null otherwise. failed_checks: type: array description: >- Checks that failed in at least one call, most failures first. items: type: object required: - test_case_id - name - source - scenario_names - failed - passed - applicable - failed_call_ids properties: test_case_id: type: string name: type: string source: type: string enum: - scenario - common scenario_names: type: array items: type: string failed: minimum: 1 type: integer passed: type: integer minimum: 0 applicable: type: integer minimum: 1 description: Passed plus failed verdicts of this check. failed_call_ids: type: array items: type: string calls_with_failures: type: integer minimum: 0 usable_calls: type: integer minimum: 0 description: >- Calls with a conversation and at least one verdict other than error. calls: type: array maxItems: 200 description: The calls picked, in the order they were picked. items: type: object required: - call_id - conversation_id - scenario_id - scenario_name - silence_mode - run_index - failed - failed_test_case_ids - picked_for properties: call_id: type: string conversation_id: type: string nullable: true scenario_id: type: string nullable: true scenario_name: type: string nullable: true silence_mode: type: string nullable: true run_index: type: integer nullable: true failed: minimum: 1 type: integer failed_test_case_ids: type: array items: type: string picked_for: type: string enum: - coverage - most_failures coverage: type: object required: - covered - total properties: covered: type: integer minimum: 0 total: type: integer minimum: 0 uncovered_test_case_ids: type: array description: Failed checks that none of the picked calls fails. items: type: string unusable_calls: type: array items: type: object required: - call_id - conversation_id - scenario_id - scenario_name - reason - hangup_reason properties: call_id: type: string conversation_id: type: string nullable: true scenario_id: type: string nullable: true scenario_name: type: string nullable: true reason: type: string description: > `unsupported_caller_settings`, `region_conflict`, `deleted_draft`, `isolation_error`, `not_connected` or `not_judged`. More codes may be added. hangup_reason: type: string nullable: true excluded_verdicts: type: object required: - error - not_sure - not_relevant properties: error: type: integer minimum: 0 not_sure: type: integer minimum: 0 not_relevant: type: integer minimum: 0 pending_calls: type: integer minimum: 0 description: Calls not finished or not judged yet. example: submission_id: sub_01J9 submission_name: Booking regression 2026-10-22 14:00 state: completed 'n': 20 verdicts_before: null tested_version: id: ver_789 number: 12 pinned_draft: false live_version: id: ver_789 number: 12 draft_version: null draft_changed_since_run: null failed_checks: - test_case_id: tc_01 name: Quotes the trip total source: scenario scenario_names: - Roaming quote failed: 2 passed: 0 applicable: 2 failed_call_ids: - call_01 - call_02 calls_with_failures: 2 usable_calls: 3 calls: - call_id: call_01 conversation_id: conv_01 scenario_id: sc_01 scenario_name: Roaming quote silence_mode: 'off' run_index: 0 failed: 1 failed_test_case_ids: - tc_01 picked_for: coverage - call_id: call_02 conversation_id: conv_02 scenario_id: sc_01 scenario_name: Roaming quote silence_mode: 'off' run_index: 1 failed: 1 failed_test_case_ids: - tc_01 picked_for: most_failures coverage: covered: 1 total: 1 uncovered_test_case_ids: [] unusable_calls: - call_id: call_04 conversation_id: null scenario_id: sc_02 scenario_name: Late payment reason: not_connected hangup_reason: eval_tester_never_joined excluded_verdicts: error: 0 not_sure: 1 not_relevant: 4 pending_calls: 0 '401': $ref: '#/components/responses/Unauthorized' '404': description: >- The project, agent or eval submission does not exist, or your credential cannot see it. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Eval submission not found '422': description: >- `n` is not an integer from 1 to 200, `verdicts_before` is not a date-time, or the agent is a Voice Assist agent, which cannot take test calls (`code: AGENT_TYPE_NOT_DISPATCHABLE`). content: application/json: schema: $ref: '#/components/schemas/ValidationError' components: parameters: ProjectIdPath: name: projectId in: path required: true schema: type: string description: Project id responses: Unauthorized: description: >- No credential was sent, or the API key is invalid or revoked. A key that could not be checked at all answers 503 `AUTH_UPSTREAM_UNAVAILABLE` instead (see Errors). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Invalid or revoked token schemas: Error: type: object required: - error additionalProperties: true properties: error: type: string description: Error message code: type: string description: >- A stable machine-readable reason, present on the refusals a client may branch on. Among them: `PUBLISH_CAPABILITY_REQUIRED` (403, the credential may not change what is live), `AGENT_NOT_PUBLISHED` (409, the agent has no published version yet), `AGENT_TYPE_NOT_DISPATCHABLE` (422, a Voice Assist agent named where an agent must place a call or answer one itself — a campaign, an outbound caller ID, a dispatched call, an eval; a number's inbound dispatch rule accepts one; the body carries `agent_type` and `agent_id`), `ASSIST_FLEET_NOT_CONFIGURED` (422 on a dispatch rule naming a Voice Assist agent in a project whose LiveKit has no Voice Assist listener), `NOT_APPLICABLE_TO_AGENT_TYPE` (422, a voice-only setting written on a Voice Assist agent), `AGENT_TYPE_BOUNDARY` (409), `AGENT_TYPE_NOT_SUPPORTED` (400), `INVALID_CUSTOMER_TIMEZONE` (400, `customer_timezone` is not a time zone name; the body carries the value), `VOICE_ASSISTANT_REQUIRED` (403, the organization is not licensed for Voice Assist), `ORGANIZATION_UNAVAILABLE` (503), `REGION_PROFILE_CONFLICT` (503), `LLM_SERVICE_TIER_UNAVAILABLE` (422, an agent's processing speed is not offered by its model or not enabled for the organization; `reason` says which) and `AUTH_UPSTREAM_UNAVAILABLE` (503 on any endpoint, with `Retry-After`: the credential could not be checked right now; it was not rejected and the request was not carried out). ValidationError: type: object description: >- A validation failure. `error` is a human-readable summary; `issues` (request validation) or `details` (agent configuration validation) locate each problem. A refused processing speed answers with `error` and `code` both `LLM_SERVICE_TIER_UNAVAILABLE` and the fields `path`, `reason`, `tier`, `provider` and `model`. properties: error: type: string code: type: string description: >- A machine-readable code, on the failures that carry one: `LLM_SERVICE_TIER_UNAVAILABLE` for a processing speed the agent cannot use. message: type: string path: type: string description: >- With `LLM_SERVICE_TIER_UNAVAILABLE`: the refused field, `agent_model_config.llm_service_tier`. reason: type: string enum: - model - organization description: >- With `LLM_SERVICE_TIER_UNAVAILABLE`: `model` when the language model does not offer the speed (or the value is not a speed at all), `organization` when your organization does not have it. tier: type: string description: With `LLM_SERVICE_TIER_UNAVAILABLE`, the refused value, as text. provider: type: string description: >- With `LLM_SERVICE_TIER_UNAVAILABLE`, the agent's language model provider. model: type: string description: With `LLM_SERVICE_TIER_UNAVAILABLE`, the agent's language model. issues: type: array items: type: object properties: path: type: string description: Dotted path of the offending field code: type: string message: type: string details: type: array items: {} securitySchemes: organizationApiKey: type: http scheme: bearer description: >- Your organization API key (it starts with `anek_org_`). The same key works on the Voice API and the Support API. See [Authentication](/authentication). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.