# Task operations

Operate the complete task lifecycle without confusing queueing, disconnects, idle completion, agent failures, or infrastructure failures.

Start with [Tasks and runs](/platform/tasks-and-runs) for the execution model.
This page is the operational reference.

## Status lifecycle

| Status | Meaning |
| --- | --- |
| `pending` | Created but not yet accepted for execution. |
| `queued` | Accepted and waiting for an organization concurrency slot. |
| `scheduled` | Assigned; the sandbox is being provisioned. |
| `running` | The agent is actively working. |
| `awaiting_user` | Paused on one or more human interrupts. |
| `idle` | An interactive task is alive and waiting for another run. |
| `completed` | Reached the end of its lifecycle without a task error. Read `completion_reason`. |
| `failed` | Ended with an error. Read `metadata.error`. |
| `cancelling` | A cancellation request is being applied. |
| `cancelled` | Cancelled and stopped. |

One-shot tasks usually move from `queued` to `scheduled`, `running`, and
`completed`. Interactive tasks return to `idle` between turns.

## Diagnose the task row first

**CLI:**

```bash
introspection tasks get <task-id>
```

**JS SDK:**

```ts
const task = await runner.tasks.get(taskId);
console.dir(task, { depth: null });
```

The task row is the system of record for lifecycle diagnosis:

- `metadata.completion_reason` explains why a completed task ended.
  `task_completion` means the work settled normally;
  `inactivity_timeout` means an idle session expired and may have produced no
  result.
- `metadata.error` explains a failed task, including failures that happened
  before the agent ran.
- `metadata.conversation_id` links to the exact conversation when the sandbox
  emitted a trace.
- resolved runtime, recipe, environment, and experiment fields show what was
  actually served.

Do not infer success from status alone and do not begin by selecting the newest
conversation in a runtime-wide list.

## A task that never produced a conversation

Some failures happen before the agent emits any trace:

- The sandbox terminated during startup, never became ready, or could not
  receive the initial prompt.
- The runtime could not resolve model access, such as `byok_no_endpoints` or an
  `endpoint_credential_missing` binding.

These tasks have no conversation because conversations are assembled from spans
the sandbox emits. Diagnose the task's `metadata.error`. Fix binding errors in
[Bindings](/platform/bindings); treat sandbox readiness failures as
infrastructure failures rather than recipe behavior.

## A task that stays queued

`queued` means the task is waiting for an organization concurrency slot. A
queued task proceeds when a slot frees, is cancelled by the caller, or is
cancelled after the queue-wait budget. Retrying only adds more work to the
queue.

There is no CLI or dashboard setting for organization concurrency. Shape the
burst or let the queue drain; contact Introspection when the workload requires
more capacity than the current plan provides.

## Human interrupts

When an agent reaches a permission or decision requiring a person, the task
moves to `awaiting_user`. Its metadata lists the pending interrupts.

The caller answers each interrupt as:

- `resolved`, optionally with a payload; or
- `cancelled` when the requested action should not proceed.

Resolving every pending interrupt returns the task to `running`. Resolving only
some keeps it at `awaiting_user`. Resuming is idempotent: submitting an already
resolved response batch again is a no-op.

Use the [JavaScript](/sdk/javascript) or [Python](/sdk/python) resume APIs, or
the [CLI task commands](/sdk/cli/data) for the exact payload contract.

## Prompt, steer, and provision runs

A task can contain several runs:

| Kind | Effect |
| --- | --- |
| `prompt` | Opens a fresh turn from a prompt. |
| `steer` | Injects guidance into a turn already in progress; falls back to `prompt` when none is active. |
| Provision | A request with no prompt and no kind prepares or restarts the sandbox without opening a turn. |

