Send a follow-up

POST/o/{org}/sessions/{session}/messages
View .md

Delivers a message to the session's agent. A parked sandbox is woken first. While a turn is still running the message waits in line and runs next; the answer's turn says which (running or queued), and its id is the turn to read with GET …/p/_/sessions/{session}/turns/{turn}. The session's own status stays the machine's, so it can read completed with the previous turn's answer while a queued turn waits. At most 20 follow-ups wait at once; the next is 429 QUEUE_FULL. Files land in the sandbox beside the session's first ones.

Authenticate with an API key or a signed-in session.

Path parameters

orgstringrequired

The org's slug or id. A caller with no role in the org gets 404.

sessionstringrequired

The session's full id (execution_id).

Request body

inputstring | array of object | objectrequired

The task, as a string or as content blocks. Text blocks are joined, with a blank line between them, into the prompt (at most 256 KiB, at least one text block). Every file block is stored before the run starts and downloaded into the sandbox at /workspace/.rush/attachments/, where the prompt names it.

Responses

202Accepted; the session as GET reads it, and the turn the message opened.
execution_idstringrequired

The session id.

org_idstringrequired

The org as the request's path named it.

project_idstringoptional

The Project the console ran the session in.

Format uuid
statusstringrequired

paused is a resumable session parked between turns; needs_review finished without the proof it was asked for; cancelling appears only in the 202 answer to a cancel whose sandbox is still being released; GET reads cancelled once it is.

One ofqueuedallocatingrunningpausedinput_requiredneeds_reviewcompletedfailedcancellingcancelledexpired
harnessstringoptional

claude, codex or opencode.

agent_idstringoptional

The saved agent the session was started from, if any.

Format uuid
modelstringoptional
effortstringoptional
resultstringoptional

The agent's final answer for the last finished turn, in full.

turnobjectoptional

Only on a follow-up's answer: the turn the message opened, running or waiting in line (queued).

2 fields
idstringrequired
Format uuid
statusstringrequired
One ofrunningqueued
recapobjectoptional

What the last finished turn did, written from result when it finished: the line Rush's notifications lead with. Absent when the turn left no answer.

2 fields
headlinestringrequired
at most 80 characters
pointsarray of stringoptional
errorobjectoptional

Why a failed or expired run ended. message is a sentence a person can act on.

2 fields
codestringrequired

A plan or account limit the run hit (FREE_TRIAL_USED, PLAN_REQUIRED, TOKEN_LIMIT_REACHED, CREDITS_EXHAUSTED, SPEND_CAP_REACHED, COMPUTE_LIMIT_REACHED, WEEKLY_COMPUTE_LIMIT_REACHED, PAYMENT_METHOD_REQUIRED), the model account it used (PROVIDER_AUTH_FAILED, PROVIDER_RATE_LIMITED, MODEL_ACCOUNT_MISSING), how it ended (HARNESS_EXITED, RUN_STALLED, RUN_TIMED_OUT, RUN_START_FAILED, MACHINE_UNAVAILABLE, MACHINE_REFUSED, MACHINE_LOST, LEASE_EXPIRED, SAVED_STATE_EXPIRED, BRANCH_NOT_FOUND, AGENT_UNAVAILABLE, CONNECTION_UNAVAILABLE, AUTH_FAILED), or RUN_FAILED. Runs that failed before codes were recorded read RUN_FAILED.

messagestringrequired
repo_ownerstringoptional
repo_namestringoptional
branchstringoptional
pr_urlstringoptional
input_tokensintegeroptional
output_tokensintegeroptional
cache_read_tokensintegeroptional
cache_write_tokensintegeroptional
total_tokensintegeroptional

Uncached input plus cache writes plus output.

reasoning_tokensintegeroptional
total_cost_usdnumberoptional
tool_calls_countintegeroptional
turns_countintegeroptional
artifactsarray of objectoptional

