Send message to Workspace
send_workspace_messageSend a message to a Plori Workspace to start or continue a background agent run that works on its files and saves a new revision, returning run status for long builds or reports.
Instructions
Use this when a build, research or recurring report should run in the background or after the chat ends. Do not use for quick lookups. Send a message to a Workspace's main conversation, or to another of its conversations named by session_id; the Workspace's agent runs it. The run works on the Workspace's current files and saves them as a new revision when it ends. Returns the run with agent_id and workspace_id. A completed run has text (the agent's reply), the files the reply linked, a url to the conversation in the Plori web app, and its credits and tokens; file_source.state ready and no save_failure mean its files are saved. A run still going has status "running", run_id and poll_after_seconds, and continues after this call returns. A paused run has status "awaiting_input" and lists its requests; tell the person each approval's approve_url and who it is assigned to. A run started through this connector pauses before each action outside the agent's own environment (connected-account, MCP and outbound HTTP writes, git push, publishing, deploys, email) until the account owner approves that one action in the Plori web app; the owner's standing approvals do not apply and the calling model cannot approve. While the conversation is running or paused, a plain-text message is accepted as steering or queued (steer_id), or answers an ordinary question assigned to its sender, and never cancels a pending request. A message with attachments or run options gets 409 conversation_busy until the conversation is idle: keep them and resend once it is idle. Runs are charged to the account's prepaid US-dollar balance; a run the balance cannot cover is refused with 402. idempotency_key identifies the request for 24 hours: the same key with the same arguments returns the original result, and the same key with different arguments is refused.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| wait | No | Queued or steering messages return their receipt immediately, regardless of wait. For a newly started or continued run, true (default): hold this call until the run finishes, pauses for a person, or the hold ends. The hold is 25 seconds by default, 50 seconds for Codex, and up to 30 minutes for Claude Code 2.1.212 or later; a call without an MCP progressToken is held at most 50 seconds. If the hold ends first, the result has status "running" and the run continues. false: return the run_id at once. Clients that support MCP Tasks always receive the run_id at once. | |
| message | Yes | The message for the agent, in plain text. | |
| session_id | No | A conversation of this Workspace to continue (session_id from an earlier result). Omitted, the message goes to the main conversation. A worker's private conversation cannot be selected here. | |
| callback_url | No | Optional callback URL for this run. Must use http or https and resolve only to public addresses. | |
| wait_seconds | No | Hold length in seconds when wait is true, used instead of the client default. 0 or omitted uses the client default. A call without an MCP progressToken is still held at most 50 seconds. | |
| workspace_id | Yes | The Workspace UUID. | |
| callback_secret | No | Optional secret used to sign callback deliveries with HMAC-SHA256. | |
| idempotency_key | No | A string of 1-255 bytes you generate for this message. The same key with the same arguments returns the original run or message receipt for 24 hours instead of acting again; the same key with different arguments is refused. Without a key, every call submits a new message. | |
| max_turn_tokens | No | Optional cumulative cache-weighted token ceiling for this turn. 0 or omitted: no ceiling for a registered account, and 2,000,000 for an anonymous trial. The maximum is 5,000,000. The agent reserves its final 2% for a tool-free wrap-up that says the work so far is saved and that a new message continues the task. | |
| max_turn_seconds | No | Optional wall-clock budget for this turn in seconds, maximum 14,400. When it runs out the agent is told to finish and reply; the run is not cancelled. 0 or omitted uses the platform default, when one is set. | |
| max_advisor_spend_micro_usd | No | Optional maximum advisor-completion spend for this turn in micro-US-dollars. 0 disables advisor completions. Omit it or pass null to use the agent setting; when neither is set, at most two advisor calls can run. The maximum is 5,000,000. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | A deep link to this run's session in the plori web app. | |
| hint | No | What to do next with this run, in one sentence. Present only while the run is non-terminal. | |
| text | No | The assistant's reply once the run has finished. While a run is still going this is the run's own status message, not an answer, and is often absent — read last_worklog and last_tool_step instead. | |
| cause | No | Machine-readable cause for a non-normal terminal state. | |
| error | No | Why a terminal error or cancelled run failed, whether it was charged and what to do about it. Absent for a run that is still going or that finished normally. | |
| files | No | Files in the Workspace files that this reply linked, in the order they appear. Each url is fetchable with the bearer token you called this tool with. Absent when the reply linked none. | |
| run_id | Yes | The public run identifier; empty for an answered message whose continuation has not started. | |
| status | Yes | The current run status, queued/steering for a message accepted into an active conversation, or answered when the answer is recorded but its continuation has not started. | |
| tokens | No | Attributed token count; null when attribution is unavailable. | |
| advisor | No | Advisor calls used and allowed, spend this turn, and its optional spend cap in micro-US-dollars. | |
| credits | No | Attributed spend in micro-US-dollars; null when attribution is unavailable. | |
| agent_id | No | The agent that runs the run. get_run_result and cancel_run take this value or workspace_id. | |
| ended_at | No | When the run reached a terminal state. | |
| steer_id | No | Durable message receipt when status is queued or steering. run_id names the running or paused predecessor, not a result of this message; find the later queued turn with list_runs. | |
| retryable | No | Whether sending the same message again could plausibly succeed. A time_limit run can continue with a follow-up message. | |
| session_id | Yes | The durable conversation/session identifier. | |
| started_at | No | When the run started. | |
| file_source | No | Where this run's file links read from and whether its files are saved. Execution status does not report the save; check state here. | |
| stop_reason | No | Controller-selected stop reason, when present. | |
| input_status | No | The durable status of this run's human-input request, when it has one: pending, answered, cancelled or expired. cancelled and expired are terminal — that run will never resume, so stop polling it. | |
| last_worklog | No | The agent's most recent one-sentence note about what it is doing, from the run's durable event log. Absent for a terminal result and for a run that has written none. | |
| save_failure | No | Present when saving the run's working copy failed, so its files are not durable outputs. code names the failure. content_refusals lists up to three refused paths, relative to the copy root, each with its cause: hardlink, database_backup_required (a SQLite file that needs sqlite3 .backup) or unsupported_file_mode. | |
| workspace_id | No | The Workspace UUID. | |
| input_expired | No | True when this run is paused on a question its conversation has already moved past: a later run in the same conversation has completed. Do not answer it; start a new run instead. | |
| poll_after_ms | No | The same wait as poll_after_seconds, in milliseconds. | |
| resume_run_id | No | The exact auto-resume successor for an interrupted run; poll this run next. | |
| resume_status | No | Auto-resume disposition for an interrupted run: pending, resumed, failed, or unknown. | |
| tool_progress | No | Durable tool execution progress; absent when this run has no tool-progress telemetry. | |
| usage_by_role | No | Attributed spend, tokens, and model-call counts split into executor, advisor, and reviewer roles. | |
| last_tool_step | No | What this run last did with a tool: "running <tool>" while a call is in flight, otherwise "completed <tool>" for the most recent finished call. Absent for a terminal result and for a run with no tool-progress telemetry. | |
| pending_inputs | No | Human inputs blocking an awaiting_input run. | |
| elapsed_seconds | No | Seconds since the run started; absent for a terminal result. | |
| upstream_status | No | The model provider's HTTP status when this run died on an upstream fault; absent otherwise. | |
| last_activity_at | No | When the run last wrote a note or finished a tool call. Absent for a terminal result and for a run that has done neither. | |
| last_heartbeat_at | No | Most recent durable executor heartbeat. | |
| continuation_error | No | Why the answered message has not started its continuation. | |
| poll_after_seconds | No | Suggested seconds before polling again, paced to this run's recent tool-completion rate; absent for a terminal result. | |
| continuation_run_id | No | The exact continuation created for an answered input; poll this run next. | |
| continuation_pending | No | The answer was recorded and its continuation has not started yet. Retry this message with the same idempotency key to get the continuation. |