> ## 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
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.
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.
````