Batches

A batch runs one cascade against many applicants. You submit the rows once; Cascades pre-creates a child execution per row in queued state and works through them in the background. Track progress on the batch, drill into rows with the child-execution list, and export everything when it is done.

How do I create a batch?

POST /workflows/{id}/batches with a rows array — up to 500 rows per request — and an Idempotency-Key. Each row carries its own external_reference and applicant:

{
  "rows": [
    { "external_reference": "row-1", "applicant": { "first_name": "Ava", "last_name": "Stone" } },
    { "external_reference": "row-2", "applicant": { "first_name": "Ben", "last_name": "Park" } }
  ],
  "execution_mode": "test",
  "external_reference": "rentvine-batch-001"
}

The response is 202 Accepted with the batch. More than 500 rows is 422 validation_failed (rows: max 500 rows per batch). The idempotency key is compared against a hash of the rows: the same key with the same rows returns the original batch, the same key with different rows returns 409 idempotency_conflict.

Batches need an active cascade, even in test mode (see the next section). execution_mode: live needs production access (403 live_mode_forbidden). Needs executions:write.

Why does my batch return 409 workflow_inactive?

The cascade is a draft (active: false). A draft refuses every batch create with 409 workflow_inactive, in test mode too, before the rows are checked. A single trigger is different: POST /workflows/{id}/trigger with execution_mode: test runs on a draft and answers 202.

A sandbox account (not yet approved for production) cannot activate a cascade, so its cascades stay drafts and every batch create returns this 409. To run a batch:

1. Get the account approved for production through the activation form at /activate.
2. Activate the cascade: turn on its Status toggle on the Cascades list in the app, or PATCH /workflows/{id} with active: true from a key made at /api-keys. Docs keys cannot activate a cascade (403 activation_forbidden).
3. Create the batch. Test mode still works on an active cascade, so you can try it before you run live.

Until then, run single test-mode triggers on the draft to check the cascade one applicant at a time.

What are the batch statuses?

total_count, completed_count and failed_count on the batch give you a progress bar without listing rows.

How do I follow the rows?

GET /batches/{id}/executions lists child executions in row_index order with each row's status, retry_count, external_reference, needs_human_review and review_status. Filter with filter[status]=failed,skipped. Each child is a normal execution: GET /executions/{id} returns its detail and step_outputs, and it emits its own execution.completed / execution.failed webhook with batch_execution_id set — so integrations that process batches as a whole can ignore per-row events and watch the batch instead.

Cancel, resume, retry

• POST /batches/{id}/cancel halts dispatch and marks queued and in-flight rows cancelled. Only pending, running and interrupted batches can be cancelled (409 batch_not_cancellable).
• POST /batches/{id}/resume re-queues the remaining rows of an interrupted batch (409 batch_not_resumable otherwise). The cascade must still be active and live batches still need production access.
• POST /batches/{id}/retry_failed re-queues every failed row under the per-row retry cap and every skipped row, clearing their stale terminal state (409 batch_not_retryable when there is nothing to retry).

All three answer 202 with the batch. Resume and retry also answer 409 workflow_inactive when the cascade was set back to a draft after the batch was created.

How do I export results?

Add ?include=all to the CSV or ZIP to include re-evaluation revisions rather than only the latest state per applicant. All three are gated behind executions:read:full because the contents are raw applicant data.

Related

• Executions — the per-row lifecycle
• Idempotency
• POST /workflows/{id}/batches