List tasks

Overview

A task is a saved prompt for an agent that runs in the background, on demand or on a schedule. Each run gets its own record and transcript, so you can check on it later. Use tasks for reports, syncs, and other work nobody waits on.

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 tasksGET`/v1/tasks`

List tasks.

Lists your tasks, most recently updated first, one page at a time. Each task includes latestRun with the status of its most recent run, or null if it has never run. Filter by agent or by end user, and pass nextCursor as cursor to get the next page.

Request

Requires bearer authentication.

Field	Type	Location	Description
`agentId`	string	query	Return only tasks for this agent.
`userId`	string	query	Return only tasks for this end user. An empty string returns tenant-level tasks.
`cursor`	string \| null	query	`nextCursor` from the previous page.
`limit`	integer	query	Tasks per page, 1 to 200. 1–200. Defaults to `50`.

Response

A page of tasks.

TaskListobjectrequired

A page of tasks.

Returns 200 OK as application/json. A page of tasks.

Response schema: TaskList.

{
  "data": [
    {
      "id": "tk_6Wq3Hn8ZpL2vRt5C",
      "tenantId": "ten_8Hq2Zr5WcY1bJt6D",
      "agentId": "ag_4kP9sT2vXq7LmN3a",
      "agentVersion": null,
      "name": "Daily support summary",
      "prompt": "Summarize yesterday's open support cases and flag any that are overdue.",
      "schedule": {
        "kind": "cron",
        "config": {
          "expression": "0 9 * * 1-5",
          "timezone": "Europe/London"
        }
      },
      "enabled": true,
      "activeRunId": null,
      "latestRunId": "tr_9Jd4Ks7NbV2xQm6P",
      "userId": "",
      "metadata": {
        "team": "support"
      },
      "deletedAt": null,
      "createdAt": "2026-07-10T10:00:00.000Z",
      "updatedAt": "2026-07-10T10:03:00.000Z",
      "latestRun": {
        "id": "tr_9Jd4Ks7NbV2xQm6P",
        "status": "succeeded",
        "finishedAt": "2026-07-10T10:03:00.000Z"
      }
    }
  ],
  "nextCursor": null
}

Errors

Status	Codes	Description
`400`	`validation_failed`, `invalid_cursor`	The request is invalid
`401`	`unauthorized`	The credential is missing or invalid
`402`	`subscription_required`	An active subscription or usage credit is required

See REST errors for the error envelope and shared codes.

cURL

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

Create taskPOST`/v1/tasks`

Create a task.

Creates a task: a saved prompt your agent runs in the background. With a schedule, the task runs by itself; without one, it runs only when you start it. Send submit: true to start a run right away, which returns 202 Accepted with the run's ID in runId; otherwise you get 201 Created and runId is null. Retrying this request creates another task, so when retries must not start duplicate runs, create the task first and start runs with POST /v1/tasks/{taskId}/runs and an idempotencyKey. The platform-managed ba assist agent cannot run tasks.

Request

Requires bearer authentication and a JSON body.

Field	Type	Location	Required	Description
`agentId`	string	body	required	ID of the agent that runs the task. It cannot change later.
`agentVersion`	integer \| null	body		Agent version to run. `null` runs whatever version is current when each run starts. 1–2147483647. Defaults to `null`.
`name`	string	body	required	Display name, 1 to 80 characters. 1–80 characters.
`prompt`	string	body	required	The prompt the agent receives on every run, 1 to 6,000 characters. 1–6000 characters.
`schedule`	object \| null	body		When the task runs by itself: `once` at a time, every `everyMs` milliseconds (at least 60,000) for `interval`, or a five-field cron expression in an IANA timezone for `cron`. `null` means the task runs only when you start it. Defaults to `null`.
`enabled`	boolean	body		Whether the schedule fires. A disabled task can still be started on demand. Defaults to `true`.
`submit`	boolean	body		Start a run as soon as the task is created. Defaults to `false`.
`userId`	string	body		Your end user's ID, used for attribution. An empty string means a tenant-level task. It cannot change after creation. Defaults to `""`.
`metadata`	object	body		Your own key-value data, returned unchanged and copied to each run. Defaults to `{}`.

Response

A page of tasks.

TaskListobjectrequired

A page of tasks.

Returns 201 Created as application/json. The created task.

Response schema: CreatedTask.

