Tasks

client.tasks runs an agent in the background with no user present. A task saves a prompt for one agent; each run executes it once in a fresh session. Start runs yourself or give the task a schedule. To decide between tasks and chat, and to design a schedule, read Tasks and Schedules.

const { task, runId } = await client.tasks.create({
  agentId,
  name: "Release summary",
  prompt: "Summarize the release queue.",
  submit: true,
});

// Later, from any request or worker:
const run = await client.tasks.getRun({ taskId: task.id, runId: runId! });
console.log(run.status);

Every method takes one input object and accepts an optional abortSignal.

Runs

A task has at most one active run at a time. A run moves from queued to running, then ends as succeeded, failed, canceled, or blocked. blocked means the run was not allowed to start, for example because a quota ran out; error says why.

Runs use the agent's approvalInTasks policy. Nobody is there to approve a call, so tool calls that would need a person are denied and the agent is told so. See tool approvals.

Available operations

Methods

create()

Creates a task that runs on demand or on a schedule.

Signature: create(input: CreateTaskBody & ResourceRequestOptions): Promise<CreateTaskResponse>

const { task } = await client.tasks.create({
  agentId,
  name: "Weekday summary",
  prompt: "Summarize open support cases.",
  schedule: {
    kind: "cron",
    config: { expression: "0 9 * * 1-5", timezone: "Europe/London" },
  },
});

Calling create() twice creates two tasks. Returns CreateTaskResponse. Errors: validation_failed, agent_version_not_found, admin_agent_managed, and agent_disabled when submit is true.

list()

Lists your tasks with each one's latest run.

Signature: list(input?: TasksListOptions): Promise<TasksListResponse>

const { data } = await client.tasks.list({ agentId });
for (const task of data) console.log(task.name, task.latestRun?.status);

Returns TasksListResponse. Errors: validation_failed, invalid_cursor.

get()

Reads one task.

Signature: get(input: { taskId: string } & ResourceRequestOptions): Promise<TaskResponse>

const task = await client.tasks.get({ taskId });

Returns TaskResponse. Errors: validation_failed, not_found.

update()

Changes a task's name, prompt, schedule, version pin, or metadata, or pauses its schedule.

Signature: update(input: UpdateTaskBody & { taskId: string } & ResourceRequestOptions): Promise<TaskResponse>

const task = await client.tasks.update({ taskId, enabled: false });

Takes taskId plus any of name, prompt, schedule, enabled, agentVersion, and metadata, with at least one. Fields you leave out stay as they are. schedule: null makes the task on-demand, and agentVersion: null goes back to the current version. agentId and userId cannot change, and runs that already exist keep their settings.

Returns TaskResponse. Errors: validation_failed, not_found, agent_version_not_found, admin_agent_managed.

delete()

Deletes a task and stops its schedule. Past runs and their sessions stay readable.

Signature: delete(input: { taskId: string } & ResourceRequestOptions): Promise<void>

await client.tasks.delete({ taskId });

Fails with task_active_run_exists while a run is active; cancel it first. Errors: validation_failed, not_found, task_active_run_exists.

createRun()

Starts a run now and returns its ID without waiting for it.

Signature: createRun(input: CreateTaskRunBody & { taskId: string } & ResourceRequestOptions): Promise<CreateTaskRunResponse>

const { runId } = await client.tasks.createRun({
  taskId,
  idempotencyKey: "release-summary-2026-09-26",
});

Returns { runId: string }. Save it and check the run later with getRun(). Errors: validation_failed, not_found, task_active_run_exists, agent_version_not_found, agent_disabled.

listRuns()

Lists a task's runs, newest first.

Signature: listRuns(input: { taskId: string } & TaskRunsListOptions): Promise<TaskRunsListResponse>

const { data } = await client.tasks.listRuns({ taskId, limit: 10 });

Returns TaskRunsListResponse. Errors: validation_failed, invalid_cursor, not_found.

getRun()

Reads one run's status.

Signature: getRun(input: { taskId: string; runId: string } & ResourceRequestOptions): Promise<TaskRunResponse>

const run = await client.tasks.getRun({ taskId, runId });
if (run.status === "queued" || run.status === "running") {
  console.log("Still working; check again later.");
} else {
  console.log(run.status, run.error);
}

Returns TaskRunResponse. sessionId is null until the run starts. Errors: validation_failed, not_found.

runMessages()

Reads the messages from a run's session, the same way sessions.messages() does.

Signature: runMessages(input: { taskId: string; runId: string } & TaskRunMessagesOptions): Promise<TaskRunMessagesResponse>

const page = await client.tasks.runMessages({ taskId, runId });
const newer = page.latestCursor
  ? await client.tasks.runMessages({ taskId, runId, after: page.latestCursor })
  : null;

A run that has not started returns an empty page. Do not pass cursor and after together. Returns TaskRunMessagesResponse. Errors: validation_failed, invalid_cursor, not_found.

cancelRun()

Asks a run to stop and returns without waiting.

Signature: cancelRun(input: { taskId: string; runId: string } & ResourceRequestOptions): Promise<void>

await client.tasks.cancelRun({ taskId, runId });

The run stops at its next safe point; poll getRun() until its status is canceled or another final state. Cancelling a run that already finished, or a run ID the task does not have, does nothing. Errors: validation_failed, and not_found when the task does not exist.

Response types

TaskResponse

CreateTaskResponse

interface CreateTaskResponse {
  task: TaskResponse;
  runId: string | null;
}

runId is set only when you passed submit: true.

TasksListResponse

interface TasksListResponse {
  data: Array<
    TaskResponse & {
      latestRun: { id: string; status: TaskRunStatus; finishedAt: string | null } | null;
    }
  >;
  nextCursor: string | null;
}

TaskRunResponse

type TaskRunStatus = "queued" | "running" | "blocked" | "succeeded" | "failed" | "canceled";

interface TaskRunsListResponse {
  data: TaskRunResponse[];
  nextCursor: string | null;
}

TaskRunMessagesResponse

interface TaskRunMessagesResponse {
  data: SessionMessage[];
  nextCursor: string | null;
  latestCursor: string | null;
}

SessionMessage is described in the sessions reference.

Schedule types

type TaskScheduleInput =
  | { kind: "once"; config: { at: string } }
  | { kind: "interval"; config: { everyMs: number } }
  | { kind: "cron"; config: { expression: string; timezone?: string; staggerMs?: number } };

• once: runs at at, an ISO 8601 timestamp with an offset.
• interval: runs every everyMs milliseconds, at least 60,000.
• cron: a five-field numeric cron expression, such as "0 9 * * 1-5". timezone is an IANA name and defaults to "UTC". staggerMs adds a delay of up to that many milliseconds.

A scheduled fire is skipped while another run of the task is active or the agent is disabled. See Schedules.

Errors

Failures throw BlazingAgentsError. The task codes:

Next

• Tasks
• Schedules
• Sessions reference