> ## 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 Text > Execute evaluators against your agent using text-only simulation (SMS, chat, or an agent-hosted websocket). Cheaper than voice — billed at the text-simulation rate. ## OpenAPI ````yaml post /test_framework/v1/scenarios/run_scenarios_text/ 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_text/: post: tags: - Evaluators summary: Run evaluators in text / SMS / chat mode description: >- TEXT / SMS / CHAT RUN: Execute evaluators against your agent using text-only simulation (SMS, chat, or an agent-hosted websocket). Cheaper than voice — billed at the text-simulation rate. Requires a chat connection (`provider.chat_agent_details`) on the agent, or a websocket URL for `self_hosted` agents. **Run-count math:** total conversations = `len(scenarios) × frequency × max(1, len(personality_ids)) × max(1, len(test_profile_ids))`. **Concurrency:** use `concurrency_limit` to cap parallel conversations. Default: unbounded (subject to provider rate limits). **Scenario selection (pick one):** - `scenarios` — list of integer evaluator IDs (e.g. `[101, 102]`) - `tags` — select by tag - `folder_path` — select by folder path (e.g. `"Sales.Inbound"`); requires `project_id` **Websocket override:** if the agent exposes a plain websocket URL for text, pass it as `websocket_url` — this bypasses the agent's standard text-readiness check. Pass `websocket_headers` (JSON object) to override connection headers for this run — merged over the agent's configured headers, with the per-run values winning. **When to use this vs others** (pick the endpoint matching the agent's configured connection — check `aiagents_retrieve`): - `run_scenarios` — real voice / phone / SIP call - `run_scenarios_with_websockets` — each scenario carries its own websocket URL (bulk) - `run_scenarios_pipecat` — Pipecat/Daily.co WebRTC deployment **`self_hosted` agents:** agents with `assistant_provider="self_hosted"` require a websocket URL. Either pre-configure `websocket_url` on the agent, or pass it directly in this request. Without it, the run fails with `["Agent does not have a websocket URL"]`. Passing `websocket_url` here changes the result's `run_type` to `"WebSocket"` instead of `"Text"`. **Personality override:** `personality_ids` must be IDs that are already enabled for the agent's project. Check which are enabled via `aiagents_retrieve` → `enabled_personalities` field. To enable a new personality, call `aiagents_partial_update` with the updated `enabled_personalities` list before using it here. Note: enabling a personality applies project-wide, not just to one agent. Passing an ID that is not enabled returns `["Invalid personalities provided."]`. **Scheduled runs:** to run on a cron schedule, create a CronJob via `POST /test_framework/v1/cron_jobs/` with `execution_mode="text"` instead. **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'. There is no separate progress endpoint for runs. Check `failed_reasons` for infrastructure errors; check `runs[run_id].error_message` for per-run errors. operationId: scenarios-run-text_2 requestBody: content: application/json: schema: $ref: '#/components/schemas/SchemaPostRunScenariosText' examples: RunSelectedScenariosInTextMode: value: agent_id: 12 scenarios: - 101 - 102 frequency: 1 summary: Run selected scenarios in text mode RunViaAgentWebsocketURL,2×Each,3InParallel: value: agent_id: 12 scenarios: - 101 frequency: 2 websocket_url: wss://my-agent.example.com/chat concurrency_limit: 3 summary: Run via agent websocket URL, 2× each, 3 in parallel RunAFolderViaSMS: value: agent_id: 12 folder_path: Support.Billing project_id: 1376 frequency: 1 outbound_phone_number: '+14155551234' summary: Run a folder via SMS application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/SchemaPostRunScenariosText' multipart/form-data: schema: $ref: '#/components/schemas/SchemaPostRunScenariosText' 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 examples: - id: 274 status: pending scenario: 1 number: null inbound_number: '+11234567890' scenario_name: Customer Support Call (Agent Inbound = True) test_profile_data: null - id: 275 status: pending scenario: 2 number: '+11234567890' inbound_number: null scenario_name: Outbound Sales Call (Agent Inbound = False) test_profile_data: null 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: SchemaPostRunScenariosText: type: object description: >- Schema for the run_scenarios_text endpoint, which runs scenarios in text mode (SMS, chat, or agent-hosted websocket). properties: agent_id: type: integer description: ID of the agent to run evaluators for assistant_id: type: string writeOnly: true description: | Alternative to agent ID - the assistant ID to use for this scenario Example: `"asst_1234567890"` name: type: string description: Label text for result scenarios: type: array items: type: integer description: > List of evaluator IDs to run. Either scenarios, tags, or folder_path must be provided. Example: `[11, 22, 33]` To run evaluators by tag or folder, use the `tags` or `folder_path` fields instead. tags: type: array items: type: string description: > List of tags to filter evaluators to run. Either evaluators or tags must be provided. Example: `["tag1", "tag2", "tag3"]` folder_path: type: string description: > Dot-separated folder path to select evaluators from (e.g. `"Sales.Inbound"`). Mutually exclusive with `scenarios` and `tags`. Requires `project_id`. project_id: type: integer description: > Project ID. Required when using `folder_path` (or when passing a folder path string via `scenarios`). Example: `1376` frequency: type: integer minimum: 1 default: 1 description: | The number of times each evaluator will run Example: `1` websocket_url: type: string description: >- If provided, the simulated caller connects to this websocket URL instead of using the agent's configured text/SMS gateway. Use for agents that expose a websocket endpoint for text testing. Bypasses the normal `agent.can_run_as_text()` check. websocket_headers: type: object additionalProperties: {} description: >- Headers to send on the websocket connection for this run. Merged over the agent's configured `websocket_headers` — keys provided here win. System `X-VOCERA-*` headers cannot be overridden. personality_ids: type: - array - 'null' items: type: integer description: >- List of personality IDs to override for this run. If not provided, uses the scenario's default personality. test_profile_ids: type: - array - 'null' items: type: integer description: >- List of test profile IDs to override for this run. If not provided, uses the scenario's default test profile. agent_number: type: string description: > Override the phone number from which the agent under test receives the call during outbound runs. This allows overriding the default agent contact number for testing purposes. Example: "+1234567890" outbound_phone_number: type: string description: | Override the phone number to use for outbound calls. Example: "+1234567890" concurrency_limit: type: integer minimum: 1 description: > Cap on the number of evaluator runs executed in parallel. Default: unbounded (subject to your provider's rate limits). Use this to avoid hitting provider rate limits on large frequency or folder runs. Example: `5` 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. ````