Skip to content
API Reference

Track Runs and Retrieve Results

Version: unreleased · Docs: 3c6ab9f2Download Markdown

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.

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.

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 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.

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.

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.

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.