Get run result
get_run_resultGet a Plori agent run's status, timing, credits, tokens, and live activity. Wait for completion or human input to retrieve the final reply, files, or error details.
Instructions
Get a run's status, timing, attributed credits (micro-US-dollars) and tokens, and what it is doing while it runs: last_worklog (the agent's own most recent note), last_tool_step ("running ", or "completed " between calls), last_activity_at, and tool_progress (active calls, last completion time, completed-call count) when telemetry exists. With wait=true it holds your turn until the run finishes, pauses for input, or the hold ends (contract in the server instructions; wait_seconds bounds it). A completed run includes the reply text and a url to its session; files the reply linked come back as absolute URLs in the text and as a "files" list, fetched with the same bearer token you called this tool with. A failed or cancelled run includes its cause, whether it is retryable, and an "error" object saying what happened, whether the work was charged and what to do next. Status "awaiting_input" includes pending requests. Show the owner each approval request's approve_url. Once that request is answered, input_status reads "answered" and continuation_run_id names the run to poll next; "cancelled" or "expired" means the run will never resume, so stop polling it. Keep polling a non-terminal run at poll_after_seconds.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| wait | No | When true, wait for a terminal result or human input (see this tool's description for how long the hold lasts). After this tool returns, continue polling while status is non-terminal; it cannot wake an idle client. | |
| run_id | Yes | The run id returned by invoke_agent. | |
| agent_id | Yes | The agent's UUID. | |
| wait_seconds | No | Optional: how many seconds to wait when wait=true (maximum 1800). Omit to use the window your MCP client can hold. |
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 on the agent's disk 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. | |
| status | Yes | The current run status. | |
| 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. | |
| ended_at | No | When the run reached a terminal state. | |
| retryable | No | Whether sending the same message again could plausibly succeed. False for a cause the same request would hit again, including time_limit — split the work or raise max_turn_seconds instead of retrying it unchanged. | |
| session_id | Yes | The durable conversation/session identifier. | |
| started_at | No | When the run started. | |
| 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. | |
| input_expired | No | True when this run is parked on a question its session 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 | Legacy spelling of poll_after_seconds in milliseconds; the two always agree. Prefer poll_after_seconds. | |
| 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. | |
| 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. |