CEcekura
Evaluators

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

Changed on

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
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
    • API key in header X-CEKURA-API-KEY
    • or HTTP bearer
    • or HTTP bearer

Request body

namestring nullable

Optional name for the scenario result

frequencyinteger

Frequency to run

agentinteger nullable

Agent to use. Required if none of the scenarios have an agent.

personality_idsinteger[] nullable

List of personality IDs to override for this run. If not provided, uses the scenario's default personality.

test_profile_idsinteger[] nullable

List of test profile IDs to override for this run. If not provided, uses the scenario's default test profile.

mock_tool_namesstring[] 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.

concurrency_limitinteger nullable

Optional cap on how many of this run's calls execute concurrently.

calls_per_secondnumber 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_idinteger nullable

Single personality ID override. Merged into personality_ids; prefer personality_ids for multiple.

test_profile_idinteger nullable

Single test profile ID override. Merged into test_profile_ids; prefer test_profile_ids for multiple.

Response

idinteger

ID of the result

agentinteger

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_textboolean

Whether the scenario ran as text or not

created_atstring date-time

Example response

{
  "runs": [
    {
      "number": "+11234567890",
      "inbound_number": "+11234567890"
    }
  ],
  "created_at": "2025-02-25T21:00:01.990052Z"
}

Changes