---
title: "List held executions"
method: GET
path: "/executions/holds"
tags: ["Held Executions"]
---

# List held executions

`GET /executions/holds`

## Request

- Base URL: `/` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/executions/holds`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `/authorize`, token URL `/oauth/token`)

List the held executions the caller may see, newest first.

``org:admin`` sees every one; a user sees those filed by agents they own;
an agent sees its own. Filter by ``state`` (e.g. ``pending``) or ``agent_id``.

## Query parameters

- `state` 'pending' | 'approved' | 'denied' | 'expired' | 'withdrawn': Lifecycle of an execution approval; every state but ``pending`` is terminal.
- `agent_id` string, nullable: Only return held executions filed by this agent.
- `cursor` string, nullable: Opaque cursor from a previous page's `next_cursor`; omit for the first page.
- `limit` integer: Maximum number of held executions to return (1-100, default 25).

## Response `200`

Successful Response

- HeldExecutionListResponse: A page of held executions.
  - `data` HeldExecutionResponse[], required: The page of held executions.
    - `_links` HeldExecutionLinksResponse, required: HAL-style links for a held execution.
      - `execution` string, nullable: The execution record, once the approved call has run.
      - `result` string, nullable: The call's result: the upstream response, or why it never ran. Present once the call has finished.
      - `self` string, required: This held execution.
      - `withdraw` string, nullable: Withdraw the held call. Present while it is pending.
    - `agent_id` string, required: The agent whose call was held.
    - `api_name` string, required: Name of the API called.
    - `api_vendor` string, required: Vendor of the API called.
    - `api_version` string, required: Version of the API called.
    - `created_at` string, date-time, required: When the call was held.
    - `credential_id` string, required: The credential selected when the call was held.
    - `decided_at` string, date-time, nullable: When it left `pending`.
    - `decided_by` string, nullable: Reviewer who decided it.
    - `decision_reason` string, nullable: Reviewer's reason.
    - `execution_id` string, nullable: Execution record written once the approved call ran.
    - `execution_status` 'held' | 'queued' | 'running' | 'completed' | 'failed' | 'cancelled', nullable: Where the held call stands: `held` until decided, then `queued`, `running`, and `completed`, `failed` or `cancelled`.
    - `expires_at` string, date-time, required: When a pending held execution expires undecided.
    - `id` string, required: Held execution id (`held_…`).
    - `matched_rule_id` string, nullable: The require-approval permission rule that held the call.
    - `method` string, required: HTTP method of the held call.
    - `operation_id` string, nullable: Resolved OpenAPI operation id.
    - `path` string, required: Upstream path of the held call.
    - `review_url` string, required: Review page a signed-in reviewer opens to approve or deny the call. Carries no credential.
    - `state` 'pending' | 'approved' | 'denied' | 'expired' | 'withdrawn', required: Lifecycle of an execution approval; every state but ``pending`` is terminal.
    - `trace_id` string, nullable: Trace id of the held call.
    - `updated_at` string, date-time, nullable: Last change.
  - `has_more` boolean, required: Whether more results exist after this page.
  - `next_cursor` string, nullable: Cursor for the next page; null when there are no more results.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `422`: Unprocessable Entity
- `500`: Internal Server Error
- `503`: Service Unavailable

## Changes

> 175 revisions in range; 2 not diffed.

- **2026-10-16** `b51ab3eec2ce`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/jentic/apis/jentic-control-plane-api/changes/executions/holds/get.md)

---

[API](https://skmtc.dev/jentic/apis/jentic-control-plane-api.md) · [All operations](https://skmtc.dev/jentic/apis/jentic-control-plane-api/llms.txt) · [OpenAPI document](https://skmtc.dev/jentic/apis/jentic-control-plane-api/revisions/830c559b7a76?raw)