Skip to main content
A scheduled job fires a definition on a recurring cron schedule. Each scheduled job is backed by a managed schedule; every fire creates a normal job — visible under GET /definitions/{definition_id}/jobs with source: "schedule" and a scheduled_job_id linking back to the schedule that produced it. The job and execution lifecycle is otherwise identical to a manual trigger. 
{
  "id": "sched_c9beda5f",
  "definition_id": "def_a1b2c3d4",
  "description": "Refresh Five9 lists every 15 minutes",
  "cron_expression": "*/15 * * * *",
  "input_data": { "list": "prod" }
}
Create the scheduled job once; the platform re-fires it on every cron tick with no further calls from you.

​
The scheduled job object

FieldTypeDescription
idstringScheduled job identifier (e.g. sched_c9beda5f).
definition_idstringThe definition to fire. Must belong to your org. Immutable after creation — to point at a different definition, delete and recreate.
org_idstringOwning organization.
descriptionstringHuman-readable description (1–200 chars).
cron_expressionstring5-field UTC cron (e.g. */15 * * * *).
enabledbooleantrue fires on schedule; false creates or leaves the schedule paused without losing fire history.
input_dataobjectInput passed to each fired job — the same role as a trigger’s input_data.
metadataobjectFree-form metadata. Defaults to {}.
next_fire_atdatetimeComputed from cron_expression at read time — never stored.
last_fired_atdatetime | nullWhen the most recent fire occurred.
last_fire_statusstring | nullState of the most recent fire: running, success, or failure. Written by the worker as the fired job progresses.
Cron expressions are UTC-only and 5-field syntax only. Six-field expressions (with seconds), aliases like @reboot/@hourly/@daily/@weekly/@monthly/@yearly, and any timezone / tz field are rejected with 422. There is no per-schedule timezone — convert your local cadence to UTC before you set the expression.

​
Fire policy

The fire policy is fixed and not configurable:
  • Overlap = SKIP. If a previous fire is still running when the next cron tick arrives, that tick is dropped, not queued — a slow run never stacks up a backlog of overlapping fires.
  • 60-second catch-up window. Missed fires during downtime are replayed only within a 60-second window; anything older is skipped, so recovering from an outage never triggers a thundering herd of stale fires.

​
Managing scheduled jobs

All management endpoints require authentication and operate only on your organization’s schedules. Mutating endpoints require an admin-role caller (an X-API-Key is admin-equivalent).
MethodEndpointPurpose
POST/scheduled-jobsCreate a scheduled job and its backing schedule. Returns 201.
GET/scheduled-jobsList your org’s schedules with cursor pagination (cursor, limit), newest first.
GET/scheduled-jobs/{scheduled_job_id}Fetch one schedule; next_fire_at is computed at read time.
PATCH/scheduled-jobs/{scheduled_job_id}Partial update — change the cadence, pause/resume with enabled, or update input_data. Fire history is preserved.
DELETE/scheduled-jobs/{scheduled_job_id}Remove the backing schedule then the record. Returns 204. Jobs already fired are unaffected.
Creating one: 
curl -X POST "$BASE_URL/scheduled-jobs" \
  -H "X-API-Key: $GETDIALED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "definition_id": "def_a1b2c3d4",
    "description": "Refresh Five9 lists every 15 minutes",
    "cron_expression": "*/15 * * * *",
    "input_data": { "list": "prod" }
  }'
PATCH updates the backing schedule in place — a new cron_expression re-times future fires, and toggling enabled pauses or unpauses the schedule, but neither resets the fire history. DELETE is idempotent: if the backing schedule is already gone, the record is still removed and the call returns 204.
next_fire_at is derived from the cron expression every time you read the object, so it always reflects the current cadence even immediately after a PATCH. Poll last_fired_at / last_fire_status to confirm a schedule is firing as expected.

​
Next steps

Schedule a flow

A step-by-step walkthrough: create, pause, and re-time a recurring schedule.

Jobs and executions

Follow the jobs each fire produces through their execution lifecycle.