> ## Documentation Index
> Fetch the complete documentation index at: https://dialnexa.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Start Agent Evaluation Run

> Start an agent evaluation run to queue test conversations against a saved draft or published version.

Changes state - verify before retry

Start an agent evaluation run to queue test conversations against a saved draft or published version. The response acknowledges queued work; it does not mean the tests passed.

## Start Agent Evaluation Run

Save tests with [Create Agent Evaluation Test](https://dialnexa.com/docs/api-reference/v1/eval-tests/create.md). Every selected test must belong to this agent, and at least one must be enabled. The selected target must have a saved version. Only one queued or running run may be active for an agent.

## Minimal request

Send non-empty `test_ids`, `repeat` from 1 to 20, and `target` set to `draft` or `published`. `draft` selects the newest saved version. `prompt_override` applies only to draft runs.

```json theme={null}
{"test_ids": ["k7x2m9q4wz1abc"], "repeat": 1, "target": "draft"}
```

Replace `k7x2m9q4wz1abc` with an actual saved test ID.

## Evaluation run settings and side effects

* `mode` defaults to `text`, which skips speech recognition and synthesis. `voice` runs each conversation as a browser-style test call; no phone number is dialled. Evaluation test calls are not charged to the workspace wallet.
* `llm` defaults to `primary`, keeping the version configuration and its fallback. `secondary` uses the enabled fallback model alone. `both` queues each test against both models and doubles the conversation count for the same repeat setting. Secondary and both require an enabled fallback model.
* Disabled tests are excluded. The returned `total` is the number of queued conversations after model selection and repeats.
* Simulations can cover the primary and secondary languages in one conversation. `primary_language_only` in the saved test configuration limits a simulation to the primary language.
* Tools default to mocked execution: every function tool is mocked, and a tool with no mock response returns an error instead of running. `mock_strategy: none` runs all tools for real, `selected` runs the tools not selected for mocking for real, and `mock_fallback: real` runs tools that have no mock response. Real execution performs the external action, so review `mock_strategy`, `mock_fallback`, and `mocks` before running.
* `trigger` defaults to `manual`. `pre_publish` labels the run; it does not publish the agent or impose a publish gate.

## Verify the result

A `201` response contains the queued run in `data`. Store `data.id` and poll [Get Agent Evaluation Run](https://dialnexa.com/docs/api-reference/v1/eval-runs/get.md) until it reaches a terminal status. Check `failed`, `errored`, and conversation outcomes before treating it as a pass.

## Errors and recovery

`400` means a selected test is missing or belongs to another agent, every selected test is disabled, the target has no version, or secondary-model evaluation is unavailable. `404` means the agent is unavailable. `409` means an active run already exists: poll that run instead. A lost response may still have queued work. List runs before retrying; another successful request creates another run and repeats its test work and any configured real tool actions.

Missing, expired, or invalid API credentials return `401`. See [API authentication](https://dialnexa.com/docs/api-reference/api-fundamentals.md#authenticate-dialnexa-api-requests).

## Related endpoints

* [List Agent Evaluation Tests](https://dialnexa.com/docs/api-reference/v1/eval-tests/list.md)
* [Create Agent Evaluation Test](https://dialnexa.com/docs/api-reference/v1/eval-tests/create.md)
* [Get Agent Evaluation Run](https://dialnexa.com/docs/api-reference/v1/eval-runs/get.md)
* [Get Agent Evaluation Conversation](https://dialnexa.com/docs/api-reference/v1/eval-runs/conversation.md)


## OpenAPI

````yaml POST /v1/agents/{id}/test-runs
openapi: 3.0.0
info:
  title: DialNexa API
  description: Public `/v1` REST API for the DialNexa voice AI platform.
  version: 1.0.0
servers:
  - url: https://api.dialnexa.com
    description: DialNexa production API
security:
  - bearer: []
tags:
  - name: Agents
  - name: Batch Calls
  - name: Calls
  - name: Knowledge Base
  - name: Languages
  - name: LLMs
  - name: Phone Numbers
  - name: Organization Folders
  - name: Transcribers
  - name: Webhooks
  - name: Voices
  - name: Workflows
  - name: Workflow Leads
  - name: Authentication
  - name: Agent Builder
  - name: Agent Evaluations
paths:
  /v1/agents/{id}/test-runs:
    post:
      tags:
        - Agent Evaluations
      summary: Start Agent Evaluation Run
      description: >-
        Queues test conversations for the selected saved agent version.
        Evaluation test calls are not charged to the workspace wallet; real tool
        execution can still cause external actions. Poll Get Agent Evaluation
        Run for completion; retrying after a completed run creates a new run.
      operationId: startAgentEvalRun
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Agent ID from List Agents.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartAgentEvalRun'
            examples:
              request:
                value:
                  test_ids:
                    - k7x2m9q4wz1abc
                  repeat: 1
                  target: draft
      responses:
        '201':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - error
                  - statusCode
                  - message
                  - data
                  - timestamp
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  error:
                    type: boolean
                    enum:
                      - false
                  statusCode:
                    type: integer
                    example: 201
                  message:
                    type: string
                    example: Success
                  data:
                    $ref: '#/components/schemas/AgentEvalRun'
                  timestamp:
                    type: string
                    format: date-time
        '400':
          description: >-
            Invalid test definition or run selection. For runs, check test
            ownership, enabled tests, target version and secondary-model
            availability.
        '401':
          description: Missing, expired or invalid API key.
        '404':
          description: Agent, test, run or conversation was not found in this workspace.
        '409':
          description: >-
            A run is already in progress for this agent. Poll it before starting
            another.
      security:
        - bearer: []
components:
  schemas:
    StartAgentEvalRun:
      type: object
      properties:
        test_ids:
          type: array
          items:
            type: string
          minItems: 1
          description: Saved test IDs belonging to this agent. Disabled tests are excluded.
        repeat:
          type: integer
          minimum: 1
          maximum: 20
        target:
          type: string
          enum:
            - draft
            - published
          description: >-
            draft selects the newest saved version; published selects the
            published version.
        prompt_override:
          type: string
          description: >-
            Optional editor prompt for draft runs. Ignored for a published
            target.
        trigger:
          type: string
          enum:
            - manual
            - pre_publish
          default: manual
          description: >-
            Run label. pre_publish does not publish the agent or block
            publishing.
        mode:
          type: string
          enum:
            - text
            - voice
          default: text
          description: >-
            Text skips speech recognition and synthesis. Voice uses the audio
            test-call path.
        llm:
          type: string
          enum:
            - primary
            - secondary
            - both
          default: primary
          description: >-
            Primary keeps the version configuration, including fallback.
            Secondary uses the enabled fallback model alone. Both queues each
            test for each model; requires an enabled fallback model. Other
            settings stay the same.
      required:
        - test_ids
        - repeat
        - target
    AgentEvalRun:
      type: object
      properties:
        id:
          type: string
        agent_id:
          type: string
        status:
          type: string
          enum:
            - queued
            - running
            - completed
            - cancelled
        target:
          type: string
          enum:
            - draft
            - published
        version_number:
          type: integer
        trigger:
          type: string
          enum:
            - manual
            - pre_publish
        repeat:
          type: integer
        mode:
          type: string
          enum:
            - text
            - voice
        llm:
          type: string
          enum:
            - primary
            - secondary
            - both
        test_ids:
          type: array
          items:
            type: string
        passed:
          type: integer
        failed:
          type: integer
        errored:
          type: integer
        total:
          type: integer
        cost_inr:
          type: number
          nullable: true
        duration_ms:
          type: integer
          nullable: true
        insights:
          type: object
          additionalProperties: true
          nullable: true
        insights_status:
          type: string
          nullable: true
          enum:
            - pending
            - ready
            - failed
            - null
        created_by_name:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        finished_at:
          type: string
          format: date-time
          nullable: true
      required:
        - id
        - agent_id
        - status
        - target
        - mode
        - llm
        - test_ids
        - total
  securitySchemes:
    bearer:
      scheme: bearer
      type: http

````

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