# Task operations

Read a task's status, diagnose it, and choose how to resume or cancel it.

This applies to tasks started from the SDKs, the API, or
`introspection tasks`. A task's conversation has the same id as the task.

## Status lifecycle

| Status | Meaning |
| --- | --- |
| `pending` | Created, not yet accepted. |
| `queued` | Waiting for an organization concurrency slot. |
| `scheduled` | The sandbox is being provisioned. |
| `running` | The agent is working. |
| `awaiting_user` | Paused on one or more interrupts. |
| `idle` | Alive and waiting for the next run. |
| `completed` | Ended without a task error; read `metadata.completion_reason`. |
| `failed` | Ended with an error; read `metadata.error`. |
| `cancelling`, `cancelled` | Cancellation in progress, done. |

## Diagnose a task

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

| Symptom | Read | Meaning |
| --- | --- | --- |
| `completed` | `metadata.completion_reason` | `task_completion` settled normally; `inactivity_timeout` means an idle session expired, possibly with no result. |
| `failed`, no conversation | `metadata.error` | Failed before the agent emitted a trace: sandbox startup, or model access such as `byok_no_endpoints` or `endpoint_credential_missing` ([Bindings](/ship/bindings)). |
| `queued` for long | | Waiting for a concurrency slot. Retrying only adds to the queue; shape the burst ([Limits](/reference/limits#tasks-and-runs)). |
| `awaiting_user` | `metadata.pending_interrupts` | Answer every pending interrupt. |

The row also shows the resolved version, environment, and experiment. Sandbox
stdout and stderr are not collected unless you create the task with
`metadata.collect_sandbox_logs: true`.

## Answer interrupts

Answer each pending interrupt as `resolved` (with a payload) or `cancelled`.
Answering all of them returns the task to `running`; resuming with nothing
pending returns `409`. Code: [JavaScript](/reference/javascript#answer-an-interrupt),
[Python](/reference/python#answer-an-interrupt), or
[`introspection tasks resume`](/reference/cli/deploy#tasks). The recipe side:
[Ask the user](/patterns/ask-the-user).

## Prompt, steer, and provision runs

| Run | Effect |
| --- | --- |
| `prompt` | Opens a new turn. |
| `steer` | Adds guidance to a running turn; acts as `prompt` when none is running. |
| Provision (no prompt, no kind) | Restarts a `completed` or `failed` task's sandbox; a no-op on a live task, `409` on a cancelled one. |

Creating a task without a prompt starts its sandbox early: see
[Warm an interactive task](/reference/javascript#warm-an-interactive-task).

## Cancel: abort or drain

| Mode | Effect |
| --- | --- |
| `abort` | Stops the turn, keeps the sandbox warm; the task returns to `idle`. `introspection tasks cancel` sends this. |
| `drain` | Lets the turn finish, then tears down; the task becomes `cancelled`. `drain_within_seconds` bounds the wait. API and SDKs only. |

Pending interrupts survive a drain and are restored on a fresh sandbox. There
is no bulk cancel.

## Resume after a disconnect

A dropped stream does not cancel the run. Read `active_run_id` or
`latest_run_id` from the task and stream that run again. The SDKs replay it
from the start; the CLI (`tasks stream --since <sequence>`) and the raw API
(`?since=` or `Last-Event-ID`) resume from a cursor. Never create a
replacement task because a stream closed.

## Next

- [Deploy & operate](/reference/cli/deploy#tasks): the `tasks` commands.
- [Ask the user](/patterns/ask-the-user): interrupts end to end.

Task operations

Read a task’s status, diagnose it, and choose how to resume or cancel it.

This applies to tasks started from the SDKs, the API, or introspection tasks. A task’s conversation has the same id as the task.

Status lifecycle

Status	Meaning
`pending`	Created, not yet accepted.
`queued`	Waiting for an organization concurrency slot.
`scheduled`	The sandbox is being provisioned.
`running`	The agent is working.
`awaiting_user`	Paused on one or more interrupts.
`idle`	Alive and waiting for the next run.
`completed`	Ended without a task error; read `metadata.completion_reason`.
`failed`	Ended with an error; read `metadata.error`.
`cancelling`, `cancelled`	Cancellation in progress, done.

Diagnose a task


introspection tasks get <task-id>
introspection conversations get <task-id>

Symptom	Read	Meaning
`completed`	`metadata.completion_reason`	`task_completion` settled normally; `inactivity_timeout` means an idle session expired, possibly with no result.
`failed`, no conversation	`metadata.error`	Failed before the agent emitted a trace: sandbox startup, or model access such as `byok_no_endpoints` or `endpoint_credential_missing` (Bindings).
`queued` for long		Waiting for a concurrency slot. Retrying only adds to the queue; shape the burst (Limits).
`awaiting_user`	`metadata.pending_interrupts`	Answer every pending interrupt.

The row also shows the resolved version, environment, and experiment. Sandbox stdout and stderr are not collected unless you create the task with metadata.collect_sandbox_logs: true.

Answer interrupts

Answer each pending interrupt as resolved (with a payload) or cancelled. Answering all of them returns the task to running; resuming with nothing pending returns 409. Code: JavaScript, Python, or introspection tasks resume. The recipe side: Ask the user.

Prompt, steer, and provision runs

Run	Effect
`prompt`	Opens a new turn.
`steer`	Adds guidance to a running turn; acts as `prompt` when none is running.
Provision (no prompt, no kind)	Restarts a `completed` or `failed` task’s sandbox; a no-op on a live task, `409` on a cancelled one.

Creating a task without a prompt starts its sandbox early: see Warm an interactive task.

Cancel: abort or drain

Mode	Effect
`abort`	Stops the turn, keeps the sandbox warm; the task returns to `idle`. `introspection tasks cancel` sends this.
`drain`	Lets the turn finish, then tears down; the task becomes `cancelled`. `drain_within_seconds` bounds the wait. API and SDKs only.

Pending interrupts survive a drain and are restored on a fresh sandbox. There is no bulk cancel.

Resume after a disconnect

A dropped stream does not cancel the run. Read active_run_id or latest_run_id from the task and stream that run again. The SDKs replay it from the start; the CLI (tasks stream --since <sequence>) and the raw API (?since= or Last-Event-ID) resume from a cursor. Never create a replacement task because a stream closed.

Deploy & operate: the tasks commands.
Ask the user: interrupts end to end.