Documentation

A run is one execution of a teammate 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.

Python

Direct iteration is still supported:

Python

Stream text only

Python

Non-streaming

Follow up on a run

Follow-up messages create a new run that keeps context from the previous one.

Python

runs.reply() is always non-interactive. It does not enable AskUserQuestion, approval mode, or plan mode.

Run options

Field	Type	Default	Description
`message`	string (required)	n/a	Prompt or instruction for the run
`teammate_id`	int	n/a	Existing teammate to execute
`stream`	bool	`true`	Stream events in real-time
`tools`	string[]	n/a	Override teammate tools for this run
`user_id`	string	n/a	End-user scope. See Users
`memory`	bool	`true`	Include saved per-user memory
`history`	bool	`true`	Include prior run context
`task_setup_tools`	bool	`true`	Enable the internal same-scope teammate, task, run, webhook, inbox, and app-management tools for this run
`feedback`	bool	`true`	Enable the internal issue-reporting feedback tool (`report_issue`) for this run
`human_in_the_loop`	bool	inherited	Omit to inherit `false` for autonomous and `true` for approval/plan
`permission_mode`	string	teammate default	Override the teammate default with `autonomous`, `approval`, or `plan`
`email_inbox`	bool	`false`	Enable email inbox on the auto-created teammate. Only applies when creating a new teammate (not when providing `teammate_id`).

When email_inbox=true, the response includes email_address — forward emails to that address to trigger future runs.

Set task_setup_tools=False when you want a public API run to stay limited to the teammate's normal tools. Set feedback=False when you want to disable the internal issue-reporting feedback tool. Replies inherit both settings unless you override them.

For permission and approval flows, see Human-in-the-Loop.

Run statuses

Status	Meaning
`running`	Run is executing
`paused`	Run is paused by execution control flow
`awaiting_approval`	Run is paused for user input or approval
`completed`	Run finished successfully
`failed`	Run failed
`cancelled`	Run was cancelled
`closed`	Run is closed
`archived`	Run is archived

Run files

Runs can generate files. List and download them after execution.

Python

What's next

Teammates for trigger setup and teammate configuration
Tasks for reusable work definitions
Streaming & Events for full event taxonomy
Webhook Events for outbound run notifications