--- title: "List evaluators" method: GET path: "/test_framework/v1/scenarios/" tags: ["test_framework"] --- # List evaluators `GET /test_framework/v1/scenarios/` ## Request - Base URL: `https://api.cekura.ai` - URL: `https://api.cekura.ai/test_framework/v1/scenarios/` - Auth: one of: - API key in header `X-CEKURA-API-KEY` - HTTP bearer - HTTP bearer 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. ## Query parameters - `page` integer - `page_size` integer - `agent_id` integer - `project_id` integer - `assistant_id` string - `tags` string - `tag_filter_type` 'and' | 'or' | 'not' - `folder_path` string - `ordering` string - `conditional_actions_format` 'legacy' ## Response `200` - PaginatedScenarioListList - `count` integer, required - `next` string, uri, nullable - `previous` string, uri, nullable - `results` ScenarioList[], required - `id` integer: Unique identifier for the AI agent Example: `123` - `name` string, required: Name of the scenario - `personality` integer, nullable: Foreign key reference to the personality used in this scenario - `personality_name` string: Name of the personality used in this scenario Example: `"Normal Male"` - `agent_name` string: Name of the agent associated with this scenario Example: `"Customer Support Agent"` - `phone_number` string - `expected_outcome_prompt` string: Expected outcome prompt for the scenario Example: `"The user should be able to complete the order"` - `instructions` string, required: 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 the same object as a JSON-formatted string. The earlier id-based format (`id`, `condition`, `action`, `type`, `fixed_message`) is still accepted on writes. Responses return this shape unless `conditional_actions_format=legacy` is passed: ```json { "role": "A friendly customer calling about an appointment", "first_message": "Hi, I'd like to check on my upcoming appointment ", "conditions": [ {"when": "The agent asks for your name", "say": "My name is Sarah Johnson"}, {"when": "The agent asks for your date of birth", "say": "January first, nineteen ninety"}, { "when": "The agent confirms your identity and provides appointment details", "say": "Thank you, that's all I needed", "then": [""] } ] } ``` **Structure:** - `role`: Personality/role description - `first_message`: What the caller says first; empty means wait for the agent. Use `{"say": "...", "then": [...]}` to add follow-ups. - `conditions[].when`: A third-person description of the agent's observable action, matched semantically against the conversation - `conditions[].say`: The caller's reply, spoken verbatim. Wrap the whole step in `...` to let the caller improvise from it instead - `conditions[].then`: Optional follow-up steps, each fired on the caller's next turn after one agent reply, in order - Steps support SSML `` (interruptible), `` (not interruptible), `[laughter]` and `` in verbatim steps - `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' | 'null', nullable: 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 * `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_type` 'instruction' | 'conditional_actions': 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 * `instruction` - Instruction * `conditional_actions` - Conditional Actions - `tags` unknown - `agent` integer, required: Foreign key reference to the AI agent that owns this scenario - `inbound_phone_number` integer, nullable: (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` string: Details of the phone number used for inbound calls - `metrics` string: List of metrics associated with this scenario for evaluation - `metric_names` string: List of metric names associated with this scenario Example: `["Metric 1", "Metric 2", "Metric 3"]` - `first_message` string: The initial message that the AI agent will send when the scenario starts - `tool_ids` unknown - `test_profile` integer, nullable: Test profile ID Example: `123` - `test_profile_data` AIAgentTestProfile - `id` integer - `project` integer, nullable - `agent` integer, nullable - `agent_name` string: Name of the agent associated with this test profile Example: `"Customer Support Agent"` - `name` string, required - `information` unknown - `created_by` integer, nullable: ID of the user who created this test profile - `last_updated_by` integer, nullable: ID of the user who last updated this test profile - `created_at` string, date-time: Timestamp when the test profile was created - `updated_at` string, date-time: Timestamp when the test profile was last updated - `dynamic_variable_values` unknown - `created_at` string, date-time: Timestamp when the scenario was created - `updated_at` string, date-time: Timestamp when the scenario was last updated - `created_by` integer, nullable: ID of the user who created this scenario - `last_updated_by` integer, nullable: ID of the user who last updated this scenario - `folder_path` string, 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. ## Changes - **2026-11-03** `a6fb6a739212`: 1 info - endpoint added [Operation history](https://skmtc.dev/cekura/apis/cekura-api/changes/test_framework/v1/scenarios/get.md) --- [API](https://skmtc.dev/cekura/apis/cekura-api.md) - [All operations](https://skmtc.dev/cekura/apis/cekura-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cekura/apis/cekura-api/revisions/a6fb6a739212?raw)