---
title: Executions
description: The lifecycle of a run — every status, what terminal means, how to poll, cancel and re-evaluate, and where the report PDFs live.
canonical_url: "https://cascades.crscreditapi.com/docs/concepts/executions"
doc_version: "1.0.0"
last_updated: "2026-09-23T19:55:02Z"
source: docs/concepts/executions.md
---

# Executions

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](/docs/concepts/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](/docs/concepts/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`.

## Related

- [`POST /workflows/{id}/trigger`](/docs/api/workflows/trigger-workflow) and [`GET /executions/{id}`](/docs/api/executions/get-execution)
- [Idempotency](/docs/concepts/idempotency) — why the key is required and what it protects
- [Human review](/docs/concepts/human-review) — what `awaiting_review` means for your integration
- [Batches](/docs/concepts/batches) — running many applicants at once

## Sitemap

See the full [sitemap](https://cascades.crscreditapi.com/sitemap.md) for all pages.