Skip to main content
POST
Start customer-driven (API chat) evaluator runs

Authorizations

X-CEKURA-API-KEY
string
header
required

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

Body

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.

agent_id
integer

ID of the agent to run evaluators for

assistant_id
string
write-only

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

name
string

Label text for result

scenarios
integer[]

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
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
personality_ids
integer[] | null

Personality IDs to override for this run. Defaults to each scenario's personality.

test_profile_ids
integer[] | null

Test-profile IDs to override for this run. Defaults to each scenario's test profile.

timeout
integer | null

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).

Required range: 1 <= x <= 3600

Response

name
string
required

Name of the Result Example: "Test Result 1"

Maximum string length: 255
id
integer
read-only

Unique identifier for the Result Example: 123

agent
integer
read-only

ID of the AI agent that was tested Example: 123

agent_inbound
boolean
read-only

Whether the agent is configured for inbound calls (true) or outbound calls (false) Example: true or false

status
enum<string>
default:pending

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
Available options:
running,
completed,
failed,
pending,
in_progress,
evaluating,
in_queue,
timeout,
cancelled,
scaling_up
success_rate
number<double>
default:0

Success rate of the test runs as a decimal (0.0 to 1.0)

run_as_text
boolean
default:false

Whether this test was run in text mode instead of voice mode Example: true or false

is_cronjob
string
read-only

Whether this result was created by a scheduled cronjob Example: true or false

runs
object
read-only

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.

created_at
string<date-time>
read-only

Timestamp when this test result was created Example: 2021-01-01 00:00:00

updated_at
string<date-time>
read-only

Timestamp when this test result was last updated