Create task run

Overview

A task run is one execution of a task. Start a run on demand, poll its status and transcript while it works, and ask it to stop. Runs keep going if your connection drops.

Tool approval policy

Task runs follow the agent version's approvalInTasks policy. Nobody is there to approve a tool call during a run, so calls that need manual approval, or that automatic review escalates to a person, are denied. The agent is told which actions were blocked and keeps going with what it is allowed to do. If a run ends up waiting for a person anyway, it fails. See Tool approvals.

Endpoints

List task runsGET/v1/tasks/:taskId/runs

List a task's runs.

Lists a task's runs, newest first, one page at a time. Pass nextCursor as cursor to get the next page.

Request

Requires bearer authentication.

Returns 200 OK as application/json. A page of task runs.

Response schema: TaskRunList.

{
  "data": [
    {
      "id": "tr_9Jd4Ks7NbV2xQm6P",
      "taskId": "tk_6Wq3Hn8ZpL2vRt5C",
      "tenantId": "ten_8Hq2Zr5WcY1bJt6D",
      "agentId": "ag_4kP9sT2vXq7LmN3a",
      "agentVersion": 3,
      "sessionId": "ss_5Ty8Lr2GhW4nZc7F",
      "turnId": "turn_3Xp6Mv9QdB1sKe4H",
      "status": "succeeded",
      "error": null,
      "userId": "",
      "metadata": {
        "team": "support"
      },
      "startedAt": "2026-07-10T10:00:01.000Z",
      "finishedAt": "2026-07-10T10:03:00.000Z",
      "cancelRequestedAt": null,
      "canceledAt": null,
      "createdAt": "2026-07-10T10:00:00.000Z",
      "updatedAt": "2026-07-10T10:03:00.000Z"
    }
  ],
  "nextCursor": null
}

Errors

See REST errors for the error envelope and shared codes.

cURL

curl "$BLAZING_AGENTS_BASE_URL/v1/tasks/tk_1234567890ABCDEF/runs" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY"

Create task runPOST/v1/tasks/:taskId/runs

Start a task run.

Queues a run of the task now, whether or not it has a schedule. The run starts as queued; poll it to follow its progress. A task runs one run at a time, so this returns 409 while another run is queued or running. Send an idempotencyKey to make retries safe: repeating the request with the same key returns the same run. Send {} when you do not need a key.

Request

Requires bearer authentication and a JSON body.

Returns 202 Accepted as application/json. The ID of the queued run.

Response schema: CreatedTaskRun.

{
  "runId": "tr_9Jd4Ks7NbV2xQm6P"
}

Errors

See REST errors for the error envelope and shared codes.

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-support-summary-2026-07-10"}'

Get task runGET/v1/tasks/:taskId/runs/:runId

Get a task run.

Returns a task run's current state. status moves from queued to running and ends as succeeded, failed, canceled, or blocked. blocked means the run was not allowed to start, for example because a quota was reached or usage credit ran out; error says why. error also describes a failed run. sessionId and turnId stay null until the run starts its session, and a run that fails before starting, such as one whose agent version has no provider and model, never gets them. Every final status sets finishedAt and lets the task start another run.

Request

Requires bearer authentication.

Returns 200 OK as application/json. The task run.

Response schema: TaskRun.

{
  "id": "tr_9Jd4Ks7NbV2xQm6P",
  "taskId": "tk_6Wq3Hn8ZpL2vRt5C",
  "tenantId": "ten_8Hq2Zr5WcY1bJt6D",
  "agentId": "ag_4kP9sT2vXq7LmN3a",
  "agentVersion": 3,
  "sessionId": "ss_5Ty8Lr2GhW4nZc7F",
  "turnId": "turn_3Xp6Mv9QdB1sKe4H",
  "status": "succeeded",
  "error": null,
  "userId": "",
  "metadata": {
    "team": "support"
  },
  "startedAt": "2026-07-10T10:00:01.000Z",
  "finishedAt": "2026-07-10T10:03:00.000Z",
  "cancelRequestedAt": null,
  "canceledAt": null,
  "createdAt": "2026-07-10T10:00:00.000Z",
  "updatedAt": "2026-07-10T10:03:00.000Z"
}

Errors

See REST errors for the error envelope and shared codes.

cURL

curl "$BLAZING_AGENTS_BASE_URL/v1/tasks/tk_1234567890ABCDEF/runs/tr_1234567890ABCDEF" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY"

List task run messagesGET/v1/tasks/:taskId/runs/:runId/messages

List a task run's messages.

Returns a task run's transcript with the run's status, error, and finishedAt, so one request tells you both what the agent said and whether the run is done. Pages come newest first, with messages in chronological order inside each page, the same as session messages. To follow a run as it works, save latestCursor and pass it as after to get only newer messages. Send cursor or after, not both. The page is empty until the run starts its session; while the run is still going, an empty page does not mean it is done.

Request

Requires bearer authentication.

Returns 200 OK as application/json. A page of messages with the run's state.

Response schema: TaskRunMessageList.

{
  "data": [
    {
      "id": "msg_7Rk2Wq9TdN4vLb3X",
      "role": "assistant",
      "parts": [
        {
          "type": "text",
          "text": "Yesterday had 14 open cases. Two are overdue: a refund request and a login issue."
        }
      ]
    }
  ],
  "nextCursor": null,
  "latestCursor": "eyJzZXEiOjEyfQ",
  "status": "succeeded",
  "error": null,
  "finishedAt": "2026-07-10T10:03:00.000Z"
}

Errors

See REST errors for the error envelope and shared codes.

cURL

curl "$BLAZING_AGENTS_BASE_URL/v1/tasks/tk_1234567890ABCDEF/runs/tr_1234567890ABCDEF/messages" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY"

Cancel task runPOST/v1/tasks/:taskId/runs/:runId/cancel

Cancel a task run.

Asks a queued or running task run to stop. A queued run ends before it starts; a running run stops shortly after, not immediately. Poll the run for its canceled status. You get 204 whenever the task exists, even if the run is missing or has already finished, so the response never reveals which runs exist.

Request

Requires bearer authentication.

Returns 204 No Content. Cancellation was requested.

Errors

See REST errors for the error envelope and shared codes.

cURL

curl --request POST "$BLAZING_AGENTS_BASE_URL/v1/tasks/tk_1234567890ABCDEF/runs/tr_1234567890ABCDEF/cancel" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY"

Next

• Tasks and schedules to plan background work.
• Pagination and filtering to poll a run's transcript.