> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cekura.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Evaluator
> Retrieve a test scenario by ID
## OpenAPI
````yaml get /test_framework/v1/scenarios/{id}/
openapi: 3.1.0
info:
title: Cekura API
version: v1
description: >-
Complete API documentation for the Cekura platform. This API provides
endpoints for testing, observing, and evaluating AI voice agents — including
managing agents, running evaluators, defining metrics, and analyzing call
quality.
servers:
- url: https://api.cekura.ai
security: []
paths:
/test_framework/v1/scenarios/{id}/:
get:
tags:
- test_framework
summary: Retrieve an evaluator (scenario)
description: >-
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.
operationId: scenarios-retrieve
parameters:
- in: path
name: id
schema:
type: integer
description: A unique integer value identifying this scenario.
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SchemaScenario'
description: ''
'404':
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: ''
security:
- api_key: []
components:
schemas:
SchemaScenario:
type: object
description: ''
properties:
id:
type: integer
readOnly: true
name:
type: string
description: Name of the evaluator
agent:
type: integer
description: |
Agent ID
Example: `2142`
project:
type:
- integer
- 'null'
assistant_id:
type: string
writeOnly: true
description: |
Alternative to agent ID - the assistant ID to use for this scenario
Example: `"asst_1234567890"`
personality:
type: integer
description: ID of the personality
personality_name:
type: string
description: Name of the personality
agent_name:
type: string
readOnly: true
description: |
Name of the agent associated with this scenario
Example: `"Customer Support Agent"`
tags:
type: array
items:
type: string
description: |
List of tags of the evaluators
Example: `["tag1", "tag2", "tag3"]`
tool_ids:
description: |
List of tool IDs to associate with this scenario
Example: `["TOOL_DTMF", "TOOL_END_CALL"]`
metrics:
type: array
items:
type: integer
description: |
List of metric IDs
Example: `[123, 456, 789]`
metric_names:
type: array
items:
type: string
description: |
List of metric names
Example: `["Metric 1", "Metric 2", "Metric 3"]`
phone_number:
type: string
description: 'Phone number eg: +17776666333'
outbound_phone_number_data:
allOf:
- $ref: '#/components/schemas/PhoneNumberInbound'
readOnly: true
description: |
Phone number used for outbound calls in this scenario
Example: `"+1234567890"`
first_message:
type: string
description: First message of the evaluator
inbound_phone_number:
type:
- integer
- 'null'
inbound_phone_number_data:
allOf:
- $ref: '#/components/schemas/PhoneNumberInbound'
readOnly: true
description: >
(Deprecated) Phone number used for inbound calls in this scenario.
Use outbound_phone_number_data instead.
After CEK-6517, both phone_number and inbound_phone_number fields
are synced, so outbound_phone_number_data contains the unified phone
number for both inbound and outbound calls.
Example: `{"id": 123, "number": "+1234567890", "phone_number_id":
"abc123"}`
instructions:
type: string
description: >
Scenario Instructions - format depends on scenario_type:
- For `instruction` type: Plain text instructions
- For `conditional_actions` type: JSON string with role and
conditions array. Each condition has id, condition trigger
(FIRST_MESSAGE, 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 — or an integer reference to
another condition's id), action (text with optional `` (interruptible) or `` (not
interruptible) and `[laughter]` tags), type
(standard/action_followup), and fixed_message flag
conditional_actions:
writeOnly: true
description: >-
Structured conditional-actions object for
`scenario_type="conditional_actions"`. Use either
`conditional_actions` (structured) or `instructions` (plain text) —
not both.
Example:
```json
{
"role": "You are a patient calling to schedule an appointment",
"conditions": [
{"id": 0, "condition": "FIRST_MESSAGE", "action": "Hi, I need to schedule an appointment",
"type": "standard", "fixed_message": true},
{"id": 1, "condition": "when the agent asks for your name",
"action": "Provide your full name: John Smith", "type": "standard", "fixed_message": false}
]
}
```
simulation_description:
type: string
description: Simulation Description
information_fields:
type: object
additionalProperties: {}
description: |
Information fields of the evaluator
Example:
```json
{
"user_name": "John Doe",
"user_email": "john.doe@example.com",
}
```
expected_outcome_prompt:
type: string
description: |
Expected outcome prompt of the evaluator
Example: `"The user should be able to complete the order"`
scenario_language:
enum:
- af
- ar
- bn
- bg
- zh
- cs
- da
- nl
- en
- et
- fi
- fr
- de
- el
- gu
- hi
- he
- hu
- id
- it
- ja
- kn
- ko
- ms
- ml
- mr
- multi
- 'no'
- pl
- pa
- pt
- ro
- ru
- sk
- es
- sv
- th
- tr
- tl
- ta
- te
- uk
- vi
type: string
x-spec-enum-id: b822ad429c7b7fec
description: |-
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
* `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
* `vi` - Vietnamese
scenario_type:
type: string
description: >
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)
- `real_world_smart`: Real world smart scenario
- `real_world_fixed`: Real world fixed scenario
suite_type:
enum:
- undefined
- infrastructure
type: string
x-spec-enum-id: 643f6a8cdc799a77
description: |-
Type of predefined suite (e.g., infrastructure)
* `undefined` - Undefined
* `infrastructure` - Infrastructure
is_predefined:
type: boolean
description: Whether this is a predefined scenario (template)
test_profile:
type:
- integer
- 'null'
test_profile_data:
allOf:
- $ref: '#/components/schemas/AIAgentTestProfile'
readOnly: true
description: >
Details of the test profile associated with this scenario.
`information` uses the
sectioned shape: `main_agent_variables` are sent to the agent under
test as
dynamic variables at call time; `testing_agent_variables` are
persona/context
used by Cekura's simulated caller. Legacy flat dicts (no section
keys) still
work — at call time they are delivered to both sides for backward
compatibility.
Example:
```json
{
"id": "",
"agent_id": "",
"name": "",
"information": {
"main_agent_variables": {
"user_id": "",
"account_id": ""
},
"testing_agent_variables": {
"user_name": "",
"user_email": "",
"order_id": ""
}
}
}
```
dynamic_variable_values:
readOnly: true
description: >-
REMOVED FROM API. Reads return the historical value for legacy rows
(`null` for new rows). Writes are no longer accepted — supplying a
non-null value yields a 400 error. Put dynamic-variable values in
`test_profile_data.information.main_agent_variables` instead: create
the test profile via POST /test-profiles/ and attach it via the
`test_profile` field on the scenario.
generated_mock_tool_entries:
oneOf:
- {}
- type: 'null'
description: >-
Expected mock tool calls for this evaluator. Each entry has shape
{tool_id, tool_name, new_entry: {input, output}}. Auto-generated
during scenario generation when the agent has mock tools attached;
can also be set or edited manually.
folder_path:
type:
- string
- 'null'
- 'null'
description: >-
Dot-separated path of the folder to assign this evaluator to (e.g.
"Sales.Inbound"). Folders must be created before use — they are not
auto-created. Use `scenarios_create_folder_create` to create each
level before assigning evaluators. Example: to use "Sales.Inbound",
first create "Sales", then create "Inbound" inside it.
max_duration:
type:
- integer
- 'null'
description: >
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)
PhoneNumberInbound:
type: object
properties:
id:
type: integer
readOnly: true
number:
type: string
maxLength: 15
phone_number_id:
type: string
maxLength: 255
required:
- number
- phone_number_id
AIAgentTestProfile:
type: object
description: ''
properties:
id:
type: integer
readOnly: true
project:
type:
- integer
- 'null'
agent:
type:
- integer
- 'null'
agent_name:
type: string
readOnly: true
description: |
Name of the agent associated with this test profile
Example: `"Customer Support Agent"`
name:
type: string
maxLength: 255
information:
description: >
Variables for the test profile, split by which agent receives them.
```json
{
"main_agent_variables": {"user_id": "U-123"},
"testing_agent_variables": {"user_name": "John Doe", "user_email": "john.doe@example.com"}
}
```
`main_agent_variables` are sent to the agent under test as dynamic
variables. `testing_agent_variables` shape the simulated caller's
persona. A legacy flat dict (no section keys) is accepted for
backward compatibility and is sent to both agents.
Keys in `main_agent_variables` starting with `X-` are additionally
sent as custom SIP headers (SIP runs) or connection headers
(WebSocket runs) to the agent under test. For SIP runs this is the
only way to pass custom headers; `X-Run-Id`, `X-Scenario-Id`, and
`X-Result-Id` are reserved and always set by Cekura.
created_by:
type: integer
readOnly: true
description: ID of the user who created this test profile
last_updated_by:
type: integer
readOnly: true
description: ID of the user who last updated this test profile
created_at:
type: string
format: date-time
readOnly: true
description: Timestamp when the test profile was created
updated_at:
type: string
format: date-time
readOnly: true
description: Timestamp when the test profile was last updated
required:
- name
securitySchemes:
api_key:
type: apiKey
name: X-CEKURA-API-KEY
in: header
description: >-
API Key Authentication. It should be included in the header of each
request.
````