When you trigger a definition, GetDialed creates two kinds of records: one job for the triggering event, and one or more executions for the actual runs. You never create jobs or executions directly — they’re always produced by a trigger.
Jobs
A job represents one triggering event and groups every execution it produced. Key fields:
| Field | Description |
|---|
definition_id | The definition that was triggered |
source | Trigger origin. Defaults to api; recurring schedules set schedule; you can pass your own (e.g., csv_upload) |
status | See the lifecycle table below |
record_count | How many executions this job fans out to. 1 for a simple trigger, N when you trigger with records |
input_data | The input object for a single-record trigger |
records | The record array for a multi-record trigger |
metadata | Arbitrary metadata you attached at trigger time |
scheduled_at | If set, the job waits until this time before running |
scheduled_job_id | Links back to the scheduled job that fired it, if any |
started_at, completed_at | Lifecycle timestamps |
Job status lifecycle
| Status | Meaning |
|---|
pending | Created, not yet started |
scheduled | Waiting for its scheduled_at time |
running | Executions are in flight |
completed | Every execution succeeded |
partially_failed | Some executions succeeded, some failed |
failed | Executions failed |
cancelled | Cancelled before it ran |
pending → running → completed | partially_failed | failed. Passing scheduled_at at trigger time inserts a scheduled stage before running. Only pending or scheduled jobs can be cancelled (DELETE /jobs/{id}) — anything already running returns 409.
Executions
An execution is one durable run processing one set of inputs. Each belongs to exactly one job:
| Field | Description |
|---|
job_id | The parent job |
definition_id | The definition being run |
status | See the lifecycle table below |
input_data | The inputs this specific run received |
workflow_id | Identifier of the underlying durable run |
result | The final output when the run completes |
error | The error message when the run fails |
started_at, completed_at | Lifecycle timestamps |
Execution status lifecycle
| Status | Meaning |
|---|
pending | Created, not yet picked up |
running | Steps are executing |
completed | Finished successfully — result is populated |
failed | Finished with an error — error is populated |
cancelled | Stopped before completion |
pending → running → completed | failed. List a job’s executions with GET /jobs/{job_id}/executions and fetch one with GET /executions/{id}.
Single-record vs. multi-record triggers
A trigger creates executions in one of two shapes:
- Single-record — pass
input_data. The job has record_count: 1 and one execution that receives your input_data.
- Multi-record (fan-out) — pass a
records array (up to 15,000,000 records). One execution is created per record, each receiving that record as its input. The job’s record_count is the array length, and its final status aggregates all children: all succeed → completed, all fail → failed, a mix → partially_failed.
See triggering with records for a walkthrough.
Recurring triggers: scheduled jobs
To run a definition on a repeating cadence, create a scheduled job with POST /scheduled-jobs. Each fire creates a normal job — visible under GET /definitions/{id}/jobs with source: "schedule" and a scheduled_job_id pointing back at the schedule — so the job and execution lifecycle above applies unchanged.
| Field | Description |
|---|
definition_id | The definition to fire. Immutable after creation |
description | Human-readable description (1–200 chars) |
cron_expression | 5-field UTC cron, e.g. */15 * * * * |
enabled | Default true. Set false to pause without losing fire history |
input_data | Input passed to each fired job |
metadata | Free-form metadata |
next_fire_at | Computed from the cron expression at read time |
last_fired_at, last_fire_status | The most recent fire and its state: running, success, or failure |
Cron expressions are UTC-only and 5-field syntax only. Six-field expressions (with seconds), aliases like @hourly, and any timezone field are rejected with 422.
PATCH /scheduled-jobs/{id} (change the cron expression, pause/resume with enabled, update input_data) and DELETE /scheduled-jobs/{id} — deleting a schedule never affects jobs it already fired.