---
title: "Run evaluators against a LiveKit agent (project credentials, v2)"
method: POST
path: "/test_framework/v1/scenarios/run_scenarios_livekit_v2/"
tags: ["Evaluators"]
---

# Run evaluators against a LiveKit agent (project credentials, v2)

`POST /test_framework/v1/scenarios/run_scenarios_livekit_v2/`

## Request

- Base URL: `https://api.cekura.ai`
- URL: `https://api.cekura.ai/test_framework/v1/scenarios/run_scenarios_livekit_v2/`
- Auth: one of:
  - API key in header `X-CEKURA-API-KEY`
  - HTTP bearer
  - HTTP bearer

LIVEKIT VOICE RUN (project credentials, v2): Execute evaluators against a LiveKit agent using credentials configured at the project (or agent) level. Cekura creates the rooms; you don't pass URLs per-scenario. Requires `livekit_api_key`, `livekit_data.api_secret`, and `livekit_data.url` on the agent or project.

**Cost:** voice-simulation rate per run.
**Run-count math:** total runs = `len(scenarios) × frequency`.

**Per-request `room_config` override** is allowed; merges over agent defaults.

**When to use this vs others** (pick the endpoint matching the agent's configured connection — check `aiagents_retrieve`):
- `scenarios_run_voice` — phone / SIP voice run
- `scenarios_run_pipecat_v2` — Pipecat Cloud (project credentials, v2)
- `scenarios_run_websocket` — JSON/text WebSocket runs

## Request body

- RunLivekitScenarios
  - `name` string, nullable: Optional name for the scenario result
  - `frequency` integer: Frequency to run
  - `scenarios` LivekitScenario[], required
    - `scenario` integer, required
    - `publish_data_message` unknown
  - `agent` integer, nullable: Agent to use. Required if none of the scenarios have an agent.
  - `personality_ids` integer[], nullable: List of personality IDs to override for this run. If not provided, uses the scenario's default personality.
  - `test_profile_ids` integer[], nullable: List of test profile IDs to override for this run. If not provided, uses the scenario's default test profile.
  - `mock_tool_names` string[], nullable: 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.
  - `livekit_data` LivekitRunDataOverride: Per-run LiveKit overrides. Credentials (api_key/api_secret) are never taken here — they are read from the agent/project ProviderCredential.
    - `config` unknown
    - `agent_name` string, nullable: LiveKit agent name for explicit dispatch. Overrides the agent/project saved agent_name.
    - `url` string, nullable: LiveKit server URL override. Falls back to the agent/project saved url when omitted.
  - `concurrency_limit` integer, nullable: Optional cap on how many of this run's calls execute concurrently.
  - `calls_per_second` number, double, nullable: Most calls started per second for this run, a number from 0.1 to 4 (e.g. 0.5 starts one call every 2 seconds). Leave unset for no limit.
  - `personality_id` integer, nullable: Single personality ID override. Merged into personality_ids; prefer personality_ids for multiple.
  - `test_profile_id` integer, nullable: Single test profile ID override. Merged into test_profile_ids; prefer test_profile_ids for multiple.

## Response `200`

- object
  - `id` integer: ID of the result
  - `agent` integer: ID of the agent
  - `status` 'running' | 'completed' | 'failed' | 'pending' | 'in_progress' | 'evaluating' | 'in_queue' | 'timeout' | 'cancelled' | 'scaling_up': Status of the result. Poll until it is `completed`, `failed`, `timeout` or `cancelled`. It stays non-terminal until every run has ended, then becomes `completed` if any run completed — even if runs failed their checks or others errored.
  - `run_as_text` boolean: Whether the scenario ran as text or not
  - `runs` object[]
    - `id` integer: ID of the run
    - `status` 'running' | 'completed' | 'failed' | 'pending' | 'in_progress' | 'evaluating' | 'in_queue' | 'timeout' | 'cancelled' | 'scaling_up': Status of the run
    - `scenario` integer: ID of the scenario
    - `number` string: For outbound runs (agent.inbound=False). The given number that must be called from the phone number configured in the cekura agent.
    - `inbound_number` string, nullable: For inbound runs (agent.inbound=True). The agent's configured phone number will receive calls from this number.
    - `scenario_name` string: Name of the scenario
    - `test_profile_data` object, nullable: Details of the test profile associated with this run scenario
    - `outbound_dial_window_opens_at` string, date-time, nullable: When the outbound dial window opened (run transitioned to pending/waiting-for-call). Null until dispatched.
    - `outbound_dial_window_seconds` integer, nullable: Duration of the outbound dial window in seconds.
    - `outbound_dial_window_closes_at` string, date-time, nullable: 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.
  - `created_at` string, date-time

## Other responses

- `400`

## Changes

- **2026-11-03** `a6fb6a739212`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cekura/apis/cekura-api/changes/test_framework/v1/scenarios/run_scenarios_livekit_v2/post.md)

---

[API](https://skmtc.dev/cekura/apis/cekura-api.md) - [All operations](https://skmtc.dev/cekura/apis/cekura-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cekura/apis/cekura-api/revisions/a6fb6a739212?raw)