Batches, jobs, and executions

When you trigger a definition, GetDialed records the run as a four-level chain: Trigger → Batch → Job → Execution

A trigger is the immutable audit anchor for the triggering event.
A batch is the rollup for that one trigger — aggregate metadata and counts, one per triggering event.
A job is one record. Every record you trigger gets its own job carrying that record’s resolved input_data. This is where per-record inputs and status live.
An execution is the durable run that actually processes one job.

You never create batches, jobs, or executions directly — they’re always produced by a trigger.

Batch vs. Job. A batch is the whole triggering event (the rollup); a job is a single record inside it. Per-record inputs live on jobs, not on the batch — the batch carries record_count, not the record array. To read the records of a batch, list its jobs with GET /flows/jobs?batch_id=<batch_id>.

Batches

A batch represents one triggering event and groups every execution it produced. Key fields:

Field	Description
`id`	The batch’s own identifier (e.g. `batch_55667788`)
`definition_id`	The definition that was triggered
`trigger_id`	The trigger that produced this batch — the immutable audit anchor
`trigger_type`	The entry point that created the trigger: `api_call`, `webhook`, `schedule`, or `event`
`trigger_source`	Optional caller-supplied provenance label (e.g. `salesforce`, `ui`). `null` when not supplied
`status`	See the lifecycle table below
`record_count`	How many jobs (and therefore executions) this batch fans out to. `1` for a simple trigger, `N` when you trigger with records
`metadata`	Arbitrary metadata you attached at trigger time
`scheduled_at`	If set, the batch waits until this time before running
`schedule_id`	Links back to the schedule that fired it, if any
`started_at`, `completed_at`	Lifecycle timestamps

trigger_type and trigger_source are two independent dimensions. Type is the deterministic entry point (api_call / webhook / schedule / event); source is the free-form caller label you pass at trigger time. Filter or group on either one. See Triggers for the full model.

Contract change: the batch no longer embeds per-record data. Earlier versions exposed input_data and records on the batch object. Those fields are gone — per-record inputs now live on jobs. Read them with GET /flows/jobs?batch_id=<batch_id>; the batch keeps only the record_count rollup.

Batch status lifecycle

Status	Meaning
`pending`	Created, not yet started
`queued`	Bulk path only. Every uploaded row now has a job and an execution, and the batch is waiting to be processed
`scheduled`	Waiting for its `scheduled_at` time
`running`	Executions are in flight
`paused`	An admin paused this batch’s dispatch. Not terminal — resuming restores the status the batch held before the pause. See Dispatch pacing
`completed`	Every execution succeeded
`completed_with_errors`	Bulk path only. At least one uploaded row was accepted by your platform, and some were rejected or left unresolved — see Import outcomes
`partially_failed`	Some executions succeeded, some failed
`failed`	Executions failed — or, on the bulk path, no uploaded row at all was accepted
`cancelled`	Cancelled

A batch moves pending → running → completed | partially_failed | failed. Passing scheduled_at at trigger time inserts a scheduled stage before running. On the bulk path the terminal state is decided by the import counters instead, which is where completed_with_errors comes from. Any batch that has not already finished can be cancelled with POST /flows/batches/{batch_id}/cancel — including one that is actively running. A batch that has already completed, failed, or been cancelled returns 409. Cancelling needs no special role: any key for the owning organization can cancel that organization’s own batches.

DELETE /flows/batches/{batch_id} is the deprecated spelling of the same cancellation and additionally requires an admin role. Use the POST .../cancel verb; the DELETE form is kept only for existing integrations.

A batch triggered from a record set is minted pending while its rows are being bound, then flips to queued once every row has both a job and an execution. From queued, the batch’s delivery is paced against your Domain’s rate budget — sent as fast as the provider’s limits allow and never faster.

Account-wide runs feed

GET /flows/batches lists every batch across all of your definitions, newest first — the backing feed for a “recent runs” screen. GET /flows/definitions/{id}/batches is the same feed scoped to a single definition.

