Get run result
get_run_resultRetrieve a Plori run's current state by run_id to check status, progress, outputs, files, errors, or wait for completion or input.
Instructions
Get a run's current state by run_id. Every result has the run's status, timing, and attributed credits (micro-US-dollars) and tokens. A run that is still going also has last_worklog (the agent's latest note), last_tool_step, last_activity_at, tool_progress when it is recorded, and poll_after_seconds. A completed run has text (the agent's reply), a url to its conversation in the Plori web app, and files: the files the reply linked, as absolute URLs readable with the same bearer token as this call. Those links read the run's copy while file_source.state is pending and the saved revision once it is ready; save_failure is present when the save failed, and then the files are not durable. When file_source.source is agent_current_files, the links read the agent's current files, which later runs can change. A failed or cancelled run has cause, retryable and an error object that states what happened and whether the run was charged. A run with status "awaiting_input" lists its approval requests and questions, each approval request with an approve_url. After a request is answered, input_status is answered and continuation_run_id names the run that continues the task; input_status cancelled or expired means this run will not continue. An interrupted run that the platform resumed has resume_run_id.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| wait | No | true: hold this call until the run finishes, pauses for a person, or the hold ends (25 seconds by default, 50 seconds for Codex, up to 30 minutes for Claude Code 2.1.212 or later, at most 50 seconds without an MCP progressToken), then return the current state. false or omitted: return the current state at once. | |
| run_id | Yes | The run_id to read: from a run result, continuation_run_id or resume_run_id. | |
| agent_id | No | The agent that ran the run (agent_id in the result that returned the run_id). Give this or workspace_id. | |
| 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 | No | The Workspace the run belongs to. Give this or agent_id; with both, agent_id is used. |
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. |