{
  "task": {
    "id": "tk_6Wq3Hn8ZpL2vRt5C",
    "tenantId": "ten_8Hq2Zr5WcY1bJt6D",
    "agentId": "ag_4kP9sT2vXq7LmN3a",
    "agentVersion": null,
    "name": "Daily support summary",
    "prompt": "Summarize yesterday's open support cases and flag any that are overdue.",
    "schedule": {
      "kind": "cron",
      "config": {
        "expression": "0 9 * * 1-5",
        "timezone": "Europe/London"
      }
    },
    "enabled": true,
    "activeRunId": null,
    "latestRunId": null,
    "userId": "",
    "metadata": {
      "team": "support"
    },
    "deletedAt": null,
    "createdAt": "2026-07-10T10:00:00.000Z",
    "updatedAt": "2026-07-10T10:00:00.000Z"
  },
  "runId": null
}

Returns 202 Accepted as application/json. The created task and the ID of its queued run.

Response schema: CreatedTask.

{
  "task": {
    "id": "tk_6Wq3Hn8ZpL2vRt5C",
    "tenantId": "ten_8Hq2Zr5WcY1bJt6D",
    "agentId": "ag_4kP9sT2vXq7LmN3a",
    "agentVersion": null,
    "name": "Daily support summary",
    "prompt": "Summarize yesterday's open support cases and flag any that are overdue.",
    "schedule": null,
    "enabled": true,
    "activeRunId": "tr_9Jd4Ks7NbV2xQm6P",
    "latestRunId": "tr_9Jd4Ks7NbV2xQm6P",
    "userId": "",
    "metadata": {
      "team": "support"
    },
    "deletedAt": null,
    "createdAt": "2026-07-10T10:00:00.000Z",
    "updatedAt": "2026-07-10T10:00:00.000Z"
  },
  "runId": "tr_9Jd4Ks7NbV2xQm6P"
}

Errors

Status	Codes	Description
`400`	`validation_failed`	The request is invalid
`401`	`unauthorized`	The credential is missing or invalid
`402`	`subscription_required`	An active subscription or usage credit is required
`404`	`not_found`, `agent_version_not_found`	The resource was not found
`409`	`agent_disabled`, `admin_agent_managed`	The request conflicts with the resource's current state
`429`	`rate_limited`	Too many requests
`503`	`service_unavailable`	The service is temporarily unavailable

See REST errors for the error envelope and shared codes.

cURL

curl --request POST "$BLAZING_AGENTS_BASE_URL/v1/tasks" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"agentId":"ag_4kP9sT2vXq7LmN3a","name":"Daily support summary","prompt":"Summarize yesterday'\''s open support cases and flag any that are overdue.","schedule":{"kind":"cron","config":{"expression":"0 9 * * 1-5","timezone":"Europe/London"}},"metadata":{"team":"support"}}'

Get taskGET`/v1/tasks/:taskId`

Get a task.

Returns a task without running it. activeRunId is the run in progress, if any, and latestRunId is the most recent run.

Request

Requires bearer authentication.

Field	Type	Location	Required	Description
`taskId`	string	path	required	ID of the task.

Response

A page of tasks.

TaskListobjectrequired

A page of tasks.

Returns 200 OK as application/json. The task.

Response schema: Task.

{
  "id": "tk_6Wq3Hn8ZpL2vRt5C",
  "tenantId": "ten_8Hq2Zr5WcY1bJt6D",
  "agentId": "ag_4kP9sT2vXq7LmN3a",
  "agentVersion": null,
  "name": "Daily support summary",
  "prompt": "Summarize yesterday's open support cases and flag any that are overdue.",
  "schedule": {
    "kind": "cron",
    "config": {
      "expression": "0 9 * * 1-5",
      "timezone": "Europe/London"
    }
  },
  "enabled": true,
  "activeRunId": null,
  "latestRunId": null,
  "userId": "",
  "metadata": {
    "team": "support"
  },
  "deletedAt": null,
  "createdAt": "2026-07-10T10:00:00.000Z",
  "updatedAt": "2026-07-10T10:00:00.000Z"
}

Errors

Status	Codes	Description
`400`	`validation_failed`	The request is invalid
`401`	`unauthorized`	The credential is missing or invalid
`402`	`subscription_required`	An active subscription or usage credit is required
`404`	`not_found`	The resource was not found

