Sign in
Background Tasks

List task runs

Changed on

Lists mirrored runs for a task. Poll with status, executor, limit, and cursor filters to drive desktop queue pickup, dashboards, and API-worker Temporal status views.

get/v1/background-tasks/{slug}/runs

Request

  • Base URL: / (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /v1/background-tasks/{slug}/runs
  • Auth: HTTP bearer

Path parameters

slugstring required

Task slug.

Example:daily-summary

Background task slug, matching bg-tasks/<slug> locally.

Query parameters

status'queued' | 'running' | 'succeeded' | 'failed' | 'stopped'

Run status.

Example:queued

Optional run status filter. Use queued for desktop pickup or running/failed/succeeded for polling dashboards.

executor'desktop' | 'api'

Run executor.

Example:api

Optional execution backend filter.

limitinteger

Page size.

Example:100

Maximum runs to return, from 1 to 500. Defaults to 100.

cursorstring date-time

Pagination cursor.

Example:2026-06-04T21:00:30Z

RFC3339 cursor returned as nextCursor from a previous page.

Response

Task runs.

nextCursorstring nullable

RFC3339 cursor for the next page when more runs are available.

Example response

{
  "nextCursor": "2026-06-04T21:00:30Z",
  "runs": [
    {
      "attempt": 1,
      "completedAt": "2026-06-04T21:02:00Z",
      "createdAt": "2026-06-04T21:00:30Z",
      "errorCode": "llm_call_failed",
      "executor": "api",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "lastHeartbeatAt": "2026-06-04T21:01:30Z",
      "localRunId": "local-run-42",
      "model": "openai/gpt-4.1-mini",
      "previousRunId": "run-20260604-205000",
      "progressMessage": "Building API-native task artifact.",
      "progressPercent": 50,
      "provider": "openai",
      "requestedContext": "Run this now and focus on high-risk accounts.",
      "revision": 2,
      "runId": "run-20260604-210000",
      "slug": "daily-summary",
      "startedAt": "2026-06-04T21:01:00Z",
      "status": "succeeded",
      "subUseCase": "daily-summary",
      "summary": "No high-priority account changes.",
      "temporalClosedAt": "2026-06-04T21:02:00Z",
      "temporalRunId": "00000000-0000-0000-0000-000000000001",
      "temporalStartedAt": "2026-06-04T21:01:00Z",
      "temporalStatus": "Running",
      "temporalWorkflowId": "background-task/user/daily-summary/api-trigger-123",
      "trigger": "manual",
      "updatedAt": "2026-06-04T21:02:05Z",
      "useCase": "background-task"
    }
  ]
}

Changes