List Schedule Runs

GET/v1/schedules/{schedule_id}/runs

List Runs with offset pagination (limit 1-100). Read one Run with GET /v1/schedules/{schedule_id}/runs/{run_id}; Schedule Run reads are read-only and status advances in the background. Request cancellation of a pending Run with POST /v1/schedules/{schedule_id}/runs/{run_id}/cancel (Idempotency-Key required, body {}). Cancel only reaches a Run whose Session has started: while session_id is null it returns 409 conflict, and while the Run input is still being delivered it returns 409 session_input_pending; in that state the Run may not be cancellable, so wait for it to finish. Cancelling a Run that has already finished returns 202 with the unchanged Run. Read notification deliveries with GET /v1/schedules/{schedule_id}/runs/{run_id}/notifications.

Path parameters

stringschedule_idrequired

Schedule ID (sch_ prefix).

Query parameters

Optional<integer>limit

Page size up to 100; values above 100 return 400, and 0 or non-numeric values fall back to 20.

Default: 20

Optional<integer>offset

Number of records to skip.

Default: 0

Run object

Returned by every Run operation.

stringstatusrequired

pending, succeeded, failed, or cancelled; skipped when a scheduled tick finds a pending Run (error_code concurrency_limit).

string · nullsession_idrequired

Session created for the Run; null until it exists.

Optional<string>error_code

Set when the Run failed, for example session_creation_rejected, execution_failed, or spending_limit_exceeded.

stringtrigger_sourcerequired

manual or scheduled.

curl -X GET "https://api.sandbase.ai/v1/schedules/sch_7e3b1c58-2a9d-5e4f-b6c1-8d0a2f4e6b17/runs?limit=20" \
  -H "Authorization: Bearer $SANDBASE_API_KEY"

Response200 OK

{
  "data": [
    {
      "id": "run_4a6c8e0b-1d3f-5a7c-9e1b-3d5f7a9c1e24",
      "source_type": "schedule",
      "source_id": "sch_7e3b1c58-2a9d-5e4f-b6c1-8d0a2f4e6b17",
      "source_version": 1,
      "agent_id": "agt_8c1f2b9e-3d4a-4f6b-9c2e-1a7d5e3b4c60",
      "agent_version": 3,
      "trigger_source": "scheduled",
      "status": "succeeded",
      "session_id": "ses_5b0e7c3a-91d2-5f4e-8a6b-2c9d4e1f7a83",
      "created_at": "2026-10-06T08:05:00Z",
      "updated_at": "2026-10-06T08:05:00Z",
      "scheduled_at": "2026-10-06T01:00:00Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}