curl --request POST \
--url https://api.cekura.ai/test_framework/v1/scenarios/run_scenarios_api_chat/ \
--header 'Content-Type: application/json' \
--header 'X-CEKURA-API-KEY: <api-key>' \
--data '
{
"agent_id": 123,
"assistant_id": "<string>",
"name": "<string>",
"scenarios": [
123
],
"tags": [
"<string>"
],
"folder_path": "<string>",
"project_id": 123,
"frequency": 1,
"personality_ids": [
123
],
"test_profile_ids": [
123
],
"timeout": 1800,
"agent_version_id": "<string>"
}
'import requests
url = "https://api.cekura.ai/test_framework/v1/scenarios/run_scenarios_api_chat/"
payload = {
"agent_id": 123,
"assistant_id": "<string>",
"name": "<string>",
"scenarios": [123],
"tags": ["<string>"],
"folder_path": "<string>",
"project_id": 123,
"frequency": 1,
"personality_ids": [123],
"test_profile_ids": [123],
"timeout": 1800,
"agent_version_id": "<string>"
}
headers = {
"X-CEKURA-API-KEY": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-CEKURA-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
agent_id: 123,
assistant_id: '<string>',
name: '<string>',
scenarios: [123],
tags: ['<string>'],
folder_path: '<string>',
project_id: 123,
frequency: 1,
personality_ids: [123],
test_profile_ids: [123],
timeout: 1800,
agent_version_id: '<string>'
})
};
fetch('https://api.cekura.ai/test_framework/v1/scenarios/run_scenarios_api_chat/', 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/run_scenarios_api_chat/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'agent_id' => 123,
'assistant_id' => '<string>',
'name' => '<string>',
'scenarios' => [
123
],
'tags' => [
'<string>'
],
'folder_path' => '<string>',
'project_id' => 123,
'frequency' => 1,
'personality_ids' => [
123
],
'test_profile_ids' => [
123
],
'timeout' => 1800,
'agent_version_id' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.cekura.ai/test_framework/v1/scenarios/run_scenarios_api_chat/"
payload := strings.NewReader("{\n \"agent_id\": 123,\n \"assistant_id\": \"<string>\",\n \"name\": \"<string>\",\n \"scenarios\": [\n 123\n ],\n \"tags\": [\n \"<string>\"\n ],\n \"folder_path\": \"<string>\",\n \"project_id\": 123,\n \"frequency\": 1,\n \"personality_ids\": [\n 123\n ],\n \"test_profile_ids\": [\n 123\n ],\n \"timeout\": 1800,\n \"agent_version_id\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-CEKURA-API-KEY", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.cekura.ai/test_framework/v1/scenarios/run_scenarios_api_chat/")
.header("X-CEKURA-API-KEY", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"agent_id\": 123,\n \"assistant_id\": \"<string>\",\n \"name\": \"<string>\",\n \"scenarios\": [\n 123\n ],\n \"tags\": [\n \"<string>\"\n ],\n \"folder_path\": \"<string>\",\n \"project_id\": 123,\n \"frequency\": 1,\n \"personality_ids\": [\n 123\n ],\n \"test_profile_ids\": [\n 123\n ],\n \"timeout\": 1800,\n \"agent_version_id\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cekura.ai/test_framework/v1/scenarios/run_scenarios_api_chat/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-CEKURA-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"agent_id\": 123,\n \"assistant_id\": \"<string>\",\n \"name\": \"<string>\",\n \"scenarios\": [\n 123\n ],\n \"tags\": [\n \"<string>\"\n ],\n \"folder_path\": \"<string>\",\n \"project_id\": 123,\n \"frequency\": 1,\n \"personality_ids\": [\n 123\n ],\n \"test_profile_ids\": [\n 123\n ],\n \"timeout\": 1800,\n \"agent_version_id\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"name": "<string>",
"id": 123,
"agent": 123,
"agent_inbound": true,
"status": "pending",
"success_rate": 0,
"run_as_text": false,
"is_cronjob": "<string>",
"runs": {},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}{
"field_name": [
"<string>"
]
}Run Evaluator (API Chat)
Start API chat runs you drive turn-by-turn over REST. No chat provider needs to be configured.
curl --request POST \
--url https://api.cekura.ai/test_framework/v1/scenarios/run_scenarios_api_chat/ \
--header 'Content-Type: application/json' \
--header 'X-CEKURA-API-KEY: <api-key>' \
--data '
{
"agent_id": 123,
"assistant_id": "<string>",
"name": "<string>",
"scenarios": [
123
],
"tags": [
"<string>"
],
"folder_path": "<string>",
"project_id": 123,
"frequency": 1,
"personality_ids": [
123
],
"test_profile_ids": [
123
],
"timeout": 1800,
"agent_version_id": "<string>"
}
'import requests
url = "https://api.cekura.ai/test_framework/v1/scenarios/run_scenarios_api_chat/"
payload = {
"agent_id": 123,
"assistant_id": "<string>",
"name": "<string>",
"scenarios": [123],
"tags": ["<string>"],
"folder_path": "<string>",
"project_id": 123,
"frequency": 1,
"personality_ids": [123],
"test_profile_ids": [123],
"timeout": 1800,
"agent_version_id": "<string>"
}
headers = {
"X-CEKURA-API-KEY": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-CEKURA-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
agent_id: 123,
assistant_id: '<string>',
name: '<string>',
scenarios: [123],
tags: ['<string>'],
folder_path: '<string>',
project_id: 123,
frequency: 1,
personality_ids: [123],
test_profile_ids: [123],
timeout: 1800,
agent_version_id: '<string>'
})
};
fetch('https://api.cekura.ai/test_framework/v1/scenarios/run_scenarios_api_chat/', 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/run_scenarios_api_chat/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'agent_id' => 123,
'assistant_id' => '<string>',
'name' => '<string>',
'scenarios' => [
123
],
'tags' => [
'<string>'
],
'folder_path' => '<string>',
'project_id' => 123,
'frequency' => 1,
'personality_ids' => [
123
],
'test_profile_ids' => [
123
],
'timeout' => 1800,
'agent_version_id' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.cekura.ai/test_framework/v1/scenarios/run_scenarios_api_chat/"
payload := strings.NewReader("{\n \"agent_id\": 123,\n \"assistant_id\": \"<string>\",\n \"name\": \"<string>\",\n \"scenarios\": [\n 123\n ],\n \"tags\": [\n \"<string>\"\n ],\n \"folder_path\": \"<string>\",\n \"project_id\": 123,\n \"frequency\": 1,\n \"personality_ids\": [\n 123\n ],\n \"test_profile_ids\": [\n 123\n ],\n \"timeout\": 1800,\n \"agent_version_id\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-CEKURA-API-KEY", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.cekura.ai/test_framework/v1/scenarios/run_scenarios_api_chat/")
.header("X-CEKURA-API-KEY", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"agent_id\": 123,\n \"assistant_id\": \"<string>\",\n \"name\": \"<string>\",\n \"scenarios\": [\n 123\n ],\n \"tags\": [\n \"<string>\"\n ],\n \"folder_path\": \"<string>\",\n \"project_id\": 123,\n \"frequency\": 1,\n \"personality_ids\": [\n 123\n ],\n \"test_profile_ids\": [\n 123\n ],\n \"timeout\": 1800,\n \"agent_version_id\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cekura.ai/test_framework/v1/scenarios/run_scenarios_api_chat/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-CEKURA-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"agent_id\": 123,\n \"assistant_id\": \"<string>\",\n \"name\": \"<string>\",\n \"scenarios\": [\n 123\n ],\n \"tags\": [\n \"<string>\"\n ],\n \"folder_path\": \"<string>\",\n \"project_id\": 123,\n \"frequency\": 1,\n \"personality_ids\": [\n 123\n ],\n \"test_profile_ids\": [\n 123\n ],\n \"timeout\": 1800,\n \"agent_version_id\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"name": "<string>",
"id": 123,
"agent": 123,
"agent_inbound": true,
"status": "pending",
"success_rate": 0,
"run_as_text": false,
"is_cronjob": "<string>",
"runs": {},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}{
"field_name": [
"<string>"
]
}Authorizations
API Key Authentication. It should be included in the header of each request.
Body
Schema for the run_scenarios_api_chat endpoint (customer-driven pull mode).
Same selection fields as the other run endpoints (agent_id, scenarios/tags/
folder_path, frequency, personality/test-profile overrides) plus timeout.
ID of the agent to run evaluators for
Alternative to agent ID - the assistant ID to use for this scenario
Example: "asst_1234567890"
Label text for result
List of evaluator IDs to run. Either scenarios, tags, or folder_path must be provided.
Runs start in the order given.
Example: [11, 22, 33]
To run evaluators by tag or folder, use the tags or folder_path fields instead.
List of tags to filter evaluators to run. Either evaluators or tags must be provided.
Example: ["tag1", "tag2", "tag3"]
Dot-separated folder path to select evaluators from (e.g. "Sales.Inbound").
Mutually exclusive with scenarios and tags. Requires project_id.
Project ID. Required when using folder_path (or when passing a folder path string via scenarios).
Example: 1376
The number of times each evaluator will run. Each repeat runs the whole list in order
before the next one starts (A, B, A, B), rather than grouping repeats of one evaluator.
Example: 1
x >= 1Personality IDs to override for this run. Defaults to each scenario's personality.
Test-profile IDs to override for this run. Defaults to each scenario's test profile.
Overall run timeout in seconds — the whole conversation's max lifetime (NOT a per-message timeout). When it elapses the run is finalized and scored automatically. Defaults to the project's configured duration. Capped at 3600 (1 hour).
1 <= x <= 3600Run against a stored version of the agent instead of the agent as it is live. Cekura makes a
private copy of the agent in your provider account, puts that version's prompt on it, and
runs against the copy — voice, model and tools stay as the agent is configured now, and the
live agent is never changed. Accepts the version label shown in the agent's version history
(v12, or p1 for a version an improvement run proposed) or its numeric history_id.
List them with GET /test_framework/v1/aiagents/{id}/history/; a version is usable when its
is_runnable is true. Available for VAPI, Retell, ElevenLabs and Bland agents that are
outbound and have a single prompt.
Example: "v12"
Response
Name of the Result
Example: "Test Result 1"
255Unique identifier for the Result
Example: 123
ID of the AI agent that was tested
Example: 123
Whether the agent is configured for inbound calls (true) or outbound calls (false)
Example: true or false
Current status of the result
running- Runningcompleted- Completedfailed- Failedpending- Pendingin_progress- In Progressevaluating- Evaluatingin_queue- In Queuetimeout- Timeoutcancelled- Cancelledscaling_up- Scaling Up
running, completed, failed, pending, in_progress, evaluating, in_queue, timeout, cancelled, scaling_up Percentage of runs that passed, 0 to 100
Whether this test was run in text mode instead of voice mode
Example: true or false
Whether this result was created by a scheduled cronjob
Example: true or false
Run summaries for this result. For full run data including transcripts and metric scores, fetch the result detail endpoint — there runs is a dict keyed by run ID.
Show child attributes
Show child attributes
Timestamp when this test result was created
Example: 2021-01-01 00:00:00
Timestamp when this test result was last updated