Every file the agent saved to /workspace/.rush/artifacts/. url downloads it from this API with no credential until url_expires_at, an hour after the read; read the session again for a fresh link. GET …/artifacts/{name} with the key also downloads it.

4 item fields
namestringrequired
mime_typestringrequired
urlstringrequired

A signed https link to the file on this API.

Format uri
url_expires_atstringrequired
Format date-time
attachmentsarray of objectoptional

The files the session was started or followed up with. url downloads one with no credential until url_expires_at, as for artifacts; GET …/attachments/{id} with the key also downloads it.

5 item fields
idstringrequired
Format uuid
namestringrequired
mime_typestringrequired
urlstringrequired

A signed https link to the file on this API.

Format uri
url_expires_atstringrequired
Format date-time
accountsarray of objectoptional

The connections the session's tokens acted as, one entry per account however often it was used, with when it was first used: a signed-in app account (oauth) or an MCP server signed as one person (mcp); a connection added to the Project for its members is not listed, so its sessions stay readable by the team. The session's agent_id says whose agent it was. Absent when the session used none, and for sessions started before accounts were recorded. Never a token.

5 item fields
kindstringrequired
One ofoauthmcp
vendorstringrequired

For oauth the app vendor (google, microsoft, buffer, quickbooks); for mcp the server's name.

accountstringrequired

For oauth the account's email (for QuickBooks, the company's realm id); for mcp the connection's id, or the server's host when the session supplied its own token.

productsarray of stringoptional

The account's products the session reached, such as gmail or outlook. Absent for mcp.

first_used_atstringrequired
Format date-time
created_atstringoptional
Format date-time
completed_atstringoptional
Format date-time
400No input or a malformed one (INVALID_BODY), its text over 256 KiB (CONTENT_TOO_LARGE), or the removed content field (FIELD_REMOVED, naming input).
errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
401No bearer, an unknown, revoked or expired one, or an API key on a route keys cannot call.
errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
402The session owner's plan does not cover more usage, whoever sends the message (same codes as starting a session).
errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
403Files on a follow-up from someone other than the session's owner (FORBIDDEN).
errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
404No such resource for the caller, including one in an org the caller is not in or a Project that is private to someone else.
errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
409The session cannot take a message: it is closed (TASK_TERMINAL), not started yet, its run cannot be continued (CONTINUATION_UNSUPPORTED) or queue one (PERSISTENCE_MODE_CONFLICT, an ephemeral session mid-turn), or its Project is paused (PROJECT_PAUSED).

The session cannot take a message: it is closed (TASK_TERMINAL), not started yet, its run cannot be continued (CONTINUATION_UNSUPPORTED) or queue one (PERSISTENCE_MODE_CONFLICT, an ephemeral session mid-turn), or its Project is paused (PROJECT_PAUSED). A file_id another run holds is ATTACHMENT_IN_USE; one never PUT to its upload_url is ATTACHMENT_NOT_UPLOADED.

errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
413The request body is over 32 MB (REQUEST_TOO_LARGE), as on session create.
errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
422A url source could not be fetched (INPUT_FETCH_FAILED), as on session create, or a connection the session named was deleted, expired or revoked since (CONNECTION_UNAVAILABLE, naming its id), or an API key sent it to a person's own session, which only the console continues (ACCOUNT_UNSUPPORTED).

A url source could not be fetched (INPUT_FETCH_FAILED), as on session create, or a connection the session named was deleted, expired or revoked since (CONNECTION_UNAVAILABLE, naming its id), or an API key sent it to a person's own session, which only the console continues (ACCOUNT_UNSUPPORTED). Nothing reached the sandbox.

errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
429The account is over its request budget, 1,800 a minute shared by the person's API keys and console on every API host (RATE_LIMITED).

The account is over its request budget, 1,800 a minute shared by the person's API keys and console on every API host (RATE_LIMITED). The error names the limit. Wait Retry-After seconds.

errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
503The runtime could not take the message right now; nothing was delivered.

The runtime could not take the message right now; nothing was delivered. Retry.

errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional

Used in