See REST errors for the error envelope and shared codes.

cURL

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

Update taskPATCH`/v1/tasks/:taskId`

Update a task.

Updates a task. Send at least one field; fields you leave out keep their values. A run already in progress keeps the settings it started with. The agent and userId cannot change: to point a task at another agent, create a new task.

Request

Requires bearer authentication and a JSON body.

Field	Type	Location	Required	Description
`taskId`	string	path	required	ID of the task.
`agentVersion`	integer \| null	body		Agent version to run. `null` runs whatever version is current when each run starts. 1–2147483647.
`name`	string	body		Display name, 1 to 80 characters. 1–80 characters.
`prompt`	string	body		The prompt the agent receives on every run, 1 to 6,000 characters. 1–6000 characters.
`schedule`	object \| null	body		When the task runs by itself: `once` at a time, every `everyMs` milliseconds (at least 60,000) for `interval`, or a five-field cron expression in an IANA timezone for `cron`. `null` means the task runs only when you start it.
`enabled`	boolean	body		Whether the schedule fires. A disabled task can still be started on demand.
`metadata`	object	body		Your own key-value data. Replaces the current metadata.

Response

A page of tasks.

TaskListobjectrequired

A page of tasks.

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

Response schema: Task.

{
  "id": "tk_6Wq3Hn8ZpL2vRt5C",
  "tenantId": "ten_8Hq2Zr5WcY1bJt6D",
  "agentId": "ag_4kP9sT2vXq7LmN3a",
  "agentVersion": null,
  "name": "Daily support summary",
  "prompt": "Summarize yesterday's open support cases and flag any that are overdue.",
  "schedule": {
    "kind": "cron",
    "config": {
      "expression": "0 9 * * 1-5",
      "timezone": "Europe/London"
    }
  },
  "enabled": false,
  "activeRunId": null,
  "latestRunId": null,
  "userId": "",
  "metadata": {
    "team": "support",
    "pausedBy": "ops"
  },
  "deletedAt": null,
  "createdAt": "2026-07-10T10:00:00.000Z",
  "updatedAt": "2026-07-10T10:15:00.000Z"
}

Errors

Status	Codes	Description
`400`	`validation_failed`	The request is invalid
`401`	`unauthorized`	The credential is missing or invalid
`402`	`subscription_required`	An active subscription or usage credit is required
`404`	`not_found`, `agent_version_not_found`	The resource was not found

See REST errors for the error envelope and shared codes.

cURL

curl --request PATCH "$BLAZING_AGENTS_BASE_URL/v1/tasks/tk_1234567890ABCDEF" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"enabled":false,"metadata":{"team":"support","pausedBy":"ops"}}'

Delete taskDELETE`/v1/tasks/:taskId`

Delete a task.

Deletes a task and stops its schedule. Its past runs and their transcripts are kept. A task with a queued or running run cannot be deleted: wait for the run to finish or cancel it first. After deletion, the task ID returns 404 everywhere.

Request

Requires bearer authentication.

Field	Type	Location	Required	Description
`taskId`	string	path	required	ID of the task.

Response

A page of tasks.

TaskListobjectrequired

A page of tasks.

Returns 204 No Content. The task was deleted.

Errors

Status	Codes	Description
`400`	`validation_failed`	The request is invalid
`401`	`unauthorized`	The credential is missing or invalid
`402`	`subscription_required`	An active subscription or usage credit is required
`404`	`not_found`	The resource was not found
`409`	`task_active_run_exists`	The request conflicts with the resource's current state

See REST errors for the error envelope and shared codes.

cURL

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

Tasks and schedules to plan background work.
Task runs API to start and watch runs.

Overview

Tool approval policy

Endpoints

List tasksGET/v1/tasks

Request

Errors

cURL

Create taskPOST/v1/tasks

Request

Errors

cURL

Get taskGET/v1/tasks/:taskId

Request

Errors

cURL

Update taskPATCH/v1/tasks/:taskId

Request

Errors

cURL

Delete taskDELETE/v1/tasks/:taskId

Request

Errors

cURL

Next

List tasksGET`/v1/tasks`

Create taskPOST`/v1/tasks`

Get taskGET`/v1/tasks/:taskId`

Update taskPATCH`/v1/tasks/:taskId`

Delete taskDELETE`/v1/tasks/:taskId`