> ## 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 (API Chat) > Start API chat runs you drive turn-by-turn over REST. No chat provider needs to be configured. ## OpenAPI ````yaml post /test_framework/v1/scenarios/run_scenarios_api_chat/ 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_api_chat/: post: tags: - Evaluators summary: Start customer-driven (API chat) evaluator runs description: >- API CHAT RUN (pull mode): open one or more chat conversations that YOU drive turn-by-turn over REST — Cekura plays the simulated user, you play the agent under test. No agent connection is dialed; there is no server-side conversation loop, so a conversation can span minutes or up to an hour with turns arbitrarily far apart. **Run-count:** total conversations = `len(scenarios) × frequency`. **Driving each run** (the response `result.runs[].id` are the run IDs): 1. If the scenario has a first message, the simulated user speaks first — read it from the run transcript. Otherwise you speak first. 2. `POST /runs/{run_id}/chat/` with your agent's message → returns a `turn_id`. 3. Poll `GET /runs/{run_id}/chat/{turn_id}/` until `status` is `ready` to read the reply. 4. Repeat until `ended` is true, or call `POST /runs/{run_id}/end-chat/`. `timeout` is the overall run timeout: each conversation is finalized and scored automatically once it elapses (defaults to the project's duration, capped at 1 hour). operationId: scenarios-run-api-chat_2 requestBody: content: application/json: schema: $ref: '#/components/schemas/SchemaPostRunScenariosApiChat' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/SchemaPostRunScenariosApiChat' multipart/form-data: schema: $ref: '#/components/schemas/SchemaPostRunScenariosApiChat' responses: '200': content: application/json: schema: $ref: '#/components/schemas/RunScenarioResult' description: '' '400': content: application/json: schema: type: object properties: field_name: type: array items: type: string description: '' security: - api_key: [] components: schemas: SchemaPostRunScenariosApiChat: type: object description: >- Schema for the run_scenarios_api_chat endpoint (customer-driven pull mode). Same selection fields as the other run endpoints (agent_id, scenarios/tags/ folder_path, frequency, personality/test-profile overrides) plus `timeout`. 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` personality_ids: type: - array - 'null' items: type: integer description: >- Personality IDs to override for this run. Defaults to each scenario's personality. test_profile_ids: type: - array - 'null' items: type: integer description: >- Test-profile IDs to override for this run. Defaults to each scenario's test profile. timeout: type: - integer - 'null' maximum: 3600 minimum: 1 description: >- Overall run timeout in seconds — the whole conversation's max lifetime (NOT a per-message timeout). When it elapses the run is finalized and scored automatically. Defaults to the project's configured duration. Capped at 3600 (1 hour). RunScenarioResult: type: object properties: id: type: integer readOnly: true description: | Unique identifier for the Result Example: `123` name: type: string description: | Name of the Result Example: `"Test Result 1"` maxLength: 255 agent: type: integer readOnly: true description: | ID of the AI agent that was tested Example: `123` agent_inbound: type: boolean readOnly: true description: > Whether the agent is configured for inbound calls (true) or outbound calls (false) Example: `true` or `false` status: enum: - running - completed - failed - pending - in_progress - evaluating - in_queue - timeout - cancelled - scaling_up type: string x-spec-enum-id: 623e22fc1eb17833 default: pending description: |- Current status of the result * `running` - Running * `completed` - Completed * `failed` - Failed * `pending` - Pending * `in_progress` - In Progress * `evaluating` - Evaluating * `in_queue` - In Queue * `timeout` - Timeout * `cancelled` - Cancelled * `scaling_up` - Scaling Up success_rate: type: number format: double default: 0 description: Success rate of the test runs as a decimal (0.0 to 1.0) run_as_text: type: boolean default: false description: | Whether this test was run in text mode instead of voice mode Example: `true` or `false` is_cronjob: type: string readOnly: true description: | Whether this result was created by a scheduled cronjob Example: `true` or `false` runs: type: object additionalProperties: {} description: >- Run summaries for this result. For full run data including transcripts and metric scores, fetch the result detail endpoint — there `runs` is a dict keyed by run ID. readOnly: true created_at: type: string format: date-time readOnly: true description: | Timestamp when this test result was created Example: `2021-01-01 00:00:00` updated_at: type: string format: date-time readOnly: true description: Timestamp when this test result was last updated required: - name 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. ````