test_framework

Retrieve an evaluator

Changed on Nov 3, 2026

Fetch a single evaluator by id. Returns full configuration including instructions, expected outcome, metrics, test profile, and — when the agent has mock tools attached and the scenario was auto-generated — the expected mock tool calls (generated_mock_tool_entries) with their inputs and outputs.

get/test_framework/v1/scenarios/{id}/

Request

Base URL
https://api.cekura.ai
URL
https://api.cekura.ai/test_framework/v1/scenarios/{id}/
Auth
- API key in header X-CEKURA-API-KEY
- or HTTP bearer
- or HTTP bearer

Path parameters

idinteger required

A unique integer value identifying this scenario.

Query parameters

conditional_actions_format'legacy'

Set to legacy to return conditional-action instructions in the earlier id-based format (id, condition, action, type, fixed_message).

Response

idinteger

namestring

Name of the evaluator

agentinteger

Agent ID Example: 2142

projectinteger nullable

assistant_idstring

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

personalityinteger

ID of the personality

personality_namestring

Name of the personality

agent_namestring

Name of the agent associated with this scenario Example: "Customer Support Agent"

tagsstring[]

List of tags of the evaluators Example: ["tag1", "tag2", "tag3"]

tool_idsunknown

metricsinteger[]

List of metric IDs Example: [123, 456, 789]

metric_namesstring[]

List of metric names Example: ["Metric 1", "Metric 2", "Metric 3"]

phone_numberstring

Phone number eg: +17776666333

first_messagestring

First message of the evaluator

inbound_phone_numberinteger nullable

instructionsstring

Scenario Instructions - format depends on scenario_type:

For instruction type: Plain text instructions
For conditional_actions type: JSON string with role, first_message and a conditions array. Each condition has when (a natural-language third-person description of the main agent's observable action — e.g. "The agent asks for your date of birth", matched semantically), say (spoken verbatim, with optional <silence time="1.5s" /> (interruptible) or <hold time="2s" /> (not interruptible) and [laughter] tags; wrap the whole step in <ai_generated>...</ai_generated> to improvise instead) and optional then follow-up steps. Responses return this format unless conditional_actions_format=legacy is passed. The earlier id-based format (id, condition, action, type, fixed_message) is still accepted on writes.

conditional_actionsunknown

condition_audioobject

Pre-recorded clips available to this scenario's conditional actions, keyed by clip id. Read-only: upload, replace and delete clips, and correct a transcript, through condition-audio/. Reference a clip from any number of verbatim steps by pasting its tag; steps lists where it is used (e.g. conditions[1].then[0]).

Example:

{
  "greeting": {"tag": "<audio id=\"greeting\"/>", "filename": "greeting.wav",
               "status": "ready", "duration": 2.4, "transcript": "Hi, is this the clinic?",
               "steps": ["first_message", "conditions[1]"]}
}

simulation_descriptionstring

information_fieldsobject

Information fields of the evaluator Example:

{
    "user_name": "John Doe",
    "user_email": "john.doe@example.com",
}

expected_outcome_promptstring

Expected outcome prompt of the evaluator Example: "The user should be able to complete the order"

scenario_language'af' | 'ar' | 'bn' | 'bg' | 'zh' | 'cs' | 'da' | 'nl' | 'en' | 'et' | 'fi' | 'fr' | 'de' | 'el' | 'gu' | 'hi' | 'he' | 'hu' | 'id' | 'it' | 'ja' | 'kn' | 'kk' | 'ko' | 'ms' | 'ml' | 'mr' | 'multi' | 'no' | 'pl' | 'pa' | 'pt' | 'ro' | 'ru' | 'sk' | 'es' | 'sv' | 'th' | 'tr' | 'tl' | 'ta' | 'te' | 'uk' | 'uz' | 'vi'

Language of the scenario

af - Afrikaans
ar - Arabic
bn - Bengali
bg - Bulgarian
zh - Chinese Simplified
cs - Czech
da - Danish
nl - Dutch
en - English
et - Estonian
fi - Finnish
fr - French
de - German
el - Greek
gu - Gujarati
hi - Hindi
he - Hebrew
hu - Hungarian
id - Indonesian
it - Italian
ja - Japanese
kn - Kannada
kk - Kazakh
ko - Korean
ms - Malay
ml - Malayalam
mr - Marathi
multi - Multilingual
no - Norwegian
pl - Polish
pa - Punjabi
pt - Portuguese
ro - Romanian
ru - Russian
sk - Slovak
es - Spanish
sv - Swedish
th - Thai
tr - Turkish
tl - Tagalog
ta - Tamil
te - Telugu
uk - Ukrainian
uz - Uzbek
vi - Vietnamese

scenario_typestring

Type of scenario:

instruction: Standard instruction-based scenario (plain text instructions)
conditional_actions: Conditional action-based scenario (JSON with role, conditions, SSML tags, emotion markers)

suite_type'undefined' | 'infrastructure'

Type of predefined suite (e.g., infrastructure)

undefined - Undefined
infrastructure - Infrastructure

is_predefinedboolean

Whether this is a predefined scenario (template)

test_profileinteger nullable

dynamic_variable_valuesunknown

generated_mock_tool_entriesunknown

folder_pathstring nullable

Path of an existing folder to assign this evaluator to, e.g. "Sales" or "Sales.Inbound". Create it first with the create-folder endpoint.

max_durationinteger nullable

Max call duration in seconds for this scenario. If not provided or set to null, the scenario will use the project's max_call_duration setting. Valid range: 10-3600 seconds (10 seconds to 60 minutes) Example: 600 (10 minutes)

Changes

Nov 3, 2026a6fb6a739212 Revision changes
- breaking
  the //// response's property type changed from no type to object for status
- breaking
  the //// response's property type changed from no type to object for status
- info
  api operation id scenarios-retrieve removed and replaced with scenarios-retrieve_2
- info
  the endpoint scheme security oauth2 was added to the API
- info
  the endpoint scheme security supabase_session was added to the API
- info
  added the new optional query request parameter conditional_actions_format
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property ///// to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the required property ///// to the response with the status
- info
  added the required property ///// to the response with the status
- info
  added the required property ///// to the response with the status
- info
  added the required property ///// to the response with the status

Operation history