Skip to main content
POST
/
test_framework
/
v1
/
scenarios
/
run_scenarios
Run evaluators over a voice call
curl --request POST \
  --url https://api.cekura.ai/test_framework/v1/scenarios/run_scenarios/ \
  --header 'Content-Type: application/json' \
  --header 'X-CEKURA-API-KEY: <api-key>' \
  --data '
{
  "agent_id": 123,
  "assistant_id": "<string>",
  "scenarios": [
    123
  ],
  "tags": [
    "<string>"
  ],
  "folder_path": "<string>",
  "project_id": 123,
  "frequency": 1,
  "name": "<string>",
  "outbound_phone_number": "<string>",
  "personality_ids": [
    123
  ],
  "test_profile_ids": [
    123
  ],
  "mode": "same_number",
  "agent_number": "<string>",
  "concurrency_limit": 2
}
'
{ "id": 167, "agent": 1, "status": "pending", "success_rate": 0, "run_as_text": false, "runs": [ { "id": 274, "scenario": 1, "number": null, "inbound_number": "+11234567890" }, { "id": 273, "scenario": 2, "number": null, "inbound_number": "+11234567891" } ], "created_at": "2025-02-25T21:00:01.990052Z" }

Authorizations

​
X-CEKURA-API-KEY
string
header
required

API Key Authentication. It should be included in the header of each request.

Body

​
agent_id
integer

ID of the agent to run evaluators for

​
assistant_id
string

Alternative to agent ID - the assistant ID to use for this scenario Example: "asst_1234567890"

​
scenarios
integer[]

List of evaluator IDs to run. Either evaluators, tags, or folder_path must be provided. Can also accept: an integer (first N evaluators), "all" (all evaluators), or a folder path string (e.g. "Sales.Inbound") to select evaluators by folder. When using a folder path string, project_id is required. Example: [11, 22, 33]

​
tags
string[]

List of tags to filter evaluators to run. Either evaluators or tags must be provided. Example: ["tag1", "tag2", "tag3"]

​
folder_path
string

Dot-separated folder path to select evaluators from (e.g. "Sales.Inbound"). Mutually exclusive with scenarios and tags. Requires project_id.

​
project_id
integer

Project ID. Required when using folder_path (or when passing a folder path string via scenarios). Example: 1376

​
frequency
integer
default:1

The number of times each evaluator will run Example: 1

Required range: x >= 1
​
name
string

Label text for result

​
outbound_phone_number
string

Override the phone number to use for outbound calls. Example: "+1234567890"

​
personality_ids
integer[] | null

List of personality IDs to override for this run. If not provided, uses the scenario's default personality. Example: [123, 456, 789]

​
test_profile_ids
integer[] | null

List of test profile IDs to override for this run. If not provided, uses the scenario's default test profile. Example: [123, 456, 789]

​
mode
enum<string>
default:same_number

Using same or different phone numbers for each evaluation

  • same_number - same_number
  • different_numbers - different_numbers
Available options:
same_number,
different_numbers
​
agent_number
string

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"

​
concurrency_limit
integer

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

Required range: x >= 1

Response

​
id
integer

ID of the result

​
agent
integer

ID of the agent

​
status
enum<string>

Status of the result

Available options:
pending,
running,
completed,
failed
​
run_as_text
boolean

Whether the scenario ran as text or not

Example:

false

​
runs
object[]
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
string<date-time>
Example:

"2025-02-25T21:00:01.990052Z"