List a task's runs
Runs by hand and on the schedule, with skipped and missed scheduled times (kept 30 days).
GET
/v1/tasks/{id}/runsRequest
| Method and path | GET/v1/tasks/{id}/runs |
|---|---|
| Base URL | https://api.boxline.dev |
| Authentication | Your API key in the x-api-key header (or Authorization: Bearer). The examples read it from BOXLINE_API_KEY. |
Path parameters
| Name | Type | Default | Allowed values | Description |
|---|---|---|---|---|
idrequired | string | – | – |
Query parameters
| Name | Type | Default | Allowed values | Description |
|---|---|---|---|---|
limit | integer | 20 | – | From 1 to 100. |
after | string | – | – | The next value of the previous page (same filters and sort). Opaque; do not build it yourself. |
status | string | – | – | One or more statuses, comma-separated. queued, running, paused, completed, failed, canceled, skipped, missed |
curl "https://api.boxline.dev/v1/tasks/$TASK_ID/runs?status=failed,skipped,missed" \ -H "x-api-key: $BOXLINE_API_KEY"import { Boxline } from "@boxline/sdk";const bx = new Boxline(); // reads BOXLINE_API_KEY and BOXLINE_API_URLfor await (const r of bx.tasks.runs("TASK_ID", { status: ["failed", "skipped", "missed"] })) { console.log(r.createdAt, r.status, r.reason ?? r.errorCode, r.scheduledFor);}from boxline import Boxlinebx = Boxline() # reads BOXLINE_API_KEY and BOXLINE_API_URLfor r in bx.tasks.runs("TASK_ID", status=["failed", "skipped", "missed"]): print(r["createdAt"], r["status"], r["reason"] or r["errorCode"], r["scheduledFor"])Responses
200 OK
A page of runs, newest first.
Fields
| Name | Type | Default | Allowed values | Description |
|---|---|---|---|---|
data | object[] | – | – | |
data[].id | string | – | – | |
data[].taskId | string | – | – | |
data[].runId | string | null | – | – | The agent run; null for skipped and missed times and for a scheduled run that could not start. |
data[].sessionId | string | null | – | – | |
data[].status | string | – | queued, running, paused, completed, failed, canceled, skipped, missed | queued: a scheduled run waiting for its turn to start. |
data[].scheduled | boolean | – | – | |
data[].scheduledFor | string | null | – | – | Format: date-time. |
data[].reason | string | null | – | previous_run_running, plan_limit, not_running, null | Why a scheduled time did not run. |
data[].missedCount | integer | null | – | – | missed: how many scheduled times it stands for (counted up to 1,000). |
data[].variables | object | – | – | The non-secret values it ran with. |
data[].secretVariables | string[] | – | – | The names of the secret variables (never their values). |
data[].structured | boolean | – | – | The result is JSON (the task has an output schema). |
data[].result | any | – | – | JSON with an output schema |
data[].resultText | string | null | – | – | |
data[].error | string | null | – | – | |
data[].errorCode | string | null | – | – | |
data[].usage | object | – | – | |
data[].usage.inputTokens | integer | – | – | |
data[].usage.outputTokens | integer | – | – | |
data[].usage.costUsd | number | null | – | – | |
data[].durationMs | integer | null | – | – | |
data[].createdAt | string | – | – | Format: date-time. |
data[].finishedAt | string | null | – | – | Format: date-time. |
next | string | null | – | – | Pass it back as after for the next page; null on the last page. |
{ "data": [ { "id": "trun_Q2x9L0aPz7NmK3Jb", "taskId": "…", "runId": "…", "sessionId": "…", "status": "queued", "scheduled": false, "scheduledFor": "2026-09-29T10:00:00.000Z", "reason": "previous_run_running", "missedCount": 0, "variables": {}, "secretVariables": [ "…" ], "structured": false, "result": null, "resultText": "…", "error": "…", "errorCode": "output_invalid", "usage": { "inputTokens": 0, "outputTokens": 0, "costUsd": 0 }, "durationMs": 0, "createdAt": "2026-09-29T10:00:00.000Z", "finishedAt": "2026-09-29T10:00:00.000Z" } ], "next": "eyJvIjoiY3JlYXRlZF9kZXNjIiwidCI6IjIwMjYtMDktMjlUMTA6MDA6MDAuMTIzNDU2WiIsImkiOiI2YzFmIn0"}Errors
Errors have a matching HTTP status and the same body. code is stable, so check it in your code; message is for people. See Errors and request ids.
| Status | Codes | When |
|---|---|---|
| 400 Bad Request | invalid_request, invalid_json, invalid_cursor, invalid_idempotency_key, invalid_extension, variables_with_extensions, terms_not_accepted, invalid_reset_token, invalid_confirmation_code, wrong_password, no_password, invalid_next, invalid_oauth_token | The request is not valid. |
| 401 Unauthorized | unauthorized | Missing or invalid API key. |
| 404 Not Found | not_found, invite_not_found, provider_unavailable | No such thing in this project (or organization), or no such route. |
{ "error": { "code": "not_found", "message": "session not found", "requestId": "req_4fJx0aQm2Lk9Pz7N" }}Learn more
These docs describe a beta API. Endpoints, fields and SDK methods may change before general availability; breaking changes will be listed in the changelog.