Task runs

Overview

Task runs are durable executions of Task definitions. Use these endpoints to enqueue on-demand work, poll its lifecycle and transcript, or request cooperative cancellation.

Endpoints

POST /v1/tasks/:taskId/runs

Enqueues an immediate run for an on-demand or scheduled Task. At most one run of a Task can be active. An optional idempotency key deterministically identifies the run; replaying it returns the existing run ID.

Request

Requires bearer authentication, JSON, and a tk_… taskId path parameter. The credential selects the Tenant ownership boundary; reads and mutations are restricted to resources owned by that Tenant.

Send {} when no key is needed. There are no query parameters.

Response

Returns 202 Accepted.

Response schema: createTaskRunResponseSchema.

{ "runId": "tr_1234567890ABCDEF" }

The run begins as queued and the API immediately enqueues its deterministic DBOS workflow. Repeating an idempotent request attaches to the same logical run. A low-frequency repair path recovers the cross-database case where the product row committed before DBOS enqueue succeeded. Poll Get a Task run.

Errors

400 invalid_request for invalid input or when another run is active. 404 not_found applies to a missing Task; 404 AGENT_VERSION_NOT_FOUND rejects a missing pin, and 409 AGENT_DISABLED rejects a disabled Agent. See REST errors.

cURL

curl --request POST \
  "$BLAZING_AGENTS_BASE_URL/v1/tasks/tk_1234567890ABCDEF/runs" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"idempotencyKey":"daily-summary-2026-07-10"}'

SDK and related guides

SDK: create-run. See Tasks and schedules and Run a background Task.

GET /v1/tasks/:taskId/runs

Returns the Task's runs newest first. An unknown, foreign, or deleted Task returns 404 not_found.

Request

Requires bearer authentication and a tk_… taskId. The credential selects the Tenant ownership boundary; reads and mutations are restricted to resources owned by that Tenant.

Response

Returns 200 OK with { data, nextCursor }. Each item is a complete Task run object.

Response schema: taskRunsListResponseSchema.

{
  "data": [
    {
      "id": "tr_1234567890ABCDEF",
      "taskId": "tk_1234567890ABCDEF",
      "tenantId": "ten_1234567890ABCDEF",
      "agentId": "ag_1234567890ABCDEF",
      "agentVersion": 3,
      "sessionId": "ss_1234567890ABCDEF",
      "status": "succeeded"