> ## 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. # 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. ## OpenAPI ````yaml post /schedules/v1/cron-jobs/ openapi: 3.1.0 info: title: Cekura API version: v1 description: >- Complete API documentation for the Cekura platform. This API provides endpoints for testing, observing, and evaluating AI voice agents — including managing agents, running evaluators, defining metrics, and analyzing call quality. servers: - url: https://api.cekura.ai security: [] paths: /schedules/v1/cron-jobs/: post: tags: - Schedules summary: Schedule a recurring evaluator run description: >- 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. **Scenario selection (pick one):** - `scenarios` — explicit list of evaluator IDs - `tags` — run every evaluator matching these tags **Execution mode** (`execution_mode`) — defaults to voice; also supports `text`, `sip`, etc. Matches the corresponding `run_scenarios` / `run_scenarios_text` endpoint. **Schedule:** `crontab_expression` uses standard cron syntax (`minute hour day month day-of-week`). Combine with `timezone` (IANA name, e.g. `America/New_York`) to control when the job fires. **Run size:** `frequency` multiplies each scenario. Personality / test-profile overrides behave identically to `run_scenarios` — same billing rules apply. operationId: cron-jobs-create requestBody: content: application/json: schema: $ref: '#/components/schemas/SchemaPostCronJob' examples: CreateScheduledJobWithScenarios: value: name: Daily Agent Test scenarios: - 1 - 2 - 3 agent: 1 crontab_expression: 0 9 * * 1-5 timezone: America/New_York summary: Create Scheduled Job with Scenarios CreateScheduledJobWithTags: value: name: Weekly Regression Test tags: - regression - high-priority agent: 1 crontab_expression: 0 0 * * 0 timezone: UTC summary: Create Scheduled Job with Tags application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/SchemaPostCronJob' multipart/form-data: schema: $ref: '#/components/schemas/SchemaPostCronJob' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/CronJob' description: '' security: - api_key: [] components: schemas: SchemaPostCronJob: type: object properties: name: type: string description: Name for the cronjob scenarios: type: array items: type: integer description: | List of scenario IDs to execute Example: `[123, 456, 789]` tags: type: array items: type: string description: | Alternative to scenarios - List of tags to filter scenario Example: `["tag1", "tag2", "tag3"]` agent: type: integer description: | Agent ID. Required when using tags to filter scenarios. Example: `123` crontab_expression: type: string description: > Cron expression for scheduling (e.g. '0 9 * * 1-5' for weekdays at 9am) Example: - `"0 9 * * 1-5"` - `"0 0 * * 0"` timezone: enum: - 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 type: string x-spec-enum-id: 6e7339d971185fa9 description: |- 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 personality: type: integer description: 'DEPRECATED: Use personalities instead' personalities: type: array items: type: integer description: > 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: type: boolean default: false description: >- DEPRECATED: Use execution_mode instead. Run scenarios as text-based chat instead of voice calls execution_mode: enum: - voice - text - sip - vapi_webrtc - retell_webrtc - elevenlabs - ello - livekit_v2 - pipecat_v2 type: string x-spec-enum-id: 6e5503f819d0efa7 default: voice description: |- 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 required: - crontab_expression CronJob: type: object properties: id: type: integer readOnly: true agent: type: integer description: | Agent ID for the cron job Example: `123` name: type: string description: Name for the cronjob maxLength: 255 crontab_expression: type: string description: | Crontab expression for the cron job Example: - `"0 9 * * 1-5"` - `"0 0 * * 0"` maxLength: 255 timezone: type: string description: | Timezone for the cron job Example: `"America/Los_Angeles"` scenarios: writeOnly: true description: | List of scenario IDs for the cron job Example: `[123, 456, 789]` scenario_ids: type: array items: type: integer readOnly: true description: | List of scenario IDs for the cron job Example: `[123, 456, 789]` scenarios_data: type: array items: $ref: '#/components/schemas/ScenarioInline' readOnly: true personality: type: - integer - 'null' description: | (Deprecated) Use personalities field instead. Example: `1` (personality ID) personalities: type: array items: type: integer description: > 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: type: array items: type: string description: | List of tags for the cron job Example: `["tag1", "tag2", "tag3"]` frequency: type: integer maximum: 100 minimum: 1 description: | Frequency for the cron job Example: `1` run_as_text: type: boolean description: > DEPRECATED: Use execution_mode instead. Kept for backward compatibility. Run the cron job as text Example: `true` or `false` execution_mode: enum: - voice - text - sip - vapi_webrtc - retell_webrtc - elevenlabs - ello - livekit_v2 - pipecat_v2 type: string x-spec-enum-id: 6e5503f819d0efa7 description: >- 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 notify_on: enum: - never - success - failure - both type: string x-spec-enum-id: d06ae6855e4121c0 description: |- Select when to notify * `never` - Never * `success` - Success * `failure` - Failure * `both` - Both is_active: type: boolean created_by: type: integer readOnly: true created_via: enum: - user - api - mcp - cli - sdk - null type: - string - 'null' x-spec-enum-id: 360ac7f2b69a95cc readOnly: true description: >- 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 created_at: type: string format: date-time readOnly: true description: | Timestamp when the cron job was created Example: `2021-01-01 00:00:00` updated_at: type: string format: date-time readOnly: true description: | Timestamp when the cron job was last updated Example: `2021-01-01 00:00:00` required: - crontab_expression ScenarioInline: type: object properties: id: type: integer readOnly: true agent: type: - integer - 'null' name: type: string description: Name of the scenario maxLength: 80 personality: type: - integer - 'null' personality_name: type: string readOnly: true securitySchemes: api_key: type: apiKey name: X-CEKURA-API-KEY in: header description: >- API Key Authentication. It should be included in the header of each request. ````