Concepts

Executions

The lifecycle of a run — every status, what terminal means, how to poll, cancel and re-evaluate, and where the report PDFs live.

An execution is one run of a cascade for one applicant. POST /workflows/{id}/trigger creates it and returns 202 Accepted immediately; the work happens in the background. Everything you need afterwards — status, decision, per-step outputs, PDFs — hangs off GET /executions/{id}.

What are the statuses?

Status	Meaning	Terminal?
`queued`	Created as a batch row, not yet dispatched	no
`pending`	Accepted, waiting for a worker	no
`running`	Nodes are executing	no
`waiting`	Paused on a `Wait` node or an adverse-action waiting period	no
`awaiting_review`	Paused at human review — someone must decide	no
`completed`	Every node ran cleanly	yes
`failed`	A node raised; `failed_steps` says which	yes
`cancelled`	Stopped by `POST /executions/{id}/cancel` or a batch cancel	yes
`skipped`	A batch row that was never run (cap or cancel)	yes

Poll until the status is terminal or awaiting_review. The review sub-state lives in review_status: none, in_review, approved, denied.

JSON

{
  "data": {
    "id": 1842,
    "object": "execution",
    "workflow_id": 27,
    "status": "completed",
    "execution_key": "api_client:12:rv-app-20491",
    "external_reference": "rv-app-20491",
    "needs_human_review": false,
    "review_status": "none",
    "started_at": "2026-05-08T18:41:02Z",
    "completed_at": "2026-05-08T18:41:05Z",
    "input_context": { "applicant": { "first_name": "Jordan" }, "execution_mode": "test" }
  },
  "meta": { "request_id": "7d4c2f48-…" }
}

How do I read the decision?

GET /executions/{id} returns the detail view: identity, status, input_context (the payload you sent plus resolved fields). With the executions:read:full scope it also returns:

step_outputs — a map of node id → that node's output: the report fields a product node returned (creditScore.fico9, searchSummary.recordsFound, …), which branch an IfElse took and why, what an action did.
failed_steps — the nodes that errored, with the error class.

step_outputs routinely contains SSNs, dates of birth, addresses and raw vendor responses. Request executions:read:full only for integrations that handle per-step PII appropriately.

How do I poll well?

Poll GET /executions/{id} every 1–2 seconds; most test runs finish in a few seconds, live runs in seconds to a minute depending on the products.
Stop on a terminal status or awaiting_review.
Prefer webhooks in production: execution.completed and execution.failed arrive signed within seconds of the transition. See Webhooks.
Respect Retry-After on 429.

How do I list executions?

GET /executions is scoped to the calling API client and supports filter[workflow_id], filter[status] (CSV, e.g. running,waiting), filter[needs_human_review], filter[review_status] (CSV), filter[batch_execution_id], filter[execution_key] and filter[external_reference]. An unknown status value returns 422 validation_failed. Pagination is described in Pagination and filtering.

Can I cancel a run?

POST /executions/{id}/cancel stops a pending, running or waiting execution and answers 202. A running execution finishes its in-flight node and stops before dispatching the next; nothing is rolled back. Cancelling a terminal execution returns 409 execution_not_cancellable. Cancelled runs do not emit execution.failed.

Can I run it again?

POST /executions/{id}/re_evaluations creates a new execution that replays the source's input_context against the definition the source ran with — not the cascade's current definition — so you can reproduce a decision after editing the cascade. It needs an Idempotency-Key (scoped to the source execution), an active cascade (409 workflow_inactive otherwise), and production access for live sources. Returns 202 with the new execution.

Where are the PDFs?

GET /executions/{id}/report_artifacts lists the credit-report PDFs generated for the run (id, filename, content type, byte size); GET …/report_artifacts/{artifact_id} downloads one.
GET /executions/{id}/notice_artifacts and …/{artifact_id} do the same for adverse-action notices.

Listing needs executions:read; downloading needs executions:read:full. Artifact ids are scoped to their execution — an id from another run returns 404.

POST /workflows/{id}/trigger and GET /executions/{id}
Idempotency — why the key is required and what it protects
Human review — what awaiting_review means for your integration
Batches — running many applicants at once