---
title: "Start Test Run"
method: POST
path: "/voice/testing/{agentId}/run"
tags: ["Voice Agent Testing"]
---

# Start Test Run

`POST /voice/testing/{agentId}/run`

## Request

- Base URL: `https://api.speakai.co/v1`
- URL: `https://api.speakai.co/v1/voice/testing/{agentId}/run`
- Auth: API key in header `x-speakai-key` and API key in header `x-access-token`

### Start Test Run

Requires the OWNER or ADMIN role. **The live execution engine is not wired up yet.** These endpoints create and transition the run record — `queued`, `running`, `paused`, `completed`, `cancelled`, `budget_exceeded` — but nothing here drives a simulated conversation against the agent. A run created with `POST /run` stays `queued` until something else (not yet built) advances it; `scenarioResults` stays empty and `overallScore` stays 0.

Rejects with 409 if the agent has no test suite, the suite has no enabled scenarios, or an active run (`queued`/`running`/`paused`) already exists for this agent — only one run can be active per agent at a time.

## Path parameters

- `agentId` string, required

## Response `201`

Created

- object
  - `status` 'success'
  - `data` object
    - `run` object
      - `_id` string: MongoDB document id, included because every document has one; use runId to identify it.
      - `runId` string
      - `suiteId` string
      - `agentId` string
      - `companyId` string
      - `status` 'queued' | 'running' | 'paused' | 'completed' | 'failed' | 'cancelled' | 'budget_exceeded'
      - `trigger` 'manual' | 'kb_update' | 'instruction_save' | 'scheduled'
      - `currentScenarioIndex` integer
      - `totalScenarios` integer
      - `scenarioResults` object[]: Populated as the execution engine appends results. Empty on a run that never left queued.
      - `overallScore` number
      - `passedCount` integer
      - `failedCount` integer
      - `totalCount` integer
      - `totalCost` number
      - `isRegression` boolean
      - `baselineScore` number, nullable
      - `scoreDelta` number, nullable
      - `recommendations` object[]
      - `startedAt` string, date-time
      - `completedAt` string, date-time, nullable
      - `failureReason` string, nullable

## Other responses

- `403`: Caller's role is not OWNER or ADMIN
- `404`: Agent, run, or recommendation not found
- `409`: Conflict — no test suite configured, no enabled scenarios, an active run already exists, or the transition is not valid from the run's current status

---

[API](https://skmtc.dev/speakai/apis/speak-ai-api.md) · [All operations](https://skmtc.dev/speakai/apis/speak-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/speakai/apis/speak-ai-api/revisions/52d777e6d46e?raw)