Parameter	Type	Description
`status`	enum	Filter to one batch status.
`definition_id`	string	Filter to batches from one definition.
`source`	string	Filter by trigger origin label (e.g. `api`, `schedule`).
`since`	datetime	Lower bound on `created_at` (`>=`).
`limit`	integer	Page size, 1–500 (default 50).
`cursor`	string	Opaque cursor from the previous response’s `next_cursor`.

The response is the converged Page envelope — items, total, limit, skip, and next_cursor. This is a data-family feed, so total is always null; page forward until next_cursor is null, which signals no more rows. Only your own account’s batches are ever returned.

{
  "items": [
    {
      "id": "batch_55667788",
      "status": "completed",
      "trigger_id": "trigger_44556677",
      "trigger_type": "schedule",
      "trigger_source": null
    }
  ],
  "total": null,
  "limit": 50,
  "skip": 0,
  "next_cursor": "eyJjcmVhdGVkX2F0Ijog..."
}

Jobs

A job is one record inside a batch. When you trigger with a single input you get one job; when you trigger with records you get one job per record. The job is the per-record audit point — it holds the resolved input_data for that record and the per-record status. Today each job maps 1:1 to one execution.

Field	Description
`id`	The job’s own identifier (e.g. `job_99aabbcc`)
`batch_id`	The parent batch this job belongs to
`trigger_id`	The trigger that produced this job
`trigger_type`, `trigger_source`	The trigger dimensions, denormalized so the jobs feed can filter/group without a second lookup
`definition_id`	The definition being run
`status`	See the lifecycle table below
`input_data`	The resolved record for this job — the per-record input that used to live on the batch
`scheduled_start_at`	Reserved for future per-record scheduling (see the note below)
`started_at`, `completed_at`	Lifecycle timestamps
`created_at`, `updated_at`	Audit timestamps

Job status lifecycle

Status	Meaning
`staged`	Bulk path only. An uploaded row that exists before any batch — it belongs to a record set that has not been triggered yet
`queued`	Bulk path only. The row has been bound to a batch and has an execution, and is waiting to be processed
`pending`	The job’s batch is deferred (`scheduled_at`) and nothing has dispatched yet
`started`	The job has been dispatched to its execution (the immediate default). A job stays `started` even while its execution is `waiting` — the job layer mirrors only terminal states
`needs_reconcile`	Bulk path only. The upload carrying this row went out but no confirmation came back. Not terminal — the row is held, never blindly retried. See Dispatch pacing
`completed`	The job’s execution finished successfully
`failed`	The job’s execution finished with an error
`cancelled`	The job’s batch was cancelled before it finished
`accepted`	Bulk path only. Your platform took this row into the list — see Import outcomes
`rejected`	Bulk path only. Your platform refused this row, and kept its own reason for doing so
`unprocessed`	Bulk path only. The row was never sent, because its batch was cancelled first
`unresolved`	Bulk path only. The row’s outcome could not be determined and never will be — held out of any automatic retry

On the immediate path jobs are written straight to started — there is no pending window. When you defer a batch with scheduled_at, its jobs are created pending until the batch runs. The terminal status (completed / failed) mirrors the job’s execution: the execution is the source of truth, and the job’s terminal state is set to match. Cancelling a batch flips its non-terminal jobs to cancelled, except on the bulk path, where rows that were never sent settle as unprocessed.

The last four are import outcomes, not execution outcomes. A bulk row ends at the answer your platform gave for that record — accepted, rejected, unprocessed or unresolved — while completed / failed continue to describe the per-record execution path exactly as before. Import outcomes covers what each one means, why a rejection carries both the provider’s own text and a normalized class, and how the four roll up into a batch’s terminal state.

scheduled_start_at exists in the schema but per-record scheduling is not enabled yet. Sending a future scheduled_start_at is rejected with 422 — there is no accept-and-ignore. Per-record scheduling, cancellation, and reschedule arrive in a later stage.

Jobs on the bulk path

