> ## 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.
# List Evaluators
> List test scenarios
## OpenAPI
````yaml get /test_framework/v1/scenarios/
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/:
get:
tags:
- test_framework
summary: List evaluators (scenarios)
description: >-
scenarios_list: List evaluators (test scenarios) that simulate callers
interacting with your agent. Filter by `agent_id`, `project_id`, `tags`,
`folder_path`, or other params (see Schema). Returns paginated scenarios
with their instructions, type, personalities, and metrics.
Performance tip: pass the most specific filter you have. `agent_id` if a
specific agent is in context, `folder_path` if you're discussing a
specific folder, or `project_id` for a workspace-level view.
`page_size=20` is a reasonable starting size if you want to peek at
recent ones first.
operationId: scenarios-list
parameters:
- name: page
required: false
in: query
description: A page number within the paginated result set.
schema:
type: integer
- name: page_size
required: false
in: query
description: Number of results to return per page.
schema:
type: integer
- in: query
name: agent_id
schema:
type: integer
description: |
Filter evaluators by agent ID
Example: `2142`
- in: query
name: project_id
schema:
type: integer
description: |
Filter evaluators by project ID
Example: `1`
- in: query
name: assistant_id
schema:
type: string
minLength: 1
description: |
Filter evaluators by assistant ID
Example: `asst_1234567890`
- in: query
name: tags
schema:
type: string
minLength: 1
description: |
Comma-separated list of tags to filter evaluators by
Example: `tag1,tag2,tag3`
- in: query
name: tag_filter_type
schema:
enum:
- and
- or
- not
type: string
x-spec-enum-id: b8b9507605e7dc0e
default: or
minLength: 1
description: |-
Filter operation type for tags
* `and` - and
* `or` - or
* `not` - not
- in: query
name: folder_path
schema:
type: string
description: >
Filter evaluators by folder path. Use empty string to get evaluators
without a folder.
Example: `Sales.Inbound`
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedScenarioListList'
description: ''
security:
- api_key: []
components:
schemas:
PaginatedScenarioListList:
type: object
required:
- count
- results
properties:
count:
type: integer
example: 123
next:
type: string
nullable: true
format: uri
example: https://api.cekura.ai/example/v1/example-external/?page=4
previous:
type: string
nullable: true
format: uri
example: https://api.cekura.ai/example/v1/example-external/?page=3
results:
type: array
items:
$ref: '#/components/schemas/ScenarioList'
ScenarioList:
type: object
description: ''
properties:
id:
type: integer
readOnly: true
description: |
Unique identifier for the AI agent
Example: `123`
name:
type: string
description: Name of the scenario
maxLength: 80
personality:
type:
- integer
- 'null'
description: Foreign key reference to the personality used in this scenario
personality_name:
type: string
readOnly: true
description: |
Name of the personality used in this scenario
Example: `"Normal Male"`
agent_name:
type: string
readOnly: true
description: |
Name of the agent associated with this scenario
Example: `"Customer Support Agent"`
phone_number:
type: string
readOnly: true
expected_outcome_prompt:
type: string
readOnly: true
description: |
Expected outcome prompt for the scenario
Example: `"The user should be able to complete the order"`
instructions:
type: string
description: >
Scenario Instructions - format depends on scenario_type:
**For scenario_type="instruction":**
Plain text describing the caller's behavior.
Example: `"You are a customer calling to inquire about your order
status. Be polite and provide order number 12345 when asked."`
**For scenario_type="conditional_actions":**
Use the structured `conditional_actions` field instead. If you must
send via this field, pass a JSON-formatted string with role and
conditions:
```json
{
"role": "A friendly customer calling about an appointment",
"conditions": [
{
"id": 0,
"condition": "FIRST_MESSAGE",
"action": "Hi, I'd like to check on my upcoming appointment ",
"type": "standard",
"fixed_message": true
},
{
"id": 1,
"condition": "The agent asks for your name",
"action": "My name is Sarah Johnson",
"type": "standard",
"fixed_message": true
},
{
"id": 2,
"condition": "The agent asks for your date of birth",
"action": "January first, nineteen ninety",
"type": "standard",
"fixed_message": true
},
{
"id": 3,
"condition": "The agent confirms your identity and provides appointment details",
"action": "Thank you, that's all I needed ",
"type": "standard",
"fixed_message": true
},
{
"id": 4,
"condition": 3,
"action": "",
"type": "action_followup",
"fixed_message": true
}
]
}
```
**Structure:**
- `role`: Personality/role description
- `conditions`: Array with id (0,1,2...), condition (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 against the conversation context | integer
reference to another condition's id), action (text with SSML
`` (interruptible) or ``
(not interruptible) and markers `[laughter]` or ``), type
(standard | action_followup), fixed_message (boolean)
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
- null
type:
- string
- 'null'
x-spec-enum-id: b822ad429c7b7fec
description: |-
Language code for the scenario (ISO language code)
* `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:
enum:
- instruction
- real_world_smart
- real_world_fixed
- conditional_actions
type: string
x-spec-enum-id: db62e37bb530b602
default: instruction
description: >-
Type of scenario:
- `instruction`: Standard instruction-based scenario where
instructions field contains plain text
- `conditional_actions`: Conditional action-based scenario where
instructions field contains JSON
- `real_world_smart`: Real world smart scenario
- `real_world_fixed`: Real world fixed scenario
* `instruction` - Instruction
* `real_world_smart` - Real World Smart
* `real_world_fixed` - Real World Fixed
* `conditional_actions` - Conditional Actions
tags:
description: |
List of tags associated with this scenario for categorization
Example: `["tag1", "tag2", "tag3"]`
agent:
type: integer
description: Foreign key reference to the AI agent that owns this scenario
inbound_phone_number:
type:
- integer
- 'null'
description: >-
(Deprecated) Foreign key reference to the phone number. Use
phone_number field instead. This field is maintained for backward
compatibility and will be automatically synced with phone_number.
inbound_phone_number_data:
type: string
readOnly: true
description: Details of the phone number used for inbound calls
metrics:
type: string
readOnly: true
description: List of metrics associated with this scenario for evaluation
metric_names:
type: string
readOnly: true
description: |
List of metric names associated with this scenario
Example: `["Metric 1", "Metric 2", "Metric 3"]`
first_message:
type: string
default: Hello
description: >-
The initial message that the AI agent will send when the scenario
starts
tool_ids:
description: |
List of tool IDs that are available for use in this scenario
Example: `["TOOL_DTML", "TOOL_END_CALL"]`
test_profile:
type:
- integer
- 'null'
description: |
Test profile ID
Example: `123`
test_profile_data:
allOf:
- $ref: '#/components/schemas/AIAgentTestProfile'
readOnly: true
description: |
Details of the test profile associated with this scenario
Example:
```json
{
"id": "",
"agent": "",
"name": "",
"information": {
"user_name": "John Doe",
"user_email": "john.doe@example.com",
}
}
```
dynamic_variable_values:
oneOf:
- {}
- type: 'null'
description: >-
REMOVED FROM API. Historically stored a flat copy of the agent's
dynamic-variable values for the scenario. The column is retained
read-only for legacy rows; reads still return its historical value,
but writes via the API are rejected with a 400. At call time the
Run-level helper consults this column ONLY when the attached
test_profile is legacy-flat (or absent) — sectioned test profiles
are the canonical source and ignore this column. Put
dynamic-variable values in
`test_profile.information.main_agent_variables` for new scenarios.
created_at:
type: string
format: date-time
readOnly: true
description: Timestamp when the scenario was created
updated_at:
type: string
format: date-time
readOnly: true
description: Timestamp when the scenario was last updated
created_by:
type: integer
readOnly: true
description: ID of the user who created this scenario
last_updated_by:
type: integer
readOnly: true
description: ID of the user who last updated this scenario
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.
required:
- agent
- instructions
- name
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.
````