CEcekura
test_framework

Retrieve an evaluator

Changed on

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/v2/scenarios/{id}/

Request

  • Base URL
    https://api.cekura.ai
  • URL
    https://api.cekura.ai/test_framework/v2/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