Run Evaluator Text

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_text endpoint, which runs scenarios in text mode (SMS, chat, or agent-hosted websocket).

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. Runs start in the order given. 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. Each repeat runs the whole list in order before the next one starts (A, B, A, B), rather than grouping repeats of one evaluator. Example: 1

Required range: x >= 1

websocket_url

string

If provided, the simulated caller connects to this websocket URL instead of using the agent's configured text/SMS gateway. Use for agents that expose a websocket endpoint for text testing. Bypasses the normal agent.can_run_as_text() check.

websocket_headers

object

Headers to send on the websocket connection for this run. Merged over the agent's configured websocket_headers — keys provided here win. System X-VOCERA-* headers cannot be overridden.

Show child attributes

personality_ids

integer[] | null

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

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.

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"

outbound_phone_number

string

Override the phone number to use for outbound calls. 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

calls_per_second

number<double> | null

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.

Required range: 0.1 <= x <= 4

mock_tool_names

string[]

Names of mock tools to activate for this run. Cekura swaps those tools' URLs to mock endpoints while the run is active and restores the originals when it finishes. 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. Example: ["get_appointments", "cancel_booking"]

agent_version_id

string

Run against a stored version of the agent instead of the agent as it is live. Cekura makes a private copy of the agent in your provider account, puts that version's prompt on it, and runs against the copy — voice, model and tools stay as the agent is configured now, and the live agent is never changed. Accepts the version label shown in the agent's version history (v12, or p1 for a version an improvement run proposed) or its numeric history_id. List them with GET /test_framework/v1/aiagents/{id}/history/; a version is usable when its is_runnable is true. Available for VAPI, Retell, ElevenLabs and Bland agents that are outbound and have a single prompt. Example: "v12"

Response

integer

ID of the result

agent

integer

ID of the agent

status

enum<string>

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.

Available options:

running,

completed,

failed,

pending,

in_progress,

evaluating,

in_queue,

timeout,

cancelled,

scaling_up

run_as_text

boolean

Whether the scenario ran as text or not

Example:

false

runs

object[]

Show child attributes

Examples:

{
  "id": 274,
  "status": "pending",
  "scenario": 1,
  "number": null,
  "inbound_number": "+11234567890",
  "scenario_name": "Customer Support Call (Agent Inbound = True)",
  "test_profile_data": null,
  "outbound_dial_window_opens_at": null,
  "outbound_dial_window_seconds": null,
  "outbound_dial_window_closes_at": null
}

{
  "id": 275,
  "status": "pending",
  "scenario": 2,
  "number": "+11234567890",
  "inbound_number": null,
  "scenario_name": "Outbound Sales Call (Agent Inbound = False)",
  "test_profile_data": null,
  "outbound_dial_window_opens_at": "2026-06-24T10:47:30Z",
  "outbound_dial_window_seconds": 300,
  "outbound_dial_window_closes_at": "2026-06-24T10:52:30Z"
}

created_at

string<date-time>

Example:

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