List a routine's runs

Lists runs of the routine, newest first. Run history is kept for 30 days.

GET /v1/routines/{routine}/runs
Lists runs of the routine, newest first. Run history is kept for 30 days.

Authentication

Bearer Token (b3os_sk_ API key or b3os_pat_ token) API Key (cookie: __Host-b3os_session)

Path Parameters

routine string required path
A routine ID (`rtn_…`) or name. Names are unique per project; `runs`, `hooks`, `validate` and `import` are reserved and cannot be routine names.
Example: "nightly-digest"

Query Parameters

limit integer optional query
Page size, from 1 to 100.
cursor string optional query
Opaque cursor from the previous page's `next_cursor`. Omit it for the first page.
status string optional query
Only runs with this status.

Responses

200 A page of runs (without step details).
application/json
object string REQUIRED
Enum: list
data object[] REQUIRED
Array of:
id string REQUIRED
object string REQUIRED
Enum: routine_run
status string REQUIRED
`queued` → `running` → one of the terminal statuses `succeeded`, `failed` or `canceled`. A job never leaves a terminal status.
Enum: queued, running, succeeded, failed, canceled
created_at string (date-time) REQUIRED
updated_at string (date-time) REQUIRED
started_at string (date-time) | null
finished_at string (date-time) | null
progress object
How far a job has got, in the job's own unit (pages, items, steps).
completed integer REQUIRED
Units finished, successfully or not.
failed integer
Units that failed (included in `completed`).
total integer | null
Units expected, when known.
unit string REQUIRED
What is counted, such as `pages`, `items` or `steps`.
result unknown
The job's output. Present once `status` is `succeeded`; the product's job type defines its shape.
error object
An RFC 9457 problem. `code` is stable and listed in the errors catalog; `type` links to its entry. `detail` is human-readable and may change. Extension members appear only for the codes that document them; ignore members you do not recognize.
type string (uri) REQUIRED
`https://docs.beta.b3os.org/errors#<code>`.
title string REQUIRED
Short summary of the problem type.
status integer REQUIRED
The HTTP status code, repeated for convenience.
code string REQUIRED
Stable machine-readable error code from the errors catalog.
detail string REQUIRED
Explanation of this occurrence. Never contains secrets.
instance string
The request ID (`req_…`) of the request that failed. Include it when you contact support.
errors object[]
Validation problems, one per field (`invalid_request` and the other codes that list `errors`).
Array of:
pointer string REQUIRED
Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/<name>`, `#path/<name>` or `#header/<name>` for parameters.
detail string REQUIRED
What is wrong there.
reason string
Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …).
required_scope string
The scope that was missing (`forbidden` with `reason: scope`).
retry_after_s integer
Same value as the `Retry-After` header, for clients that only read the body.
limit object
The limit an error refers to. IDs and current values are listed by `GET /v1/limits`.
id string REQUIRED
Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`.
limit number REQUIRED
The limit's value.
unit string REQUIRED
What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`.
window_s integer
Window length in seconds for rate limits and quotas.
current number
Current usage against the limit, when known.
current_status string
The object's current status, for state conflicts such as `sandbox_not_running`.
upstream_status integer
The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`).
step string
The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render).
pack_error object
The error a pack's error mapping chose (`upstream_error` from pack actions).
code string REQUIRED
message string REQUIRED
retryable boolean REQUIRED
timing object
Server-side phase durations in milliseconds with microsecond resolution: the same phases as the `Server-Timing` header, keyed `<phase>_ms`. `total_ms` is always present. Phase names are product-specific and documented per operation. Example values in this reference are illustrative, not measurements.
total_ms number REQUIRED
expires_at string (date-time) | null
When the job's results are deleted (retention); `null` while the job is not terminal.
metadata object
Up to 16 string key-value pairs you attach to an object for your own use. Keys are 1 to 40 characters of `A-Z a-z 0-9 _ . : -`; values are at most 500 characters. B3OS never interprets them.
webhook object
Where to deliver this job's events. Deliveries are `POST`s of a `WebhookEvent` signed with `B3OS-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">` using the endpoint's secret (`POST /v1/webhooks/secret`). Failed deliveries are retried with backoff for 24 hours. Delivery goes through the egress guard, so private and loopback addresses are refused.
url string (uri) REQUIRED
An `https://` URL.
events string[]
Event types to deliver. Defaults to the terminal events (`job.succeeded`, `job.failed`, `job.canceled`); `["*"]` delivers every event.
Array of: string
routine_id string REQUIRED
version_id string REQUIRED
version_number integer REQUIRED
durability string REQUIRED
Enum: ephemeral, standard, strict
trigger object REQUIRED
How the run started (the `trigger` context of its expressions).
type string REQUIRED
Enum: api, cron, interval, webhook, action, routine
id string
The trigger ID (cron, interval, webhook, action).
occurrence_id string
Cron and interval occurrence, used to deduplicate fires.
scheduled_at string (date-time)
hook_id string
delivery_id string
subscription_id string
The trigger subscription that delivered the event (action triggers).
event_id string
The pack trigger event's ID (action triggers).
parent_run_id string
For sub-routine runs.
parent_step_id string
input object REQUIRED
steps object[] REQUIRED
Top-level steps in definition order.
Array of:
id string REQUIRED
The step ID from the definition.
uses string
item_index integer
Position in the map's list, for steps inside a map body.
status string REQUIRED
Enum: pending, running, waiting, retrying, succeeded, failed, skipped, canceled
attempt integer REQUIRED
started_at string (date-time)
finished_at string (date-time)
duration_ms number
outputs unknown
The step's outputs, once it succeeded.
error object
An RFC 9457 problem. `code` is stable and listed in the errors catalog; `type` links to its entry. `detail` is human-readable and may change. Extension members appear only for the codes that document them; ignore members you do not recognize.
type string (uri) REQUIRED
`https://docs.beta.b3os.org/errors#<code>`.
title string REQUIRED
Short summary of the problem type.
status integer REQUIRED
The HTTP status code, repeated for convenience.
code string REQUIRED
Stable machine-readable error code from the errors catalog.
detail string REQUIRED
Explanation of this occurrence. Never contains secrets.
instance string
The request ID (`req_…`) of the request that failed. Include it when you contact support.
errors object[]
Validation problems, one per field (`invalid_request` and the other codes that list `errors`).
Array of: ...
reason string
Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …).
required_scope string
The scope that was missing (`forbidden` with `reason: scope`).
retry_after_s integer
Same value as the `Retry-After` header, for clients that only read the body.
limit object
The limit an error refers to. IDs and current values are listed by `GET /v1/limits`.
id string REQUIRED
Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`.
limit number REQUIRED
The limit's value.
unit string REQUIRED
What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`.
window_s integer
Window length in seconds for rate limits and quotas.
current number
Current usage against the limit, when known.
current_status string
The object's current status, for state conflicts such as `sandbox_not_running`.
upstream_status integer
The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`).
step string
The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render).
pack_error object
The error a pack's error mapping chose (`upstream_error` from pack actions).
code string REQUIRED
message string REQUIRED
retryable boolean REQUIRED
map object
Item counts for a map step.
total integer
succeeded integer
failed integer
running integer
waiting_for object
What a waiting step waits for.
signal string
until string (date-time)
next_cursor string | null REQUIRED
400 The request failed validation (`invalid_request`, `invalid_url`).
401 Missing, malformed, expired or revoked credentials (`unauthorized`).
403 Authenticated but not allowed (`forbidden`, `egress_denied`).
404 No such routine in this project (`routine_not_found`).
429 A rate, concurrency or quota limit applies (`rate_limited`, `concurrency_limited`, `quota_exceeded`).
500 Something failed inside B3OS (`internal`). Retry with backoff.
503 The node or the product is not available right now (`node_unavailable`, `product_unavailable`, `capacity_unavailable`). 
curl -X GET 'https://beta-api.b3os.org/v1/routines/nightly-digest/runs' \  -H 'Authorization: Bearer YOUR_API_TOKEN'
const response = await fetch('https://beta-api.b3os.org/v1/routines/nightly-digest/runs', {  method: 'GET',  headers: {      "Authorization": "Bearer YOUR_API_TOKEN"  }});const data = await response.json();console.log(data);
import requestsheaders = {    'Authorization': 'Bearer YOUR_API_TOKEN'}response = requests.get('https://beta-api.b3os.org/v1/routines/nightly-digest/runs', headers=headers)print(response.json())
200 Response 
{  "object": "list",  "data": [    {      "id": "run_01m5t5fr06dx6azc42f4wbzf5s",      "object": "routine_run",      "status": "succeeded",      "routine_id": "rtn_01m5t6vhkw4a8fa4tb5w4ffz37",      "version_id": "ver_01m5t6ncrsssrysy1p2fbn2pgf",      "version_number": 2,      "durability": "ephemeral",      "trigger": {        "type": "cron",        "id": "nightly",        "occurrence_id": "nightly@2026-10-25T13:00:00Z",        "scheduled_at": "2026-10-25T13:00:00.000Z"      },      "input": {},      "steps": [],      "created_at": "2026-10-25T13:00:00.001Z",      "updated_at": "2026-10-25T13:00:01.340Z",      "metadata": {}    }  ],  "next_cursor": null}
Previous Get a version
Next Run a routine
Ask a question... ⌘I