Uploading a record set does not change the shape of the chain. Each uploaded row is one job and one execution — the 1:1 relationship is exactly the same as on the inline path, at any volume. What differs is where the row’s data lives. On the bulk path the record is stored only on the job, as its input_data; the execution references its job by job_id rather than carrying a second copy of the record. So to read what was uploaded, read the job. A row’s own lifecycle before it starts is staged → queued: staged while it belongs to a record set that has not been triggered, queued once a trigger has bound it to a batch and given it an execution. From queued the row is dispatched to your platform and ends at the answer that platform gave for it — accepted, rejected, unprocessed or unresolved. See Import outcomes.

Listing jobs

GET /flows/jobs lists every job across all of your definitions, newest first. Scope to one batch with GET /flows/jobs?batch_id=<batch_id> — this is how you read the per-record inputs that used to be embedded on the batch.

Parameter	Type	Description
`batch_id`	string	Filter to the jobs of one batch.
`record_set_id`	string	Filter to the jobs staged from one record set — one upload’s own view. Unlike the account-wide feed, this includes that upload’s `staged` rows.
`status`	enum	Filter to one job status. Pass `staged` explicitly to see not-yet-triggered uploaded rows.
`limit`	integer	Page size, 1–500 (default 50).
`cursor`	string	Opaque cursor from the previous response’s `next_cursor`.

The response is the converged Page envelope (items, total, limit, skip, next_cursor). Like the batches feed, this is a data-family feed, so total is always null; page forward until next_cursor is null. Fetch one job with GET /flows/jobs/{job_id}; a missing or cross-tenant job returns 404.

Behavior change: GET /flows/jobs no longer returns staged rows by default. A record set stages one job per uploaded record, so a single 1,000,000-row upload would otherwise bury every other job in the feed. Rows still carrying a record_set_id and a staged status are therefore excluded unless you ask for them by name with GET /flows/jobs?status=staged.Rows that have been triggered are unaffected — once a record set is consumed its rows become queued and appear in the default feed like any other job, and GET /flows/jobs?batch_id=<batch_id> returns them as normal.

A finished bulk upload dominates the default feed. Once a large import settles, its rows are ordinary finished jobs — mostly accepted — and the feed is newest-first, so they fill the first pages and everything else sits behind them.That is the feed working as specified, not a bug to page through. Filter instead: status= for one outcome, batch_id= for one run, or record_set_id= for one upload. See Import outcomes.

Executions

An execution is one durable run processing one set of inputs. Each belongs to exactly one batch (and, 1:1, one job):

