Get Evaluator - Cekura

Retrieve an evaluator (scenario)

curl --request GET \
  --url https://api.cekura.ai/test_framework/v1/scenarios/{id}/ \
  --header 'X-CEKURA-API-KEY: <api-key>'

import requests

url = "https://api.cekura.ai/test_framework/v1/scenarios/{id}/"

headers = {"X-CEKURA-API-KEY": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-CEKURA-API-KEY': '<api-key>'}};

fetch('https://api.cekura.ai/test_framework/v1/scenarios/{id}/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cekura.ai/test_framework/v1/scenarios/{id}/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-CEKURA-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cekura.ai/test_framework/v1/scenarios/{id}/"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-CEKURA-API-KEY", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.cekura.ai/test_framework/v1/scenarios/{id}/")
  .header("X-CEKURA-API-KEY", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cekura.ai/test_framework/v1/scenarios/{id}/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-CEKURA-API-KEY"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "id": 123,
  "name": "<string>",
  "agent": 123,
  "project": 123,
  "personality": 123,
  "personality_name": "<string>",
  "agent_name": "<string>",
  "tags": [
    "<string>"
  ],
  "tool_ids": "<unknown>",
  "metrics": [
    123
  ],
  "metric_names": [
    "<string>"
  ],
  "phone_number": "<string>",
  "outbound_phone_number_data": {
    "number": "<string>",
    "phone_number_id": "<string>",
    "id": 123
  },
  "first_message": "<string>",
  "inbound_phone_number": 123,
  "inbound_phone_number_data": {
    "number": "<string>",
    "phone_number_id": "<string>",
    "id": 123
  },
  "instructions": "<string>",
  "simulation_description": "<string>",
  "information_fields": {},
  "expected_outcome_prompt": "<string>",
  "scenario_type": "<string>",
  "is_predefined": true,
  "test_profile": 123,
  "test_profile_data": {
    "name": "<string>",
    "id": 123,
    "project": 123,
    "agent": 123,
    "agent_name": "<string>",
    "information": "<unknown>",
    "created_by": 123,
    "last_updated_by": 123,
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  },
  "dynamic_variable_values": "<unknown>",
  "generated_mock_tool_entries": "<unknown>",
  "folder_path": "<string>",
  "max_duration": 123
}

{
  "detail": "<string>"
}

GET

test_framework

scenarios

{id}

Retrieve an evaluator (scenario)

curl --request GET \
  --url https://api.cekura.ai/test_framework/v1/scenarios/{id}/ \
  --header 'X-CEKURA-API-KEY: <api-key>'

import requests

url = "https://api.cekura.ai/test_framework/v1/scenarios/{id}/"

headers = {"X-CEKURA-API-KEY": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-CEKURA-API-KEY': '<api-key>'}};

fetch('https://api.cekura.ai/test_framework/v1/scenarios/{id}/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cekura.ai/test_framework/v1/scenarios/{id}/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-CEKURA-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cekura.ai/test_framework/v1/scenarios/{id}/"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-CEKURA-API-KEY", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.cekura.ai/test_framework/v1/scenarios/{id}/")
  .header("X-CEKURA-API-KEY", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cekura.ai/test_framework/v1/scenarios/{id}/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-CEKURA-API-KEY"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "id": 123,
  "name": "<string>",
  "agent": 123,
  "project": 123,
  "personality": 123,
  "personality_name": "<string>",
  "agent_name": "<string>",
  "tags": [
    "<string>"
  ],
  "tool_ids": "<unknown>",
  "metrics": [
    123
  ],
  "metric_names": [
    "<string>"
  ],
  "phone_number": "<string>",
  "outbound_phone_number_data": {
    "number": "<string>",
    "phone_number_id": "<string>",
    "id": 123
  },
  "first_message": "<string>",
  "inbound_phone_number": 123,
  "inbound_phone_number_data": {
    "number": "<string>",
    "phone_number_id": "<string>",
    "id": 123
  },
  "instructions": "<string>",
  "simulation_description": "<string>",
  "information_fields": {},
  "expected_outcome_prompt": "<string>",
  "scenario_type": "<string>",
  "is_predefined": true,
  "test_profile": 123,
  "test_profile_data": {
    "name": "<string>",
    "id": 123,
    "project": 123,
    "agent": 123,
    "agent_name": "<string>",
    "information": "<unknown>",
    "created_by": 123,
    "last_updated_by": 123,
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  },
  "dynamic_variable_values": "<unknown>",
  "generated_mock_tool_entries": "<unknown>",
  "folder_path": "<string>",
  "max_duration": 123
}

{
  "detail": "<string>"
}

Authorizations

X-CEKURA-API-KEY

string

header

required

API Key Authentication. It should be included in the header of each request.

Path Parameters

integer

required

A unique integer value identifying this scenario.

Response

integer

read-only

name

string

Name of the evaluator

agent

integer

Agent ID Example: 2142

project

integer | null

personality

integer

ID of the personality

personality_name

string

Name of the personality

agent_name

string

read-only

Name of the agent associated with this scenario Example: "Customer Support Agent"

tags

string[]

List of tags of the evaluators Example: ["tag1", "tag2", "tag3"]

tool_ids

any

List of tool IDs to associate with this scenario Example: ["TOOL_DTMF", "TOOL_END_CALL"]

metrics

integer[]

List of metric IDs Example: [123, 456, 789]

metric_names

string[]

List of metric names Example: ["Metric 1", "Metric 2", "Metric 3"]

phone_number

string

Phone number eg: +17776666333

outbound_phone_number_data

object

Phone number used for outbound calls in this scenario Example: "+1234567890"

Show child attributes

first_message

string

First message of the evaluator

inbound_phone_number

integer | null

inbound_phone_number_data

object

(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"}

Show child attributes

instructions

string

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 <silence time="1.5s" /> (interruptible) or <hold time="2s" /> (not interruptible) and [laughter] tags), type (standard/action_followup), and fixed_message flag

simulation_description

string

Simulation Description

information_fields

object

Information fields of the evaluator Example:

{
    "user_name": "John Doe",
    "user_email": "john.doe@example.com",
}

Show child attributes

expected_outcome_prompt

string

Expected outcome prompt of the evaluator Example: "The user should be able to complete the order"

scenario_language

enum<string>

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

Available options:

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

scenario_type

string

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<string>

Type of predefined suite (e.g., infrastructure)

undefined - Undefined
infrastructure - Infrastructure

Available options:

undefined,

infrastructure

is_predefined

boolean

Whether this is a predefined scenario (template)

test_profile

integer | null

test_profile_data

object

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:

{
    "id": "<integer>",
    "agent_id": "<integer>",
    "name": "<string>",
    "information": {
        "main_agent_variables": {
            "user_id": "<string>",
            "account_id": "<string>"
        },
        "testing_agent_variables": {
            "user_name": "<string>",
            "user_email": "<string>",
            "order_id": "<string>"
        }
    }
}

Show child attributes

dynamic_variable_values

any

read-only

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

any | null

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

string · null · null

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

integer | null

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)

Process Feedbacks Answer List Evaluators

⌘I