> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/warpdotdev/warp/llms.txt
> Use this file to discover all available pages before exploring further.

# oz run — list and inspect agent task runs

> Use oz run to list, filter, and inspect Oz agent task runs. Retrieve run status, conversation transcripts, and inter-run messages.

The `oz run` command (also available as `oz task`) lets you query and inspect agent task runs — the execution records created each time an agent is dispatched. You can list runs with rich filtering options, retrieve the status and conversation transcript for a specific run, and work with inter-run messages in multi-agent workflows.

## Synopsis

```bash theme={null}
oz run <subcommand> [flags]
```

**Alias:** `oz task`

## Subcommands

| Subcommand                            | Description                                               |
| ------------------------------------- | --------------------------------------------------------- |
| `list`                                | List agent task runs                                      |
| `get <task_id>`                       | Get the status of a specific run                          |
| `conversation get <conversation_id>`  | Retrieve a conversation by conversation ID                |
| `message watch <run_id>`              | Watch for new messages delivered to a run                 |
| `message send`                        | Send a message from one run to one or more recipient runs |
| `message list <run_id>`               | List inbox message headers for a run                      |
| `message read <message_id>`           | Read the full body of a message                           |
| `message mark-delivered <message_id>` | Mark a message as delivered                               |

***

## oz run list

Lists recent agent task runs. By default returns the 10 most recent runs. Supports extensive filtering and sorting.

```bash theme={null}
oz run list [flags]
```

### Flags

<ParamField path="--limit" type="integer" default="10">
  Maximum number of runs to return.

  Short form: `-L`
</ParamField>

<ParamField path="--state" type="string">
  Filter by run state. Repeatable — specify multiple times to match any of several states. Accepted values: `queued`, `pending`, `claimed`, `in-progress`, `succeeded`, `failed`, `error`, `blocked`, `cancelled`.
</ParamField>

<ParamField path="--source" type="string">
  Filter by the source that created the run. Accepted values: `api`, `cli`, `slack`, `linear`, `scheduled-agent`, `web-app`, `cloud-mode`, `github-action`, `interactive`.
</ParamField>

<ParamField path="--execution-location" type="string">
  Filter by where the run executed. Accepted values: `local`, `remote`.
</ParamField>

<ParamField path="--creator" type="string">
  Filter by creator user ID.
</ParamField>

<ParamField path="--environment" type="string">
  Filter by environment ID.
</ParamField>

<ParamField path="--skill" type="string">
  Filter by skill specification (e.g. `owner/repo:path/to/SKILL.md`).
</ParamField>

<ParamField path="--schedule" type="string">
  Filter to runs created by a specific scheduled agent, identified by schedule ID.
</ParamField>

<ParamField path="--ancestor-run" type="string">
  Filter to descendants of a specific run, identified by run ID.
</ParamField>

<ParamField path="--name" type="string">
  Filter by agent config name.
</ParamField>

<ParamField path="--model" type="string">
  Filter by model ID.
</ParamField>

<ParamField path="--artifact-type" type="string">
  Filter by produced artifact type. Accepted values: `plan`, `pull-request`, `screenshot`, `file`.
</ParamField>

<ParamField path="--created-after" type="string">
  Only include runs created after the given RFC 3339 timestamp.
</ParamField>

<ParamField path="--created-before" type="string">
  Only include runs created before the given RFC 3339 timestamp.
</ParamField>

<ParamField path="--updated-after" type="string">
  Only include runs updated after the given RFC 3339 timestamp.
</ParamField>

<ParamField path="--query" type="string">
  Fuzzy search across run title, prompt, and skill spec.

  Short form: `-q`
</ParamField>

<ParamField path="--sort-by" type="string">
  Field to sort by. Accepted values: `updated-at`, `created-at`, `title`, `agent`.
</ParamField>

<ParamField path="--sort-order" type="string">
  Sort direction. Accepted values: `asc`, `desc`.
</ParamField>

<ParamField path="--cursor" type="string">
  Opaque pagination cursor from a previous list response. When using `--cursor`, `--sort-by` and `--sort-order` must match the values used to obtain the cursor.
</ParamField>

### Examples

```bash theme={null}
# List the 10 most recent runs
oz run list

# List up to 50 runs
oz run list --limit 50

# Show only failed runs
oz run list --state failed

# Show runs that are still in progress or queued
oz run list --state in-progress --state queued

# Show runs from the CLI source
oz run list --source cli

# Show runs that ran in a specific environment
oz run list --environment env_abc123

# Find runs matching a search term
oz run list --query "login form validation"

# Show runs created in a time window
oz run list \
  --created-after 2024-01-01T00:00:00Z \
  --created-before 2024-02-01T00:00:00Z

# Sort by creation time, oldest first
oz run list --sort-by created-at --sort-order asc

# Machine-readable JSON output
oz run list --output-format json
```

***

## oz run get

Retrieves the status and details for a specific run by its ID.

```bash theme={null}
oz run get <task_id> [flags]
```

### Arguments

| Argument  | Description           |
| --------- | --------------------- |
| `task_id` | The run ID to inspect |

### Flags

<ParamField path="--conversation" type="boolean">
  Retrieve the conversation transcript for this run instead of just the run status.
</ParamField>

### Examples

```bash theme={null}
# Get run status
oz run get run_abc123

# Get the full conversation transcript
oz run get run_abc123 --conversation

# Machine-readable JSON
oz run get run_abc123 --output-format json
```

***

## oz run conversation get

Retrieves a conversation by its conversation ID.

```bash theme={null}
oz run conversation get <conversation_id>
```

### Arguments

| Argument          | Description                     |
| ----------------- | ------------------------------- |
| `conversation_id` | The conversation ID to retrieve |

***

## oz run message

The `message` subcommands support inter-run communication in multi-agent workflows, allowing one agent to send structured messages to another.

### oz run message watch

Watches for new messages delivered to a run's inbox in real time.

```bash theme={null}
oz run message watch <run_id> [flags]
```

<ParamField path="--since-sequence" type="integer" default="0">
  Resume after this event sequence number. Use as an inclusive cursor for reconnects.
</ParamField>

### oz run message send

Sends a message from one run to one or more recipient runs.

```bash theme={null}
oz run message send --to <run_id> --subject <text> --body <text> --sender-run-id <run_id>
```

<ParamField path="--to" type="string">
  Recipient run ID. Repeatable — specify multiple times or use comma-separated values to send to multiple recipients. Required.
</ParamField>

<ParamField path="--subject" type="string">
  Message subject. Required.
</ParamField>

<ParamField path="--body" type="string">
  Message body. Required.
</ParamField>

<ParamField path="--sender-run-id" type="string">
  Sender run ID. Required.
</ParamField>

### oz run message list

Lists inbox message headers for a run.

```bash theme={null}
oz run message list <run_id> [flags]
```

<ParamField path="--unread" type="boolean">
  Only return unread messages.
</ParamField>

<ParamField path="--since" type="string">
  Only return messages sent at or after this RFC 3339 timestamp.
</ParamField>

<ParamField path="--limit" type="integer" default="50">
  Maximum number of messages to return.

  Short form: `-L`
</ParamField>

### oz run message read

Reads the full body of a message.

```bash theme={null}
oz run message read <message_id>
```

### oz run message mark-delivered

Marks a message as delivered.

```bash theme={null}
oz run message mark-delivered <message_id>
```

**Alias:** `oz run message delivered`