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

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.

oz run list [flags]

Flags

--limit · integer · default: "10"

Maximum number of runs to return.

Short form: -L

--state · 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.

--source · string

Filter by the source that created the run. Accepted values: api, cli, slack, linear, scheduled-agent, web-app, cloud-mode, github-action, interactive.

--execution-location · string

Filter by where the run executed. Accepted values: local, remote.

--creator · string

Filter by creator user ID.

--environment · string

Filter by environment ID.

--skill · string

Filter by skill specification (e.g. owner/repo:path/to/SKILL.md).

--schedule · string

Filter to runs created by a specific scheduled agent, identified by schedule ID.

--ancestor-run · string

Filter to descendants of a specific run, identified by run ID.

--name · string

Filter by agent config name.

--model · string

Filter by model ID.

--artifact-type · string

Filter by produced artifact type. Accepted values: plan, pull-request, screenshot, file.

--created-after · string

Only include runs created after the given RFC 3339 timestamp.

--created-before · string

Only include runs created before the given RFC 3339 timestamp.

--updated-after · string

Only include runs updated after the given RFC 3339 timestamp.

--query · string

Fuzzy search across run title, prompt, and skill spec.

Short form: -q

--sort-by · string

Field to sort by. Accepted values: updated-at, created-at, title, agent.

--sort-order · string

Sort direction. Accepted values: asc, desc.

--cursor · 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.

Examples

# 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.

oz run get <task_id> [flags]

Arguments

Argument	Description
task_id	The run ID to inspect

Flags

--conversation · boolean

Retrieve the conversation transcript for this run instead of just the run status.

Examples

# 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.

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.

oz run message watch <run_id> [flags]

--since-sequence · integer · default: "0"

Resume after this event sequence number. Use as an inclusive cursor for reconnects.

oz run message send

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

oz run message send --to <run_id> --subject <text> --body <text> --sender-run-id <run_id>

--to · string

Recipient run ID. Repeatable — specify multiple times or use comma-separated values to send to multiple recipients. Required.

--subject · string

Message subject. Required.

--body · string

Message body. Required.

--sender-run-id · string

Sender run ID. Required.

oz run message list

Lists inbox message headers for a run.

oz run message list <run_id> [flags]

--unread · boolean

Only return unread messages.

--since · string

Only return messages sent at or after this RFC 3339 timestamp.

--limit · integer · default: "50"

Maximum number of messages to return.

Short form: -L

oz run message read

Reads the full body of a message.

oz run message read <message_id>

oz run message mark-delivered

Marks a message as delivered.

oz run message mark-delivered <message_id>

Alias: oz run message delivered