Field	Description
`batch_id`	The parent batch
`job_id`	The job this execution ran — join to `GET /flows/jobs/{job_id}` for the per-record view. Empty string on executions that predate the job layer
`trigger_id`	The trigger this execution traces back to
`trigger_type`, `trigger_source`	Denormalized trigger dimensions, so the executions feed can filter/group by trigger without a second lookup
`definition_id`	The definition being run
`status`	See the lifecycle table below
`input_data`	The inputs this specific run received. On the bulk path the record lives only on the job — read it with `GET /flows/jobs/{job_id}`
`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
`waiting`	Not terminal. A step is parked — waiting for an external signal, for a reply, or for its time window to open. Nothing is stuck and nothing has failed; the execution returns to `running` the moment the wait ends, whichever way it ends
`completed`	Finished successfully — `result` is populated
`failed`	Finished with an error — `error` is populated
`cancelled`	Stopped before completion

An execution moves pending → running → completed | failed, with any number of running → waiting → running excursions along the way.

waiting is what a long pause looks like from the outside. A signaled task or a send-and-wait can be parked for hours or days, and before this status existed such a run reported running the whole time — indistinguishable from one that was actually doing something.Two consequences worth knowing. started_at is not re-stamped on resume, so a two-day wait reads as a two-day run rather than a two-second one. And cancelling a batch settles its waiting executions like any other non-terminal state — a parked execution is never stranded under a cancelled batch.

The job document does not mirror waiting — it stays started. Job statuses mirror only the terminal state of their execution, so a parked run’s job continues to report started while its execution reports waiting.That is by design rather than a discrepancy to report: the job layer answers “what became of this record”, and a pause is not an outcome. Read the execution when you want to know whether a run is parked.

List a batch’s executions with GET /flows/batches/{batch_id}/executions and fetch one with GET /flows/executions/{id}. That listing’s status filter accepts waiting like any other status, so “which of this batch’s runs are parked” is one query.

Per-step run detail

GET /flows/executions/{id} embeds a per-step breakdown so a run-detail screen renders in one call — the step list is bounded by the definition’s task chain, so there is no pagination and no per-step endpoint. Two fields carry it:

Field	Type	Description
`steps`	array \| null	One row per step: `step_name`, `step_index`, `status`, `started_at`, `completed_at`, and structured error fields (`error_type`, `message`) on failures. Never includes step input/output payloads.
`steps_source`	enum	Where `steps` came from — see below.

steps_source is always set on the detail route so a client can distinguish “this run genuinely has no steps” from “step detail isn’t available for this run”:

Value	Meaning
`live`	Folded from the execution’s still-live event stream — the most detailed view.
`snapshot`	A durable per-step summary captured when the run reached its terminal state. Timing and errors only, no payloads.
`unavailable`	No step detail exists — an older run from before this feature, or one whose events have aged out with no snapshot.

steps and steps_source are populated only on the single-execution detail route (GET /flows/executions/{id}). The executions list route leaves them null — it isn’t the run-detail consumer.

Single-record vs. multi-record triggers

A trigger creates jobs (and their executions) in one of two shapes:

Single-record — pass input_data. The batch has record_count: 1 and one job that receives your input_data, which runs as one execution.
Multi-record (fan-out) — pass a records array (up to 10,000 records inline). One job is created per record, each carrying that record as its input_data, and each job runs its own execution. The batch’s record_count is the array length, and its final status aggregates all children: all succeed → completed, all fail → failed, a mix → partially_failed. Read the individual records with GET /flows/jobs?batch_id=<batch_id>.
Bulk (by reference) — beyond 10,000 records, upload a record set and pass record_set_id instead of records. The shape is identical (one job and one execution per row); only the delivery of the records into the platform differs. Up to 5,000,000 records per set.

See triggering with records for the inline walkthrough and bulk ingestion for the record-set path.

Recurring triggers: schedules

To run a definition on a repeating cadence, create a schedule with POST /flows/schedules. Each fire creates a normal batch — visible under GET /flows/definitions/{id}/batches with trigger_type: "schedule" and a schedule_id pointing back at the schedule — so the batch 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 batch
`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.

Fire behavior is fixed: if a previous fire is still running when the next tick arrives, that tick is skipped, not queued. Missed fires during downtime are replayed only within a 60-second catch-up window. Manage schedules with PATCH /flows/schedules/{id} (change the cron expression, pause/resume with enabled, update input_data) and DELETE /flows/schedules/{id} — deleting a schedule never affects batches it already fired.

Getting Started

Core Concepts

Building Flows

Triggers & Streaming

Batches, jobs, and executions

Batches

Batch status lifecycle

Account-wide runs feed

Jobs

Job status lifecycle

Jobs on the bulk path

Listing jobs

Executions

Execution status lifecycle

Per-step run detail

Single-record vs. multi-record triggers

Recurring triggers: schedules

​Batches

​Batch status lifecycle

​Account-wide runs feed

​Jobs

​Job status lifecycle

​Jobs on the bulk path

​Listing jobs

​Executions

​Execution status lifecycle

​Per-step run detail

​Single-record vs. multi-record triggers

​Recurring triggers: schedules

Batches

Batch status lifecycle

Account-wide runs feed

Jobs

Job status lifecycle

Jobs on the bulk path

Listing jobs

Executions

Execution status lifecycle

Per-step run detail

Single-record vs. multi-record triggers

Recurring triggers: schedules