Runs | m8tes

A run is one execution of an agent or task. Use runs for direct messages, follow-ups, and real-time output.

Create a run

Streaming (default and recommended)

Use the context manager so the stream closes cleanly even if you exit early:

See Streaming & Events for event types, text-only streaming, and reconnection. Or pass stream=False and poll:

teammate_id is the wire name for the agent id: JSON request and response bodies keep it. The SDK accepts agent_id (canonical) and teammate_id alike.

Run options

Field	Type	Default	Description
`message`	string (required)	n/a	Prompt or instruction for the run
`teammate_id`	int	n/a	Existing agent to execute
`permission_mode`	string	agent default	Override with `autonomous`, `approval`, or `plan`. See Human-in-the-Loop
`user_id`	string	n/a	End-user scope. See Users
`output_schema`	object	n/a	JSON Schema for a typed result. See Structured output

All run options

Field	Type	Default	Description
`stream`	bool	`true`	Stream events in real-time
`tools`	string[]	n/a	Override agent tools for this run
`files`	list	n/a	Input files to upload. See Files
`memory`	bool	`true`	Include saved per-user memory
`history`	bool	`true`	Include prior run context
`human_in_the_loop`	bool	inherited	Omit to inherit `false` for autonomous and `true` for approval/plan
`task_setup_tools`	bool	`true`	Enable the internal same-scope agent, task, run, webhook, inbox, and app-management tools
`feedback`	bool	`true`	Enable the internal issue-reporting tool (`report_issue`)
`email_inbox`	bool	`false`	Enable email inbox on the auto-created agent (only when no `teammate_id` is given). The response includes `email_address`; emails there trigger future runs

Replies inherit task_setup_tools and feedback unless overridden.

Follow up on a run

A follow-up continues the same run: it re-opens the run, keeps the prior context, and does not consume a new run-count slot (it reuses the original run id and only burns tokens).

runs.reply() inherits the run's settings: permission mode keeps applying, and AskUserQuestion stays enabled on runs created with human_in_the_loop: true. Pass human_in_the_loop: false on the reply to pin non-interactive behavior.

Structured output

Pass a JSON Schema as output_schema and the run returns typed data on output_data, so you can act on fields instead of parsing prose.

Python

Schema rules and gotchas

The schema root must be "type": "object", so output_data is always an object.
Inline your definitions. $ref and $defs are rejected. Pydantic's model_json_schema() and zod both emit $defs for nested models, so flatten before sending.
output_data can be null on a completed run. A run cut short by truncation, a pause, or a spend limit still completes, with its text output intact but no structured result. Always null-check.
The schema sticks to the run: replies, resumes, and retries stay structured without re-sending it.
run.completed webhooks carry output_data too.

Run outcome

GET /runs/{id}/outcome returns the condensed result of a run in one call (the agent's closing message, the structured result, and what the run cost) instead of the full transcript.

Outcome fields

Field	Meaning
`summary`	The agent's closing message. `None` when the run ended on a tool call
`headline`	One-line outcome descriptor supplied by the agent, when present
`needs_reply`	`True` when the closing message asks for a decision. Answer via `runs.reply()`
`output_data`	Structured result matching the run's `output_schema`
`cost_usd`	Metered cost as a decimal string. `None` until cost is recorded
`message_count`, `input_tokens`, `output_tokens`, `total_tokens`	Run-level usage metrics

run.status values: running, paused, awaiting_approval (waiting for user input or approval), completed, failed, cancelled, closed, archived.

Execution environment

Every run executes in an isolated cloud sandbox: a fresh, per-account Linux environment where the agent's tools (bash, file edits, computer use) run, away from your data and ours. A run streams a sandbox-connecting event while the environment is readied. The first run of a session boots the sandbox (a few to tens of seconds); later runs in the same session reuse the warm one. A busy account can briefly hit SANDBOX_CONCURRENCY_LIMIT (HTTP 429) when too many sandboxes are live at once; retry with backoff. No provisioning or configuration needed.

Run files

Attach input files with files= on runs.create (see Files). Runs can also generate files; list and download them after execution:

Python

Next: Agents · Tasks · Streaming & Events · Webhook Events