--- title: "Read a checklist run" method: GET path: "/approval/{id}/checklist" tags: ["Checklist"] --- # Read a checklist run `GET /approval/{id}/checklist` ## Request - Base URL: `https://api.nullplatform.com` - URL: `https://api.nullplatform.com/approval/{id}/checklist` - Auth: HTTP bearer Returns the checklist run for an approval request: its aggregate status, every item with its state, and a summary. ## Path parameters - `id` integer, required ## Response `200` The operation was successful. - object - `id` string: ID of the checklist run. - `approval_request_id` integer: The approval request this run belongs to. - `specification_id` string: The specification version the run was created from. - `specification_snapshot` object: The specification as it stood when the run started. Editing the specification later never changes this. - `context_snapshot` object: The request context conditions were evaluated against, captured at creation. - `aggregate_status` 'pending_items' | 'pending_aggregation' | 'pending_override' | 'resolved': Where the run is in its lifecycle. - `final_outcome` 'approve' | 'approve_with_override' | 'fail' | 'cancelled' | 'expired', nullable: How the run ended. Null while it is still open. - `outcome_reason` string, nullable: Why the run ended the way it did, when there is more to say than the outcome. - `override_metadata` object, nullable: Who approved the override and what they said, on a run that ended in `approve_with_override`. - `started_at` string, date-time: When the run was created. - `resolved_at` string, date-time, nullable: When the run reached its final outcome. Null while it is still open. - `items` object[]: Every item in the run, groups included, flattened into one list with its definition and its current state. A group lists its children by id in `children`; an item inside a group points back to it with `group_id`. - `id` string: The item's id in the specification. - `type` 'condition' | 'manual' | 'external' | 'group': How the item gets resolved. - `behavior` 'gate' | 'informational' | 'override': What the item's result does to the action. - `title` string: The label a person reads in the list. - `description` string, nullable: The guidance shown with the item. Items only. - `severity` 'info' | 'minor' | 'major' | 'critical': How the item is presented. Severity never changes the outcome. Items only. - `group_id` string, nullable: The group this item sits in. Null at the top level. Items only. - `children` string[]: The ids of the group's children. Groups only. - `status` 'pending' | 'undetermined' | 'latent' | 'in_progress' | 'validating' | 'passed' | 'failed' | 'skipped' | 'timed_out' | 'cancelled': The item's current status. The [items reference](/docs/approvals/checklist-items#item-statuses) explains each one. - `sub_status` string, nullable: Why the item reached its status, like `not_applicable` for a skipped item whose `applies_when` didn't match. - `message` string, nullable: The message that came with the item's last change. - `applicable` boolean: `false` only for an item that `applies_when` pruned out of the run. - `applies_when` object, nullable: The item's `applies_when`, as declared in the specification. Items only. - `depends_on` string[], nullable: The ids of the items this item's `applies_when` reads. Items only. - `applicability` object, nullable: The decision on an item that depends on other items, once it's taken. Null while the item is `undetermined`, and for items that don't depend on others. Items only. - `applicable` boolean: Whether the item joined the run. - `decided_at` string, date-time: When the decision was taken. - `refs` object: Each reference the decision read, with the value it saw. - `output` object, nullable: The typed output an `external` item reported in its callback. Null until it reports one. Items only. - `input_values` object, nullable: The values submitted to a `manual` item's inputs. Items only. - `resolved_by` object, nullable: Who answered a `manual` item, with their roles and when. Items only. - `user_id` integer: The user who answered. - `effective_roles` string[]: Their roles when they answered. - `at` string, date-time: When they answered. - `actionable_by_me` boolean: Whether the item is a `manual` item still `pending`, so someone can answer it. Always `false` for an `undetermined` item. Items only. - `items_summary` object: Item counts by status. Each item is counted once. - `total` integer: Items in the run. - `passed` integer: Items resolved successfully. - `failed` integer: Items resolved unsuccessfully. - `pending` integer: Items still waiting, including latent and in-progress ones. - `skipped` integer: Items that never ran. Their `sub_status` says why. - `undetermined` integer: Items waiting on the items their `applies_when` reads. Nobody can act on them yet. - `first_pending_actionable_by_me` string, nullable: The id of the first `manual` or `external` item still pending. Null when there is none. - `available_actions` string[]: What the requester can still do with the run. `ask_for_manual` is absent when the action's `on_checklist_fail` is `deny`. - `action_config` object, nullable: How the approval action is configured to treat a failed run. Null when the action can't be resolved. A run that passes always approves, so there is nothing to configure for success. - `on_checklist_fail` 'deny' | 'pending' | 'manual': What happens to the request when its checklist run resolves as `fail`. Only read in checklist mode; policy-mode actions use `on_policy_fail` instead. - `deny`: the request is denied outright. Reviewers are never notified and manual review can't be requested. - `pending`: the request stays open. The requester fixes the cause and requests again, cancels, or asks for a manual review, which is when reviewers are notified. - `manual`: the request goes to manual review right away and reviewers are notified. > **Note:** If omitted, this value defaults to **pending**. An invalid value returns `400 INVALID_CHECKLIST_FAIL_PATH`. - `execution` object: What approving the request does with the action behind it. Before the run resolves it says what will happen; afterwards, next to the request's `execution_status`, what did. Always present. - `trigger` 'explicit' | 'automatic_approval' | 'any_approval': The `execution_trigger` the run read from its specification snapshot. `explicit` when the specification doesn't set one. - `automatic_run` boolean: Whether no person or external system took part in the run, the way `automatic_approval` counts it. - `on_approval` 'execute' | 'wait': `execute` when approving starts the action on its own, `wait` when the action waits for an explicit execute. ## Other responses - `4XX`: The request couldn't be processed. For example, a parameter is invalid, the resource doesn't exist, or you don't have permission. The body is a problem details object (RFC 9457). - `5XX`: Something went wrong on nullplatform's side. The body is a problem details object (RFC 9457). ## Changes - **2026-10-22** `464556c2a716`: 21 info - added the optional property `items/items/actionable_by_me` to the response with the `200` status - added the optional property `items/items/applicability` to the response with the `200` status - added the optional property `items/items/applicable` to the response with the `200` status - added the optional property `items/items/applies_when` to the response with the `200` status - …17 more - **2026-10-15** `728d4df70ca1`: 6 breaking, 15 info - the response property `message` became optional for the status `4XX` - the response property `message` became optional for the status `5XX` - removed the required property `error` from the response with the `4XX` status - removed the required property `error` from the response with the `5XX` status - …17 more - **2026-10-02** `ac7c8dabaaa7`: 1 info - added the optional property `execution` to the response with the `200` status - **2026-09-15** `4ff26f94f63d`: 5 warning - removed the optional property `action_config/checklist_fail_mode` from the response with the `200` status - removed the optional property `action_config/on_checklist_success` from the response with the `200` status - added the new `deny` enum value to the `action_config/on_checklist_fail` response property for the response status `200` - added the new `manual` enum value to the `action_config/on_checklist_fail` response property for the response status `200` - …1 more - …earlier changes not shown [Operation history](https://skmtc.dev/nullplatform/apis/nullplatform-api/changes/approval/:id/checklist/get.md) --- [API](https://skmtc.dev/nullplatform/apis/nullplatform-api.md) - [All operations](https://skmtc.dev/nullplatform/apis/nullplatform-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nullplatform/apis/nullplatform-api/revisions/d3f66bc633d4?raw)