Skip to main content
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"
}
'
{
  "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_as_text": true,
  "is_active": true,
  "created_by": 123,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

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.

Authorizations

​
X-CEKURA-API-KEY
string
header
required

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

Body

​
crontab_expression
string
required

Cron expression for scheduling (e.g. '0 9 * * 1-5' for weekdays at 9am) Example:

  • "0 9 * * 1-5"
  • "0 0 * * 0"
​
name
string

Name for the cronjob

​
scenarios
integer[]

List of scenario IDs to execute Example: [123, 456, 789]

​
tags
string[]

Alternative to scenarios - List of tags to filter scenario Example: ["tag1", "tag2", "tag3"]

​
agent
integer

Agent ID. Required when using tags to filter scenarios. Example: 123

​
timezone
enum<string>

Timezone for the cronjob (default: Project timezone)

  • Africa/Abidjan - Africa/Abidjan
  • Africa/Accra - Africa/Accra
  • Africa/Addis_Ababa - Africa/Addis_Ababa
  • Africa/Algiers - Africa/Algiers
  • Africa/Asmara - Africa/Asmara
  • Africa/Bamako - Africa/Bamako
  • Africa/Bangui - Africa/Bangui
  • Africa/Banjul - Africa/Banjul
  • Africa/Bissau - Africa/Bissau
  • Africa/Blantyre - Africa/Blantyre
  • Africa/Brazzaville - Africa/Brazzaville
  • Africa/Bujumbura - Africa/Bujumbura
  • Africa/Cairo - Africa/Cairo
  • Africa/Casablanca - Africa/Casablanca
  • Africa/Ceuta - Africa/Ceuta
  • Africa/Conakry - Africa/Conakry
  • Africa/Dakar - Africa/Dakar
  • Africa/Dar_es_Salaam - Africa/Dar_es_Salaam
  • Africa/Djibouti - Africa/Djibouti
  • Africa/Douala - Africa/Douala
  • Africa/El_Aaiun - Africa/El_Aaiun
  • Africa/Freetown - Africa/Freetown
  • Africa/Gaborone - Africa/Gaborone
  • Africa/Harare - Africa/Harare
  • Africa/Johannesburg - Africa/Johannesburg
  • Africa/Juba - Africa/Juba
  • Africa/Kampala - Africa/Kampala
  • Africa/Khartoum - Africa/Khartoum
  • Africa/Kigali - Africa/Kigali
  • Africa/Kinshasa - Africa/Kinshasa
  • Africa/Lagos - Africa/Lagos
  • Africa/Libreville - Africa/Libreville
  • Africa/Lome - Africa/Lome
  • Africa/Luanda - Africa/Luanda
  • Africa/Lubumbashi - Africa/Lubumbashi
  • Africa/Lusaka - Africa/Lusaka
  • Africa/Malabo - Africa/Malabo
  • Africa/Maputo - Africa/Maputo
  • Africa/Maseru - Africa/Maseru
  • Africa/Mbabane - Africa/Mbabane
  • Africa/Mogadishu - Africa/Mogadishu
  • Africa/Monrovia - Africa/Monrovia
  • Africa/Nairobi - Africa/Nairobi
  • Africa/Ndjamena - Africa/Ndjamena
  • Africa/Niamey - Africa/Niamey
  • Africa/Nouakchott - Africa/Nouakchott
  • Africa/Ouagadougou - Africa/Ouagadougou
  • Africa/Porto-Novo - Africa/Porto-Novo
  • Africa/Sao_Tome - Africa/Sao_Tome
  • Africa/Tripoli - Africa/Tripoli
  • Africa/Tunis - Africa/Tunis
  • Africa/Windhoek - Africa/Windhoek
  • America/Adak - America/Adak
  • America/Anchorage - America/Anchorage
  • America/Chicago - America/Chicago
  • America/Denver - America/Denver
  • America/Los_Angeles - America/Los_Angeles
  • America/New_York - America/New_York
  • America/Phoenix - America/Phoenix
  • America/Sao_Paulo - America/Sao_Paulo
  • Asia/Dubai - Asia/Dubai
  • Asia/Hong_Kong - Asia/Hong_Kong
  • Asia/Kolkata - Asia/Kolkata
  • Asia/Seoul - Asia/Seoul
  • Asia/Shanghai - Asia/Shanghai
  • Asia/Singapore - Asia/Singapore
  • Asia/Tokyo - Asia/Tokyo
  • Australia/Melbourne - Australia/Melbourne
  • Australia/Perth - Australia/Perth
  • Australia/Sydney - Australia/Sydney
  • Europe/Amsterdam - Europe/Amsterdam
  • Europe/Berlin - Europe/Berlin
  • Europe/London - Europe/London
  • Europe/Madrid - Europe/Madrid
  • Europe/Moscow - Europe/Moscow
  • Europe/Paris - Europe/Paris
  • Europe/Rome - Europe/Rome
  • Pacific/Auckland - Pacific/Auckland
  • Pacific/Honolulu - Pacific/Honolulu
  • US/Central - US/Central
  • US/Eastern - US/Eastern
  • US/Mountain - US/Mountain
  • US/Pacific - US/Pacific
  • UTC - 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
​
personality
integer

DEPRECATED: Use personalities instead

​
personalities
integer[]

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)

