> ## Documentation Index > Fetch the complete documentation index at: https://docs.cekura.ai/llms.txt > Use this file to discover all available pages before exploring further. # Run External Scenarios Voice > VOICE RUN: Execute evaluators against your agent using a real voice / phone / SIP call. This is the primary 'run your evaluators' endpoint for voice-mode testing. Requires `telephony.phone_number` configured on the agent (any provider). ## OpenAPI ````yaml post /test_framework/v1/scenarios-external/run_scenarios_json/ openapi: 3.1.0 info: title: Cekura API version: v1 description: >- Complete API documentation for the Cekura platform. This API provides endpoints for testing, observing, and evaluating AI voice agents — including managing agents, running evaluators, defining metrics, and analyzing call quality. servers: - url: https://api.cekura.ai security: [] paths: /test_framework/v1/scenarios-external/run_scenarios_json/: post: tags: - Evaluators summary: Run test cases from a JSON spec file description: >- Run agent test cases straight from a JSON spec, without creating evaluators. Keep the spec in your repository and post it from CI. The spec describes only what to test. Pick the target with `agent_id` and `channel` on the request — `voice` for a phone call (default), `text` for chat, or `elevenlabs`, `livekit_v2`, or `pipecat_v2` for the matching WebRTC connection — so one file runs unchanged against any agent or environment. LiveKit and Pipecat connection overrides belong in the request's `livekit_data` or `pipecat_data`, never in the spec. Pass `dry_run=true` to validate only: the response describes the run that would happen (test cases, total runs, estimated cost) and nothing is created or charged. Use that on every commit, and the real call on the branches you want tested. Every problem in a spec is reported at once, keyed by its location in the file (for example `scenarios[3].metrics[1]`). Metrics must already exist and be enabled for the target agent; personalities and test profiles can be referenced by ID or defined inline. Fetch the schema this endpoint accepts from `scenarios_json_schema`. **Cost:** voice- or text-simulation rate per run. Test cases from a spec are removed automatically once no run needs them. operationId: scenarios-run-json parameters: - in: query name: dry_run schema: type: boolean description: Validate and price the spec without running or charging anything. requestBody: content: application/json: schema: $ref: '#/components/schemas/TestSuiteSpecUpload' examples: RunASpec: value: agent_id: 12 channel: voice spec: version: '1' scenarios: - name: Refund happy path instructions: You are a customer whose order arrived damaged. expected_outcome: The agent confirms a refund. metrics: - greeting_by_name personality: 3 test_profile: agent_variables: order_id: ORD-4471 summary: Run a spec application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/TestSuiteSpecUpload' multipart/form-data: schema: $ref: '#/components/schemas/TestSuiteSpecUpload' responses: '200': content: application/json: schema: type: object properties: id: type: integer description: ID of the result agent: type: integer description: ID of the agent status: type: string enum: - pending - running - completed - failed description: Status of the result run_as_text: type: boolean description: Whether the scenario ran as text or not example: false runs: type: array items: type: object properties: id: type: integer description: ID of the run status: type: string enum: - pending - running - completed - failed description: Status of the run scenario: type: integer description: ID of the scenario number: type: string description: >- For outbound runs (agent.inbound=False). The given number that must be called from the phone number configured in the cekura agent. example: '+11234567890' inbound_number: type: - string - 'null' description: >- For inbound runs (agent.inbound=True). The agent's configured phone number will receive calls from this number. example: '+11234567890' scenario_name: type: string description: Name of the scenario test_profile_data: type: - object - 'null' description: >- Details of the test profile associated with this run scenario outbound_dial_window_opens_at: type: - string - 'null' format: date-time description: >- When the outbound dial window opened (run transitioned to pending/waiting-for-call). Null until dispatched. outbound_dial_window_seconds: type: - integer - 'null' description: Duration of the outbound dial window in seconds. outbound_dial_window_closes_at: type: - string - 'null' format: date-time description: >- Deadline by which your agent must dial the outbound number (opens_at + outbound_dial_window_seconds). Dials after this are dropped and the run returns status: timeout. examples: - id: 274 status: pending scenario: 1 number: null inbound_number: '+11234567890' scenario_name: Customer Support Call (Agent Inbound = True) test_profile_data: null outbound_dial_window_opens_at: null outbound_dial_window_seconds: null outbound_dial_window_closes_at: null - id: 275 status: pending scenario: 2 number: '+11234567890' inbound_number: null scenario_name: Outbound Sales Call (Agent Inbound = False) test_profile_data: null outbound_dial_window_opens_at: '2026-06-24T10:47:30Z' outbound_dial_window_seconds: 300 outbound_dial_window_closes_at: '2026-06-24T10:52:30Z' created_at: type: string format: date-time example: '2025-02-25T21:00:01.990052Z' description: '' '400': content: application/json: schema: type: object properties: field_name: type: array items: type: string description: '' security: - oauth2: [] - supabase_session: [] - api_key: [] components: schemas: TestSuiteSpecUpload: type: object description: >- Accepts a spec as a JSON body or an uploaded file. CI posts JSON directly; the dashboard uploads the same file the customer has in their repo. Both land in ``spec``. properties: spec: description: The test-suite spec. Use this when posting JSON directly. file: type: string format: uri description: A .json spec file. Use this instead of 'spec' for uploads. agent_id: type: integer description: >- Agent to test. Overrides 'agent_id' in the spec, letting one spec file run against several environments. name: type: string description: Label for this run. Defaults to the spec's suite name. maxLength: 255 channel: enum: - voice - text - elevenlabs - livekit_v2 - pipecat_v2 type: string x-spec-enum-id: 3bf42909f82c4c98 description: >- How to reach the agent: 'voice' for a phone call (the default), 'text' for chat, 'elevenlabs' for an ElevenLabs WebRTC session, or 'livekit_v2' or 'pipecat_v2' for their respective WebRTC sessions. * `voice` - voice * `text` - text * `elevenlabs` - elevenlabs * `livekit_v2` - livekit_v2 * `pipecat_v2` - pipecat_v2 livekit_data: type: object additionalProperties: {} description: >- Optional LiveKit overrides. These apply only to this run and are not part of the portable test-suite spec. pipecat_data: type: object additionalProperties: {} description: >- Optional Pipecat Cloud overrides. These apply only to this run and are not part of the portable test-suite spec. securitySchemes: oauth2: type: http scheme: bearer bearerFormat: JWT description: OAuth access token issued by Cekura for connected apps. supabase_session: type: http scheme: bearer bearerFormat: JWT description: Cekura dashboard session token. Not a customer API credential. api_key: type: apiKey in: header name: X-CEKURA-API-KEY description: >- API Key Authentication. It should be included in the header of each request. ````