Runs
A run is one execution of an agent or task. Use runs for direct messages, follow-ups, and real-time output.
Run list and detail responses include needs_reply when a completed turn asks for a
concrete replyable decision (approve, answer, connect). It stays true until the ask is
answered or replaced. Viewing the run or receiving it by email does not change it, so a
client that relays asks to its own users can poll it. Soft FYI / out-of-reach notes must not
set needs_reply. Agents choose delivery when awaiting: Slack for one quick decision, email
for deep/batched asks, or in-app only (channel=none) when the user is already in the
run — unattended runs (schedule, webhook, Day-1) must interrupt via Slack or email
(none + needs_reply is rejected there). Send the answer with
runs.reply(); viewing the run does not answer the ask. The m8tes app is the exception
for its own board: it lists such a run under Needs you only until its owner opens it
(last_viewed_at is not before last_activity_at, which runs.mark_viewed() stamps), so an
ask they handled somewhere else does not stay flagged for ever. A run marked Needs me stays
there, and Archive clears a reply-request run in one tap (Undo during the exit animation).
A newer completed scheduled run of the same task (and user_id) supersedes it, so
recurring tasks do not stack stale asks.
closing_preview is a short headline for cards; latest_message_preview contains
up to 600 characters from the latest assistant message for hover previews.
On a finished run, files is the completion-time output list ([{name, size, label}])
when the server stamped a manifest — null means call runs.list_files(); [] means
none. label is an optional human name for the file (a report's title:); downloads
always use name. Bytes still come from runs.download_file.
Create a run
Streaming (default and recommended)
Use the context manager so the stream closes cleanly even if you exit early:
from m8tes import M8tes
client = M8tes()
with client.runs.create(agent_id=1, message="summarize this week's support trends", user_id="customer_42") as stream:
for chunk in stream.iter_text():
print(chunk, end="", flush=True)
print(stream.text) # full accumulated outputSee Streaming & Events for event types, text-only streaming, and reconnection, or pass stream=False and poll:
run = client.runs.create(agent_id=1, message="summarize this week's support trends", stream=False, user_id="customer_42")
run = client.runs.poll(run.id, user_id="customer_42")
print(run.output)
teammate_idis the wire name for the agent id: JSON request and response bodies keep it. The SDK acceptsagent_id(canonical) andteammate_idalike.
Run options
All run options
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).
For a failed or cancelled run, can_continue indicates that it has a saved, unexpired conversation eligible for runs.reply(). Prefer Continue when this is true; a run that never started needs its original task retried. Reply still checks current funding and permissions.
For an explicit continuation, pass reset_auto_recovery=True in Python or { reset_auto_recovery: true } in TypeScript. This grants a fresh three-attempt recovery budget when the reply is accepted, including when it is queued. Automatic loops should leave this option false. auto_recovery_attempt_count reports attempts in the current budget; auto_retry_count preserves the cumulative history. A later platform update can then recover work you explicitly continued, even if an earlier recovery budget was exhausted.
first = client.runs.create_and_wait(agent_id=1, message="find all open incidents", user_id="customer_42")
with client.runs.reply(first.id, message="now draft an update for each owner") as stream:
for chunk in stream.iter_text():
print(chunk, end="", flush=True)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.
Replying while the run is still executing
A reply works on a live run too. If the run's current turn is still executing, the message is queued and delivered as the run's next turn the moment the current one ends. Never a second concurrent execution. The response tells you which happened:
run = client.runs.reply(42, message="also check the staging env", stream=False)
if run.delivery == "queued": # run was mid-turn; message delivers next
print("queued as message", run.queued_message_id)
else: # "resumed": it became the next turn now
print("resumed")With stream=True on a queued reply, the SDK joins the live run's ongoing stream (the queued message itself delivers on the next turn). Delivery normally starts within seconds of the turn ending; across a platform update it can take up to ~15 minutes (the recovery sweep).
Every queued message resolves observably: run.message_received when queued, then either run.started for its delivery turn or run.message_cancelled with a reason (owner cancelled [agent senders only; your own replies to a run you cancelled still deliver and revive it], sandbox expired, account disabled, or 24h undelivered).
While the run is live, replies with file attachments or per-reply overrides (tools, permission_mode, task_setup_tools, feedback, human_in_the_loop) return 409. Overrides only apply to an immediate resume; silently dropping them would be worse.
This is also how agent-to-agent messaging behaves: when one of your agents messages another agent's run, the message arrives the same way. Queued if the target is busy, delivered as the next turn, and always attributed to the sending agent, never to you.
Starting the sandbox while your user types
A reply to a finished run restarts its sandbox, which takes 36 to 61 seconds at the median. Call runs.wake() (POST /runs/{id}/wake) when your user starts typing, and the restore runs while they write the message:
# In your input's change handler: once when typing starts, then at most every 30 seconds.
client.runs.wake(run_id, user_id="customer_42")It is a hint. It answers 204 for any run you can read, does not wait for the sandbox, and starts one only when all of these hold:
- The run is
completed,failedorcancelled, a person started it (not a schedule or a trigger), and no usage limit has queued it to restart by itself. - Its sandbox is stopped or archived on the current runtime, and the run has been quiet for 60 seconds.
- The caller could send the reply, and the account could pay for it and has room for the sandbox.
A run is woken at most once per 30 minutes. An account holds at most 3 wakes at once and 40 a day that nobody replied to. A woken sandbox stays up for at least 10 minutes, so a message that is never sent costs little.
Continue every run a plan limit stopped
When a connected plan runs out of usage, the runs it refused wait to start again by themselves, or sit held until the plan reopens. runs.continue_stopped() resumes them together. It sends "Continue" to each stopped run, the same as runs.reply(id, message="Continue", reset_auto_recovery=True), but it is paced by your plans and never starts a run into a plan that is known to be closed.
result = client.runs.continue_stopped()
print(result.started) # run ids resumed now, oldest stopped first
print(result.waiting) # run ids left exactly as they were
print(result.next_plan_opens_at) # set only when every connected plan is closedA run counts as stopped by a limit when it is failed with failure_kind limit (queued for an automatic retry, or out of tries) or paused and held until its plan reopens, and can_continue is true. A run whose work was already started again as a new run (retried_by_run_id is set) is left out: the retry is the run to continue. Then:
- Every connected plan is closed: nothing starts. Every eligible run comes back in
waiting, andnext_plan_opens_atsays when the first plan reopens. - A plan is open, or no plan is connected: at most three runs start per open plan (three in all when none is connected), oldest stopped first. The rest are in
waiting. Call again for more. - A
waitingrun is untouched: its queued automatic start, its tries and its reset time stay as they were. Astartedrun gets a fresh automatic-retry budget, and no automatic try is spent on it. - The cap on live runs: if your account's cap on runs live at once refuses a start, starting stops there. That run and the rest are
waiting.
Omit run_ids for every such run of your account (its own runs, not its end users'). Then skipped lists only a run that a limit had stopped when the call began and that was not started: its start was refused, or it changed while the call worked (archived, stopped, or started by someone else). Pass up to 200 ids to learn why each run that is left alone is left alone: every named run that cannot be continued lands in skipped. Each skipped run carries one of these reasons:
Calling again is safe: a run that is already running is already_running and nothing starts twice. An Idempotency-Key header is ignored.
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.
run = client.runs.create_and_wait(
agent_id=1,
message="Review this Sentry issue and rate its severity.",
output_schema={"type": "object", "properties": {"severity": {"type": "string", "enum": ["low", "medium", "high"]}}},
user_id="customer_42",
)
if run.output_data: # always None-check
print(run.output_data["severity"]) # -> "high"Schema rules and gotchas
- The schema root must be
"type": "object", sooutput_datais always an object. - Inline your definitions.
$refand$defsare rejected. Pydantic'smodel_json_schema()and zod both emit$defsfor nested models, so flatten before sending. output_datacan benullon a completed run. A run cut short by truncation, a pause, or a spend limit still completes, with its textoutputintact but no structured result. Always null-check.- The schema sticks to the run: replies, resumes, and retries stay structured without re-sending it.
run.completedwebhooks carryoutput_datatoo.
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 = client.runs.outcome(run_id=42)
print(outcome.summary, outcome.cost_usd) # "Audit done: paused 3 wasteful keywords." "0.4831"
if outcome.needs_reply: # the agent is asking for a decision
client.runs.reply(42, message="Approve both")
if outcome.delivery_channel == "none": # agent chose silence. No completion email
passOutcome fields
Scheduled delivery (set_run_delivery)
On scheduled and webhook-triggered runs, the agent chooses how the outcome reaches the owner by calling the set_run_delivery built-in tool before its closing message:
Read the choice from runs.outcome().delivery_channel or run.completed webhook data.delivery_channel. Disable the tool with disabled_builtin_tools: ["delivery"] on the agent.
Embed agents (prompt_profile: "bare") do not receive m8tes's delivery playbook in the system prompt. Document set_run_delivery in your agent instructions if scheduled runs should use it.
run_id = 1
outcome = client.runs.outcome(run_id)
if outcome.delivery_channel == "email" and outcome.needs_reply:
notify_user(outcome.summary, subject=outcome.headline)
elif outcome.delivery_channel == "none":
logger.info("scheduled run chose silence run_id=%s", run_id)Legacy NEEDS-REPLY / HEADLINE: marker lines in closing prose are deprecated; delivery_channel, needs_reply, and headline on outcome and webhooks are authoritative.
run.status values: running, paused (not started yet: held until a model usage limit resets, see a run that has not started), awaiting_approval (waiting for user input or approval), completed, failed, cancelled, closed, archived.
Results nobody has opened
A run you start yourself and walk away from comes to you. Pass email_notifications=True on runs.create() (the m8tes app does this for the runs it starts). If nobody has viewed the finished run 5 minutes after it lands, its closing message is sent to the account owner: a Slack DM when Slack is connected, else email. A reply continues the run.
- Viewed means
runs.mark_viewed(run_id)(POST /runs/{id}/view). The m8tes app calls it while the run is on screen. - The agent decides what is worth sending.
set_run_delivery(channel="none")without an ask keeps a result in the dashboard. An open ask (needs_reply) is always sent. - Runs started in the m8tes app are stricter. The app sets
email_notificationson every run it starts, so there the flag is not a request. A result is sent only when the agent declared it: an ask, or aslackoremailchannel. A run that declared nothing stays in the dashboard. Over the API you set the flag on purpose, so an undeclared result is still sent. run.notified_at/run.notified_channelsay when and where it went (emailorslack).- First-party runs only. A run scoped to one of your end-users (
user_id) is never sent to you. A saved task's run over the API is not sent either, only its scheduled completions. - Turn it off for yourself with
client.settings.update(result_email_enabled=False, result_slack_enabled=False), or Settings → Preferences in the app.
# Personal development only: this disables strict user_id checks account-wide.
# This persists. For customer-facing apps, keep strict mode on and pass user_id.
client.settings.update(require_end_user_id=False)
run = client.runs.create(
agent_id=1,
message="find where checkout drops people",
stream=False,
email_notifications=True,
)Execution environment
Tools run in an isolated, per-account Linux sandbox. m8tes provisions it automatically.
See Computer use for desktop tools.
List runs
sort="priority" puts runs waiting on a human first; the default is newest first.
for run in client.runs.list(sort="priority", limit=20, user_id="customer_42").auto_paging_iter():
print(run.id, run.status)Run files
Attach input files with files= on runs.create (see Files). Runs can also generate files. A finished run may already carry run.files (name, size, optional label); otherwise list and download after execution:
run = client.runs.get(1, user_id="customer_42")
files = run.files if run.files is not None else client.runs.list_files(run_id=1)
for f in files:
print(f.name, f.size)
content = client.runs.download_file(run_id=1, filename="report.csv")Next: Agents · Tasks · Streaming & Events · Webhook Events