​
run_as_text
boolean
default:false

DEPRECATED: Use execution_mode instead. Run scenarios as text-based chat instead of voice calls

​
execution_mode
enum<string>
default:voice

Execution mode for the cron job. Choices: voice, text, sip Example: "voice", "text", or "sip"

  • voice - Voice
  • text - Text
  • sip - SIP
  • vapi_webrtc - VAPI WebRTC
  • retell_webrtc - Retell WebRTC
  • elevenlabs - ElevenLabs
  • ello - Ello
  • livekit_v2 - LiveKit
  • pipecat_v2 - Pipecat
Available options:
voice,
text,
sip,
vapi_webrtc,
retell_webrtc,
elevenlabs,
ello,
livekit_v2,
pipecat_v2

Response

201 - application/json
​
crontab_expression
string
required

Crontab expression for the cron job Example:

  • "0 9 * * 1-5"
  • "0 0 * * 0"
Maximum string length: 255
​
id
integer
read-only
​
agent
integer

Agent ID for the cron job Example: 123

​
name
string

Name for the cronjob

Maximum string length: 255
​
timezone
string

Timezone for the cron job Example: "America/Los_Angeles"

​
scenario_ids
integer[]
read-only

List of scenario IDs for the cron job Example: [123, 456, 789]

​
scenarios_data
object[]
read-only
​
personality
integer | null

(Deprecated) Use personalities field instead. Example: 1 (personality ID)

​
personalities
integer[]

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)

​
tags
string[]

List of tags for the cron job Example: ["tag1", "tag2", "tag3"]

​
frequency
integer

Frequency for the cron job Example: 1

Required range: 1 <= x <= 100
​
run_as_text
boolean

DEPRECATED: Use execution_mode instead. Kept for backward compatibility. Run the cron job as text Example: true or false

​
execution_mode
enum<string>

Execution mode for the cron job Choices: voice, text, sip, vapi_webrtc, elevenlabs, pipecat_v2, livekit_v2, retell_webrtc, ello Example: "voice", "text", "sip", "pipecat_v2", "elevenlabs", or "livekit_v2"

  • voice - Voice
  • text - Text
  • sip - SIP
  • vapi_webrtc - VAPI WebRTC
  • retell_webrtc - Retell WebRTC
  • elevenlabs - ElevenLabs
  • ello - Ello
  • livekit_v2 - LiveKit
  • pipecat_v2 - Pipecat
Available options:
voice,
text,
sip,
vapi_webrtc,
retell_webrtc,
elevenlabs,
ello,
livekit_v2,
pipecat_v2
​
notify_on
enum<string>

Select when to notify

  • never - Never
  • success - Success
  • failure - Failure
  • both - Both
Available options:
never,
success,
failure,
both
​
is_active
boolean
​
created_by
integer
read-only
​
created_via
enum<string> | null
read-only

How the cron job was created: user (UI), api (API key), or mcp (MCP client)

  • user - User
  • api - API
  • mcp - MCP
  • cli - CLI
  • sdk - SDK
Available options:
user,
api,
mcp,
cli,
sdk,
null
​
created_at
string<date-time>
read-only

Timestamp when the cron job was created Example: 2021-01-01 00:00:00

​
updated_at
string<date-time>
read-only

Timestamp when the cron job was last updated Example: 2021-01-01 00:00:00