A provision call restarts a terminal task before the next prompt. On a
non-terminal task, including a newly created task that is already provisioning,
it is a no-op reporting current status. Applications can use promptless creation
to overlap sandbox startup with the user's composing time; see
[Warming an interactive task](/sdk/javascript#warming-an-interactive-task).

## Abort versus drain

Cancellation has two meanings:

| Mode | Effect |
| --- | --- |
| `abort` | Interrupts the active turn and keeps the sandbox warm. The task returns to `idle`. |
| `drain` | Lets the active turn settle, then tears down the sandbox. The task becomes `cancelled`. |

Use `abort` for an interactive Stop button when the next prompt should reuse the
same task. Use `drain` to release the sandbox and end the task. A drain request
can include `drain_within_seconds` to force teardown if the turn does not settle
in time.

Pending human interrupts survive a drain. A later resume rehydrates them on a
fresh sandbox rather than losing the exchange.

`introspection tasks cancel` sends `abort`: it stops the active turn and
leaves the task warm and idle. To drain, call the task cancellation API or
SDK with `{"mode":"drain"}`.

## Resume after a disconnect

A network disconnect or gateway timeout can sever the live stream without
cancelling the run. Persist the task ID, run ID, and last event ID, then
reattach and request events after the last sequence you processed.

Do not create a replacement task merely because the browser reloaded or a
stream closed. The original task may still be running and would produce
duplicate work. See [Resumable streams](/sdk/javascript#resumable-streams) for
the SDK pattern.

## Operational checklist

When a task looks wrong:

1. Fetch the exact task row.
2. Check status, `completion_reason`, `error`, runtime version, and environment.
3. If a conversation ID exists, inspect that exact conversation.
4. If no conversation exists, diagnose provisioning, bindings, or model access.
5. If queued, inspect concurrency rather than retrying.
6. If awaiting a person, resolve or cancel every pending interrupt.
7. If a stream disconnected, reattach before creating new work.
8. When cancelling, choose deliberately between aborting the turn and draining
   the task.

## Related

- [Tasks and runs](/platform/tasks-and-runs): concise execution model and first task.
- [Tags](/platform/tags): organize tasks and control cohort access.
- [State and artifacts](/platform/state-and-artifacts): files, memory, shares, and persistence.
- [API reference](/api-reference): complete task and run request schemas.

Task operations

Operate the complete task lifecycle without confusing queueing, disconnects, idle completion, agent failures, or infrastructure failures.

Start with Tasks and runs for the execution model. This page is the operational reference.

Status lifecycle

Status	Meaning
`pending`	Created but not yet accepted for execution.
`queued`	Accepted and waiting for an organization concurrency slot.
`scheduled`	Assigned; the sandbox is being provisioned.
`running`	The agent is actively working.
`awaiting_user`	Paused on one or more human interrupts.
`idle`	An interactive task is alive and waiting for another run.
`completed`	Reached the end of its lifecycle without a task error. Read `completion_reason`.
`failed`	Ended with an error. Read `metadata.error`.
`cancelling`	A cancellation request is being applied.
`cancelled`	Cancelled and stopped.

One-shot tasks usually move from queued to scheduled, running, and completed. Interactive tasks return to idle between turns.

Diagnose the task row first

CLI


introspection tasks get <task-id>

The task row is the system of record for lifecycle diagnosis:

metadata.completion_reason explains why a completed task ended. task_completion means the work settled normally; inactivity_timeout means an idle session expired and may have produced no result.
metadata.error explains a failed task, including failures that happened before the agent ran.
metadata.conversation_id links to the exact conversation when the sandbox emitted a trace.
resolved runtime, recipe, environment, and experiment fields show what was actually served.

Do not infer success from status alone and do not begin by selecting the newest conversation in a runtime-wide list.

A task that never produced a conversation

Some failures happen before the agent emits any trace:

The sandbox terminated during startup, never became ready, or could not receive the initial prompt.
The runtime could not resolve model access, such as byok_no_endpoints or an endpoint_credential_missing binding.

These tasks have no conversation because conversations are assembled from spans the sandbox emits. Diagnose the task’s metadata.error. Fix binding errors in Bindings; treat sandbox readiness failures as infrastructure failures rather than recipe behavior.

A task that stays queued

queued means the task is waiting for an organization concurrency slot. A queued task proceeds when a slot frees, is cancelled by the caller, or is cancelled after the queue-wait budget. Retrying only adds more work to the queue.

There is no CLI or dashboard setting for organization concurrency. Shape the burst or let the queue drain; contact Introspection when the workload requires more capacity than the current plan provides.

Human interrupts

When an agent reaches a permission or decision requiring a person, the task moves to awaiting_user. Its metadata lists the pending interrupts.

The caller answers each interrupt as:

resolved, optionally with a payload; or
cancelled when the requested action should not proceed.

Resolving every pending interrupt returns the task to running. Resolving only some keeps it at awaiting_user. Resuming is idempotent: submitting an already resolved response batch again is a no-op.

Use the JavaScript or Python resume APIs, or the CLI task commands for the exact payload contract.

Prompt, steer, and provision runs

A task can contain several runs:

Kind	Effect
`prompt`	Opens a fresh turn from a prompt.
`steer`	Injects guidance into a turn already in progress; falls back to `prompt` when none is active.
Provision	A request with no prompt and no kind prepares or restarts the sandbox without opening a turn.

A provision call restarts a terminal task before the next prompt. On a non-terminal task, including a newly created task that is already provisioning, it is a no-op reporting current status. Applications can use promptless creation to overlap sandbox startup with the user’s composing time; see Warming an interactive task.

Abort versus drain

Cancellation has two meanings:

Mode	Effect
`abort`	Interrupts the active turn and keeps the sandbox warm. The task returns to `idle`.
`drain`	Lets the active turn settle, then tears down the sandbox. The task becomes `cancelled`.

Use abort for an interactive Stop button when the next prompt should reuse the same task. Use drain to release the sandbox and end the task. A drain request can include drain_within_seconds to force teardown if the turn does not settle in time.

Pending human interrupts survive a drain. A later resume rehydrates them on a fresh sandbox rather than losing the exchange.

introspection tasks cancel sends abort: it stops the active turn and leaves the task warm and idle. To drain, call the task cancellation API or SDK with {"mode":"drain"}.

Resume after a disconnect

A network disconnect or gateway timeout can sever the live stream without cancelling the run. Persist the task ID, run ID, and last event ID, then reattach and request events after the last sequence you processed.

Do not create a replacement task merely because the browser reloaded or a stream closed. The original task may still be running and would produce duplicate work. See Resumable streams for the SDK pattern.

Operational checklist

When a task looks wrong:

Fetch the exact task row.
Check status, completion_reason, error, runtime version, and environment.
If a conversation ID exists, inspect that exact conversation.
If no conversation exists, diagnose provisioning, bindings, or model access.
If queued, inspect concurrency rather than retrying.
If awaiting a person, resolve or cancel every pending interrupt.
If a stream disconnected, reattach before creating new work.
When cancelling, choose deliberately between aborting the turn and draining the task.

Tasks and runs: concise execution model and first task.
Tags: organize tasks and control cohort access.
State and artifacts: files, memory, shares, and persistence.
API reference: complete task and run request schemas.