> ## 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 Evaluator Websocket > Execute evaluators where each scenario carries its own websocket URL. Useful when you have a fleet of agents or stateful websocket sessions to test in a single batch. ## OpenAPI ````yaml post /test_framework/v1/scenarios/run_scenarios_with_websockets/ 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/run_scenarios_with_websockets/: post: tags: - Evaluators summary: Run evaluators against per-scenario websocket URLs (bulk) description: >- WEBSOCKET RUN (per-scenario URLs, bulk): Execute evaluators where each scenario carries its own websocket URL. Useful when you have a fleet of agents or stateful websocket sessions to test in a single batch. **Run-count:** total conversations = `len(scenarios) × frequency`. (Personality and test-profile multipliers are not supported on this endpoint.) **`frequency` is required** on this endpoint (no default). **When to use this vs others** (pick the endpoint matching the agent's configured connection — check `aiagents_retrieve`): - `run_scenarios_text` — single websocket URL or SMS/chat mode (simpler) - `run_scenarios` — real voice / phone / SIP call - `run_scenarios_pipecat` — Pipecat/Daily.co WebRTC deployment **Polling for completion:** the response contains a `result.id` with `status: 'running'`. Poll `GET /test_framework/v1/results/{result_id}/` until `status` is 'completed' or 'failed'. **Known limitation:** `result.run_type` may show 'Text' instead of 'WebSocket' for runs triggered via this endpoint — this is a display issue only and does not affect execution. operationId: scenarios-run-websocket_2 requestBody: content: application/json: schema: $ref: '#/components/schemas/RunScenariosWithWebsockets' examples: Per-scenarioWebsocketURLs: value: agent: 12 frequency: 1 scenarios: - scenario: 101 websocket_url: wss://agent-a.example.com/chat - scenario: 102 websocket_url: wss://agent-b.example.com/chat summary: Per-scenario websocket URLs application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/RunScenariosWithWebsockets' multipart/form-data: schema: $ref: '#/components/schemas/RunScenariosWithWebsockets' required: true responses: '201': 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: - api_key: [] components: schemas: RunScenariosWithWebsockets: type: object properties: agent: type: - integer - 'null' description: Agent to use. Required if none of the scenarios have an agent. scenarios: type: array items: $ref: '#/components/schemas/ScenarioWithWebsocket' description: >- List of scenario+websocket pairs. Each element must be an object with two keys: `scenario` (integer evaluator ID) and `websocket_url` (string, ws:// or wss:// URL). Example: [{"scenario": 101, "websocket_url": "wss://agent-a.example.com/chat"}, {"scenario": 102, "websocket_url": "wss://agent-b.example.com/chat"}] frequency: type: integer maximum: 100 minimum: 1 description: Frequency to run mock_tool_names: type: - array - 'null' items: type: string description: >- Names of mock tools to activate for this run. Omit (or send null) to mock every tool configured on the agent; send an empty list to mock none so every tool keeps its original endpoint; send specific names to mock only those. Tools that belong to an MCP server should be selected via the MCP server's name or key, which mocks all of that server's tools as one unit. Legacy MCP sub-tool names are accepted as aliases for the whole parent MCP. required: - frequency - scenarios ScenarioWithWebsocket: type: object properties: scenario: type: integer description: Integer ID of the evaluator (scenario) to run. websocket_url: type: string description: >- WebSocket URL for this specific scenario (must start with ws:// or wss://). Overrides the agent-level websocket_url for this run only. required: - scenario securitySchemes: api_key: type: apiKey name: X-CEKURA-API-KEY in: header description: >- API Key Authentication. It should be included in the header of each request. ````