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

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 output

See 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_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

FieldTypeDefaultDescription
messagestring (required)n/aPrompt or instruction for the run
teammate_idintn/aExisting agent to execute
permission_modestringagent defaultOverride with autonomous, approval, or plan. See Human-in-the-Loop
user_idstringn/aEnd-user scope. See Users
output_schemaobjectn/aJSON Schema for a typed result. See Structured output
All run options
FieldTypeDefaultDescription
streambooltrueStream events in real-time
toolsstring[]n/aOverride agent tools for this run
fileslistn/aInput files to upload. See Files
memorybooltrueInclude saved per-user memory
historybooltrueInclude prior run context
human_in_the_loopboolinheritedOmit to inherit false for autonomous and true for approval/plan
task_setup_toolsbooltrueEnable the internal same-scope agent, task, run, webhook, inbox, and app-management tools
feedbackbooltrueEnable the internal issue-reporting tool (report_issue)
email_inboxboolfalseEnable 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).

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:

Python
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:

Python
# 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, failed or cancelled, 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 closed

A 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, and next_plan_opens_at says 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 waiting run is untouched: its queued automatic start, its tries and its reset time stay as they were. A started run 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.
FieldMeaning
startedRuns resumed by this call
waitingRuns left as they were: every plan is closed, the pace was reached, or no run slot was free
skippedRuns the call left alone, each with a reason: every named run that cannot be continued, and, without run_ids, a stopped run whose start was refused or that changed while the call worked
plans_connected, plans_openConnected plans, and how many are not known to be closed
next_plan_opens_atThe earliest reopening, only when plans are connected and every one is closed

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:

reasonMeaning
not_foundNo such run on your account
not_stopped_by_a_limitNot a failed run that a limit stopped, nor a run held until its plan reopens
cannot_continueA limit stopped it, but it has no saved conversation, is too old, its work was already started again as a new run, or its Continue was refused (funding, account state)
archivedArchived runs are never restarted
already_runningIt is running, or someone started it a moment ago

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.

Python
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", 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 = 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
    pass
Outcome fields
FieldMeaning
summaryThe agent's closing message. None when the run ended on a tool call
headlineOne-line outcome descriptor supplied by the agent, when present
needs_replyTrue when the closing message asks for a decision. Answer via runs.reply()
needs_reply_countWhen several decisions are waiting, how many (may be null)
delivery_channelemail, slack, or none. Set by the agent via set_run_delivery during the run
output_dataStructured result matching the run's output_schema
cost_usdMetered cost as a decimal string. None until cost is recorded
message_count, input_tokens, output_tokens, total_tokensRun-level usage metrics

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:

channelMeaningCompletion email
emailDeep work (report, audit). Short closing hook; depth in latest-report PDFSent when the task has email_notifications: true
slackQuick 1–3 line nudgeSuppressed (first-party only: agent also Slacks via send_slack_message_to_user)
noneAll clear. Nothing worth interruptingSuppressed

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.

Python
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_notifications on 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 a slack or email channel. 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_channel say when and where it went (email or slack).
  • 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.
Python
# 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.

StateWhat to expect
sandbox-connectingFirst run boots the environment; allow a few to tens of seconds
Warm sessionLater runs reuse the sandbox
paused with error_code SANDBOX_CONCURRENCY_LIMITYour account is at its cap on runs at once. A run you start waits for a free slot and starts by itself, oldest first. Nothing to retry. The response to the start still reads running: it turns paused within a moment
429 SANDBOX_CONCURRENCY_LIMITThe platform is at capacity, or the start cannot wait (attachments, a reply that restarts a finished run, a retry): wait for capacity, then retry with backoff

See Computer use for desktop tools.

List runs

sort="priority" puts runs waiting on a human first; the default is newest first.

Python
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:

Python
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

Was this page helpful?