Schedule a recurring evaluator run
curl --request POST \
--url https://api.cekura.ai/schedules/v1/cron-jobs/ \
--header 'Content-Type: application/json' \
--header 'X-CEKURA-API-KEY: <api-key>' \
--data '
{
"crontab_expression": "<string>",
"name": "<string>",
"scenarios": [
123
],
"tags": [
"<string>"
],
"agent": 123,
"personality": 123,
"personalities": [
123
],
"run_as_text": false,
"execution_mode": "voice",
"run_settings": "<unknown>"
}
'import requests
url = "https://api.cekura.ai/schedules/v1/cron-jobs/"
payload = {
"crontab_expression": "<string>",
"name": "<string>",
"scenarios": [123],
"tags": ["<string>"],
"agent": 123,
"personality": 123,
"personalities": [123],
"run_as_text": False,
"execution_mode": "voice",
"run_settings": "<unknown>"
}
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({
crontab_expression: '<string>',
name: '<string>',
scenarios: [123],
tags: ['<string>'],
agent: 123,
personality: 123,
personalities: [123],
run_as_text: false,
execution_mode: 'voice',
run_settings: '<unknown>'
})
};
fetch('https://api.cekura.ai/schedules/v1/cron-jobs/', 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/schedules/v1/cron-jobs/",
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([
'crontab_expression' => '<string>',
'name' => '<string>',
'scenarios' => [
123
],
'tags' => [
'<string>'
],
'agent' => 123,
'personality' => 123,
'personalities' => [
123
],
'run_as_text' => false,
'execution_mode' => 'voice',
'run_settings' => '<unknown>'
]),
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/schedules/v1/cron-jobs/"
payload := strings.NewReader("{\n \"crontab_expression\": \"<string>\",\n \"name\": \"<string>\",\n \"scenarios\": [\n 123\n ],\n \"tags\": [\n \"<string>\"\n ],\n \"agent\": 123,\n \"personality\": 123,\n \"personalities\": [\n 123\n ],\n \"run_as_text\": false,\n \"execution_mode\": \"voice\",\n \"run_settings\": \"<unknown>\"\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/schedules/v1/cron-jobs/")
.header("X-CEKURA-API-KEY", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"crontab_expression\": \"<string>\",\n \"name\": \"<string>\",\n \"scenarios\": [\n 123\n ],\n \"tags\": [\n \"<string>\"\n ],\n \"agent\": 123,\n \"personality\": 123,\n \"personalities\": [\n 123\n ],\n \"run_as_text\": false,\n \"execution_mode\": \"voice\",\n \"run_settings\": \"<unknown>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cekura.ai/schedules/v1/cron-jobs/")
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 \"crontab_expression\": \"<string>\",\n \"name\": \"<string>\",\n \"scenarios\": [\n 123\n ],\n \"tags\": [\n \"<string>\"\n ],\n \"agent\": 123,\n \"personality\": 123,\n \"personalities\": [\n 123\n ],\n \"run_as_text\": false,\n \"execution_mode\": \"voice\",\n \"run_settings\": \"<unknown>\"\n}"
response = http.request(request)
puts response.read_body{
"crontab_expression": "<string>",
"id": 123,
"agent": 123,
"name": "<string>",
"timezone": "<string>",
"scenario_ids": [
123
],
"scenarios_data": [
{
"id": 123,
"agent": 123,
"name": "<string>",
"personality": 123,
"personality_name": "<string>"
}
],
"personality": 123,
"personalities": [
123
],
"tags": [
"<string>"
],
"frequency": 50,
"run_settings": "<unknown>",
"run_as_text": true,
"execution_mode": "voice",
"notify_on": "never",
"is_active": true,
"created_by": 123,
"created_via": "user",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}Evaluators
Create Cronjob
Create a cron job that runs evaluators against your agent on a recurring schedule (daily regression tests, hourly smoke tests, weekly rollups, etc.). The job invokes the same logic as run_scenarios but on a timer.
POST
/
schedules
/
v1
/
cron-jobs
/
Schedule a recurring evaluator run
curl --request POST \
--url https://api.cekura.ai/schedules/v1/cron-jobs/ \
--header 'Content-Type: application/json' \
--header 'X-CEKURA-API-KEY: <api-key>' \
--data '
{
"crontab_expression": "<string>",
"name": "<string>",
"scenarios": [
123
],
"tags": [
"<string>"
],
"agent": 123,
"personality": 123,
"personalities": [
123
],
"run_as_text": false,
"execution_mode": "voice",
"run_settings": "<unknown>"
}
'import requests
url = "https://api.cekura.ai/schedules/v1/cron-jobs/"
payload = {
"crontab_expression": "<string>",
"name": "<string>",
"scenarios": [123],
"tags": ["<string>"],
"agent": 123,
"personality": 123,
"personalities": [123],
"run_as_text": False,
"execution_mode": "voice",
"run_settings": "<unknown>"
}
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({
crontab_expression: '<string>',
name: '<string>',
scenarios: [123],
tags: ['<string>'],
agent: 123,
personality: 123,
personalities: [123],
run_as_text: false,
execution_mode: 'voice',
run_settings: '<unknown>'
})
};
fetch('https://api.cekura.ai/schedules/v1/cron-jobs/', 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/schedules/v1/cron-jobs/",
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([
'crontab_expression' => '<string>',
'name' => '<string>',
'scenarios' => [
123
],
'tags' => [
'<string>'
],
'agent' => 123,
'personality' => 123,
'personalities' => [
123
],
'run_as_text' => false,
'execution_mode' => 'voice',
'run_settings' => '<unknown>'
]),
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/schedules/v1/cron-jobs/"
payload := strings.NewReader("{\n \"crontab_expression\": \"<string>\",\n \"name\": \"<string>\",\n \"scenarios\": [\n 123\n ],\n \"tags\": [\n \"<string>\"\n ],\n \"agent\": 123,\n \"personality\": 123,\n \"personalities\": [\n 123\n ],\n \"run_as_text\": false,\n \"execution_mode\": \"voice\",\n \"run_settings\": \"<unknown>\"\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/schedules/v1/cron-jobs/")
.header("X-CEKURA-API-KEY", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"crontab_expression\": \"<string>\",\n \"name\": \"<string>\",\n \"scenarios\": [\n 123\n ],\n \"tags\": [\n \"<string>\"\n ],\n \"agent\": 123,\n \"personality\": 123,\n \"personalities\": [\n 123\n ],\n \"run_as_text\": false,\n \"execution_mode\": \"voice\",\n \"run_settings\": \"<unknown>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cekura.ai/schedules/v1/cron-jobs/")
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 \"crontab_expression\": \"<string>\",\n \"name\": \"<string>\",\n \"scenarios\": [\n 123\n ],\n \"tags\": [\n \"<string>\"\n ],\n \"agent\": 123,\n \"personality\": 123,\n \"personalities\": [\n 123\n ],\n \"run_as_text\": false,\n \"execution_mode\": \"voice\",\n \"run_settings\": \"<unknown>\"\n}"
response = http.request(request)
puts response.read_body{
"crontab_expression": "<string>",
"id": 123,
"agent": 123,
"name": "<string>",
"timezone": "<string>",
"scenario_ids": [
123
],
"scenarios_data": [
{
"id": 123,
"agent": 123,
"name": "<string>",
"personality": 123,
"personality_name": "<string>"
}
],
"personality": 123,
"personalities": [
123
],
"tags": [
"<string>"
],
"frequency": 50,
"run_settings": "<unknown>",
"run_as_text": true,
"execution_mode": "voice",
"notify_on": "never",
"is_active": true,
"created_by": 123,
"created_via": "user",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}Authorizations
api_keyoauth2supabase_session
API Key Authentication. It should be included in the header of each request.
Body
application/jsonapplication/x-www-form-urlencodedmultipart/form-data
Cron expression for scheduling (e.g. '0 9 * * 1-5' for weekdays at 9am) Example:
"0 9 * * 1-5""0 0 * * 0"
Name for the cronjob
List of scenario IDs to execute
Example: [123, 456, 789]
Alternative to scenarios - List of tags to filter scenario
Example: ["tag1", "tag2", "tag3"]
Agent ID. Required when using tags to filter scenarios.
Example: 123
Timezone for the cronjob (default: Project timezone)
Africa/Abidjan- Africa/AbidjanAfrica/Accra- Africa/AccraAfrica/Addis_Ababa- Africa/Addis_AbabaAfrica/Algiers- Africa/AlgiersAfrica/Asmara- Africa/AsmaraAfrica/Bamako- Africa/BamakoAfrica/Bangui- Africa/BanguiAfrica/Banjul- Africa/BanjulAfrica/Bissau- Africa/BissauAfrica/Blantyre- Africa/BlantyreAfrica/Brazzaville- Africa/BrazzavilleAfrica/Bujumbura- Africa/BujumburaAfrica/Cairo- Africa/CairoAfrica/Casablanca- Africa/CasablancaAfrica/Ceuta- Africa/CeutaAfrica/Conakry- Africa/ConakryAfrica/Dakar- Africa/DakarAfrica/Dar_es_Salaam- Africa/Dar_es_SalaamAfrica/Djibouti- Africa/DjiboutiAfrica/Douala- Africa/DoualaAfrica/El_Aaiun- Africa/El_AaiunAfrica/Freetown- Africa/FreetownAfrica/Gaborone- Africa/GaboroneAfrica/Harare- Africa/HarareAfrica/Johannesburg- Africa/JohannesburgAfrica/Juba- Africa/JubaAfrica/Kampala- Africa/KampalaAfrica/Khartoum- Africa/KhartoumAfrica/Kigali- Africa/KigaliAfrica/Kinshasa- Africa/KinshasaAfrica/Lagos- Africa/LagosAfrica/Libreville- Africa/LibrevilleAfrica/Lome- Africa/LomeAfrica/Luanda- Africa/LuandaAfrica/Lubumbashi- Africa/LubumbashiAfrica/Lusaka- Africa/LusakaAfrica/Malabo- Africa/MalaboAfrica/Maputo- Africa/MaputoAfrica/Maseru- Africa/MaseruAfrica/Mbabane- Africa/MbabaneAfrica/Mogadishu- Africa/MogadishuAfrica/Monrovia- Africa/MonroviaAfrica/Nairobi- Africa/NairobiAfrica/Ndjamena- Africa/NdjamenaAfrica/Niamey- Africa/NiameyAfrica/Nouakchott- Africa/NouakchottAfrica/Ouagadougou- Africa/OuagadougouAfrica/Porto-Novo- Africa/Porto-NovoAfrica/Sao_Tome- Africa/Sao_TomeAfrica/Tripoli- Africa/TripoliAfrica/Tunis- Africa/TunisAfrica/Windhoek- Africa/WindhoekAmerica/Adak- America/AdakAmerica/Anchorage- America/AnchorageAmerica/Chicago- America/ChicagoAmerica/Denver- America/DenverAmerica/Los_Angeles- America/Los_AngelesAmerica/New_York- America/New_YorkAmerica/Phoenix- America/PhoenixAmerica/Sao_Paulo- America/Sao_PauloAsia/Dubai- Asia/DubaiAsia/Hong_Kong- Asia/Hong_KongAsia/Kolkata- Asia/KolkataAsia/Seoul- Asia/SeoulAsia/Shanghai- Asia/ShanghaiAsia/Singapore- Asia/SingaporeAsia/Tokyo- Asia/TokyoAustralia/Melbourne- Australia/MelbourneAustralia/Perth- Australia/PerthAustralia/Sydney- Australia/SydneyEurope/Amsterdam- Europe/AmsterdamEurope/Berlin- Europe/BerlinEurope/London- Europe/LondonEurope/Madrid- Europe/MadridEurope/Moscow- Europe/MoscowEurope/Paris- Europe/ParisEurope/Rome- Europe/RomePacific/Auckland- Pacific/AucklandPacific/Honolulu- Pacific/HonoluluUS/Central- US/CentralUS/Eastern- US/EasternUS/Mountain- US/MountainUS/Pacific- US/PacificUTC- UTC
Available options:
Africa/Abidjan, Africa/Accra, Africa/Addis_Ababa, Africa/Algiers, Africa/Asmara, Africa/Bamako, Africa/Bangui, Africa/Banjul, Africa/Bissau, Africa/Blantyre, Africa/Brazzaville, Africa/Bujumbura, Africa/Cairo, Africa/Casablanca, Africa/Ceuta, Africa/Conakry, Africa/Dakar, Africa/Dar_es_Salaam, Africa/Djibouti, Africa/Douala, Africa/El_Aaiun, Africa/Freetown, Africa/Gaborone, Africa/Harare, Africa/Johannesburg, Africa/Juba, Africa/Kampala, Africa/Khartoum, Africa/Kigali, Africa/Kinshasa, Africa/Lagos, Africa/Libreville, Africa/Lome, Africa/Luanda, Africa/Lubumbashi, Africa/Lusaka, Africa/Malabo, Africa/Maputo, Africa/Maseru, Africa/Mbabane, Africa/Mogadishu, Africa/Monrovia, Africa/Nairobi, Africa/Ndjamena, Africa/Niamey, Africa/Nouakchott, Africa/Ouagadougou, Africa/Porto-Novo, Africa/Sao_Tome, Africa/Tripoli, Africa/Tunis, Africa/Windhoek, America/Adak, America/Anchorage, America/Chicago, America/Denver, America/Los_Angeles, America/New_York, America/Phoenix, America/Sao_Paulo, Asia/Dubai, Asia/Hong_Kong, Asia/Kolkata, Asia/Seoul, Asia/Shanghai, Asia/Singapore, Asia/Tokyo, Australia/Melbourne, Australia/Perth, Australia/Sydney, Europe/Amsterdam, Europe/Berlin, Europe/London, Europe/Madrid, Europe/Moscow, Europe/Paris, Europe/Rome, Pacific/Auckland, Pacific/Honolulu, US/Central, US/Eastern, US/Mountain, US/Pacific, UTC DEPRECATED: Use personalities instead
List of personalities to use for test execution. Multiple personalities can be assigned to run tests with different configurations.
Example: [1, 2, 3] (personality IDs)
DEPRECATED: Use execution_mode instead. Run scenarios as text-based chat instead of voice calls
Execution mode for the cron job. Choices: voice, text, sip
Example: "voice", "text", or "sip"
voice- Voicetext- Textsip- SIPvapi_webrtc- VAPI WebRTCretell_webrtc- Retell WebRTCelevenlabs- ElevenLabsello- Ellolivekit_v2- LiveKitpipecat_v2- Pipecatagora- Agora
Available options:
voice, text, sip, vapi_webrtc, retell_webrtc, elevenlabs, ello, livekit_v2, pipecat_v2, agora Connection overrides applied on every scheduled run, keyed as the matching run
endpoint accepts them. Accepted keys depend on execution_mode: voice takes
mode, outbound_phone_number, agent_number; text takes websocket_url,
outbound_phone_number, agent_number; sip takes sip_endpoint;
vapi_webrtc takes vapi_assistant_id; retell_webrtc takes retell_agent_id;
elevenlabs takes elevenlabs_agent_id and elevenlabs_data; livekit_v2 takes
livekit_data; pipecat_v2 takes pipecat_data. Unsupported keys are rejected.
Response
201 - application/json
Crontab expression for the cron job Example:
"0 9 * * 1-5""0 0 * * 0"
Maximum string length:
255Agent ID for the cron job
Example: 123
Name for the cronjob
Maximum string length:
255Timezone for the cron job
Example: "America/Los_Angeles"
List of scenario IDs for the cron job
Example: [123, 456, 789]
Show child attributes
Show child attributes
(Deprecated) Use personalities field instead.
Example: 1 (personality ID)
List of personalities to use for test execution. Multiple personalities can be assigned to run tests with different configurations.
Example: [1, 2, 3] (personality IDs)
List of tags for the cron job
Example: ["tag1", "tag2", "tag3"]
Frequency for the cron job
Example: 1
Required range:
1 <= x <= 100Connection overrides applied on every scheduled run. Keys must match what the matching run endpoint accepts, and depend on execution_mode:
- voice:
mode,outbound_phone_number,agent_number - text:
websocket_url,outbound_phone_number,agent_number - sip:
sip_endpoint - vapi_webrtc:
vapi_assistant_id - retell_webrtc:
retell_agent_id - elevenlabs:
elevenlabs_agent_id,elevenlabs_data - livekit_v2:
livekit_data - pipecat_v2:
pipecat_dataExample:{"livekit_data": {"agent_name": "support-agent", "config": {"greeting": "hi"}}}
DEPRECATED: Use execution_mode instead. Kept for backward compatibility.
Run the cron job as text
Example: true or false
Execution mode for the cron job
Choices: voice, text, sip, vapi_webrtc, elevenlabs, pipecat_v2, livekit_v2, retell_webrtc, ello, agora
Example: "voice", "text", "sip", "pipecat_v2", "elevenlabs", or "livekit_v2"
voice- Voicetext- Textsip- SIPvapi_webrtc- VAPI WebRTCretell_webrtc- Retell WebRTCelevenlabs- ElevenLabsello- Ellolivekit_v2- LiveKitpipecat_v2- Pipecatagora- Agora
Available options:
voice, text, sip, vapi_webrtc, retell_webrtc, elevenlabs, ello, livekit_v2, pipecat_v2, agora Select when to notify
never- Neversuccess- Successfailure- Failureboth- Both
Available options:
never, success, failure, both How the cron job was created: user (UI), api (API key), or mcp (MCP client)
user- Userapi- APImcp- MCPcli- CLIsdk- SDK
Available options:
user, api, mcp, cli, sdk, null Timestamp when the cron job was created
Example: 2021-01-01 00:00:00
Timestamp when the cron job was last updated
Example: 2021-01-01 00:00:00