# Track Runs and Retrieve Results

Keep the **id**, **thread_id** and **kind** returned when Redbelt accepts your
request. An agent input keeps its **id**; its **run_id** appears once the run
starts. A workflow's **id** is the workflow run. Direct AI requests have their own
endpoints under **/api/v1/inference/requests**.

## Read status or wait for a result

For agent or workflow execution, call
**GET /api/v1/executions/KIND/EXECUTION_ID**, where **KIND** is **agent** or
**workflow**. The response contains status and any saved output. **202** at
submission means accepted work, not a successful final answer.

| Status                                  | Next step                                              |
| --------------------------------------- | ------------------------------------------------------ |
| queued                                  | Wait for it to start; keep the accepted ID.            |
| running                                 | Read saved output, or wait for the next status.        |
| waiting_for_input, waiting_for_approval | Read and respond to the returned wait ID.              |
| completed                               | Use output and retrieve published artifacts.           |
| failed, cancelled, budget_exceeded      | Inspect error_code and partial output before retrying. |

To wait instead of polling, add **wait** (up to 30 seconds):
**GET /api/v1/executions/KIND/EXECUTION_ID?wait=30**. The request returns as soon
as the status is no longer **queued** or **running**, or with the current snapshot
when the time is up. Repeat it while the status is still **queued** or
**running**. Each response is a complete snapshot: replace saved output rather
than appending it. Closing the request leaves the execution running.

## Answer a question or approval

Call **GET /api/v1/waits/WAIT_ID** and inspect **kind**, **status**, and **prompt**.
Send **POST /api/v1/waits/WAIT_ID/respond** with a stable **idempotency_key** and
the fields required by that wait. Input questions use **answers**; an action
review uses **decision**. Use the generated [request schema](/api/reference/) and
returned prompt for the supported answer shape and choices.

Redbelt decides which approvals apply. It accepts a response only for a wait this
API key's identity is allowed to answer, so a request can't approve an action on
its own.

## Retrieve artifacts

Call **GET /api/v1/executions/KIND/EXECUTION_ID/artifacts**. The list contains
published files belonging to that run, with **id**, **title**, **size_bytes**, and
**download_path**. Request that path with your bearer key to download the bytes.
An unpublished or inaccessible artifact is excluded. The list defaults to 100
files; set **limit** (up to 500) and advance **offset** to retrieve later pages.
When listing during a run, deduplicate by artifact ID. Downloads always go through
Redbelt with your key; the list never contains direct storage links.

## Cancel explicitly

Call **POST /api/v1/executions/KIND/EXECUTION_ID/cancel**. A run can finish just
before the cancellation lands, so read the returned status. Cancelling does not
undo a message or external action that already happened.

## Handle access and delivery errors

Every read, download, wait response and cancellation uses the API key's
identity and organization. Revoked credentials stop access. An inaccessible
resource may return **404** rather than disclose its existence.

* **400:** a valid request shape selects an unavailable model or unsupported execution option.
* **401:** missing, invalid, expired or revoked credentials.
* **402:** the organization's plan or spending limit doesn't allow new work right now.
* **403:** the identity or organization cannot perform the operation.
* **404:** absent or inaccessible resource.
* **409:** conflicting input or idempotency key reused with changed parameters.
* **422:** invalid fields or unsupported options; correct the request.

After a network timeout, retrieve the accepted result or repeat the exact
submission under the same request ID. A new ID can cause duplicate external work.
