Skip to main content
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

SubcommandDescription
listList 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 sendSend 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

ArgumentDescription
task_idThe 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

ArgumentDescription
conversation_idThe 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

Build docs developers (and LLMs) love

Get started for freeTalk to us