Trigger with records

A trigger doesn’t have to carry a single input. Pass a records array — one object per row — and GetDialed fans the flow out: one batch for the trigger, one job per record, and one execution per job, all running concurrently. It’s the natural fit for anything row-shaped: a parsed CSV, a CRM export, a nightly batch of leads.

How fan-out works

When you POST /flows/definitions/{id}/trigger with records:

One batch is created with record_count equal to the number of records.
One job is created per record — the per-record audit point. Each record becomes that job’s input_data.
Each job runs one execution, so your definition’s expressions read the record’s fields via {{input.<column>}} — exactly as they would for a single trigger. All executions run concurrently and succeed or fail independently.
When every execution finishes, the batch gets an aggregate status.

Per-record inputs live on jobs, not on the batch. To read the individual records after triggering, list the batch’s jobs with GET /flows/jobs?batch_id=<batch_id> — the batch object itself only carries the record_count rollup.

Batch status	Meaning
`completed`	Every execution succeeded
`partially_failed`	Some executions succeeded, some failed
`failed`	Every execution failed

A single trigger accepts up to 10,000 inline records. Beyond that, upload a record set and trigger with record_set_id — see Bulk ingestion. An inline array over the cap is rejected with 422.

Example: load a contact list

Say you have a contact CSV:

first_name,last_name,phone
Alice,Nguyen,5551234567
Bob,Marsh,5559876543
Carla,Diaz,5555550123

Your flow reads each row’s columns through {{input.first_name}}, {{input.last_name}}, and {{input.phone}}. Parse the file into one dict per row and send the rows as records:

curl -X POST "$BASE_URL/flows/definitions/def_a1b2c3d4/trigger" \
  -H "X-API-Key: $GETDIALED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "csv_upload",
    "metadata": {
      "filename": "july-leads.csv",
      "uploaded_by": "alice@example.com"
    },
    "records": [
      {"first_name": "Alice", "last_name": "Nguyen", "phone": "5551234567"},
      {"first_name": "Bob",   "last_name": "Marsh",  "phone": "5559876543"},
      {"first_name": "Carla", "last_name": "Diaz",   "phone": "5555550123"}
    ]
  }'

{
  "batch_id": "batch_55667788",
  "definition_id": "def_a1b2c3d4",
  "status": "pending"
}

The definition can’t tell the difference between a single trigger and a fan-out — each execution sees one record as its input_data. Build the flow once, then trigger it with 1 record, 10,000 inline, or millions by way of a record set.

Track the batch and its executions

Fetch the batch to see the aggregate picture — record_count confirms how many executions were fanned out:

curl "$BASE_URL/flows/batches/batch_55667788" \
  -H "X-API-Key: $GETDIALED_API_KEY"

{
  "id": "batch_55667788",
  "definition_id": "def_a1b2c3d4",
  "trigger_id": "trigger_44556677",
  "trigger_type": "api_call",
  "trigger_source": null,
  "metadata": {"filename": "july-leads.csv", "uploaded_by": "alice@example.com"},
  "status": "partially_failed",
  "record_count": 3,
  "started_at": "2026-07-06T14:00:01Z",
  "completed_at": "2026-07-06T14:00:09Z"
}

A partially_failed batch means some rows made it and some didn’t. List just the failures to find out which:

curl "$BASE_URL/flows/batches/batch_55667788/executions?status=failed" \
  -H "X-API-Key: $GETDIALED_API_KEY"

Each failed execution carries its own input_data (the original record) and an error message — everything you need to fix the row and re-trigger just the failures as a new, smaller records array. To inspect the records themselves — the per-record inputs that used to be embedded on the batch — list the batch’s jobs:

curl "$BASE_URL/flows/jobs?batch_id=batch_55667788" \
  -H "X-API-Key: $GETDIALED_API_KEY"

Each job carries the record’s resolved input_data and its per-record status. Filter to just the failures with ?batch_id=batch_55667788&status=failed.

Defer the start with scheduled_at

To load records now but run them later — say, at the start of the calling window — add scheduled_at (ISO 8601):

curl -X POST "$BASE_URL/flows/definitions/def_a1b2c3d4/trigger" \
  -H "X-API-Key: $GETDIALED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "csv_upload",
    "records": [
      {"first_name": "Alice", "last_name": "Nguyen", "phone": "5551234567"}
    ],
    "scheduled_at": "2026-07-07T09:00:00Z"
  }'

The trigger response comes back with "status": "scheduled" instead of "pending", and the executions start at the given time. Until then the batch can still be cancelled with DELETE /flows/batches/{batch_id} — only pending and scheduled batches are cancellable.

Record provenance with source and metadata

Both fields are free-form provenance labels you attach at trigger time, so you can answer “where did this run come from?” weeks later. source is filterable on the account-wide runs feed (GET /flows/batches?source=...):

Field	Type	Default	Use it for
`source`	string	`"api"`	The trigger origin — e.g. `csv_upload`, `crm_sync`, `nightly_batch`. Filter the runs feed by it.
`metadata`	object	`{}`	Anything worth keeping with the batch — filename, uploader, batch IDs, correlation IDs

Neither affects execution; they exist purely for auditing and filtering on your side.

Trigger request reference

Field	Type	Required	Description
`source`	string	no	Trigger origin label. Default `"api"`
`metadata`	object	no	Arbitrary provenance data stored on the batch. Default `{}`
`input_data`	object	no	Input for a single-execution trigger. Default `{}`
`records`	array of objects	no	One object per row; if non-empty, one job (and execution) per record. Max 10,000
`record_set_id`	string	no	A sealed record set to trigger instead of inline `records`. Mutually exclusive with `records`
`scheduled_at`	string (ISO 8601)	no	Batch-level defer; batch status becomes `scheduled`. Supported today.
`scheduled_start_at`	string (ISO 8601)	no	Per-record scheduled start. Part of the final job schema, but not enabled yet — see the warning below.

The definition must be active — triggering a draft or archived definition returns 400. See Build your first flow for the create-and-activate walkthrough.

scheduled_start_at (the per-record start time on jobs) is present in the schema so clients can build against the finished shape, but per-record scheduling is not enabled yet. A future scheduled_start_at is rejected with 422 — there is no accept-and-ignore. To defer a whole batch today, use the batch-level scheduled_at above. (This is distinct from scheduled_at, which is supported.)

Next steps

Bulk ingestion

Past 10,000 records — upload a record set in chunks and trigger by reference.

Batches and executions

The full lifecycle and every status in detail.

Batching

Aggregate records across executions into efficient platform calls.

Getting Started

Core Concepts

Building Flows

Triggers & Streaming

How fan-out works

Example: load a contact list

Track the batch and its executions

Defer the start with scheduled_at

Record provenance with source and metadata

Trigger request reference

Next steps

Bulk ingestion

Batches and executions

Batching

​How fan-out works

​Example: load a contact list

​Track the batch and its executions

​Defer the start with scheduled_at

​Record provenance with source and metadata

​Trigger request reference

​Next steps

Bulk ingestion

Batches and executions

Batching

How fan-out works

Example: load a contact list

Track the batch and its executions

Defer the start with scheduled_at

Record provenance with source and metadata

Trigger request reference

Next steps