Get Phoenix Run Status
The v2 MCP API is in preview and not yet generally available. These pages document its tools and request/response shapes; live data access is limited to enrolled organizations until v2 is released.
Check the status and details of a Phoenix agent run started by phoenix_invoke_agent. Returns the current status (queued | running | succeeded | partially_failed | failed), any generated artifacts (with absolute URLs), the agent name, inputs, timestamps, and credit cost. Use this once the user asks whether their run/brief is done, or to grab the artifact link after a run succeeds. If the run is still queued or running, return the status and run id to the user rather than calling this tool again in a loop; repeated polling within one turn will exhaust the step budget. Do NOT use this to start a run — use phoenix_invoke_agent; to browse every deliverable the org has (not just one run) use phoenix_list_artifacts, and to inline one artifact's HTML body use phoenix_get_artifact.
Credits
Free — No credits consumed. See the full credit table for how AI Credits work.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
run_id Required | string | - | The run id to check (UUID). This is the runId returned by phoenix_invoke_agent. |
Use Cases
- Check whether a previously started agent run has finished
- Retrieve the artifact URL after a run succeeds
- Report a run's credit cost (tool + LLM credits) back to the user
- Confirm a run failed and surface the failure status
Example Usage
Check a run by its id
{
"tool": "phoenix_get_run_status",
"arguments": {
"run_id": "00000000-0000-0000-0000-000000000000"
}
}
Response Format
| Field | Type | Description |
|---|---|---|
runId | string | Unique identifier for the agent run |
status | string | Current status of the run |
agentName | string | null | Name of the agent that was executed |
inputs | object | Input parameters provided to the agent |
startedAt | string | null | ISO timestamp when the run started; null while queued |
finishedAt | string | null | ISO timestamp when the run completed; null while queued or running |
artifacts | array | Generated artifacts from the run (empty when the run has no downloadable artifact) |
artifacts[].id | string | Artifact identifier |
artifacts[].type | string | Artifact type (html, markdown, pdf, table) |
artifacts[].url | string | Absolute URL to view the artifact |
artifacts[].byteSize | number | Artifact size in bytes (omitted when unknown) |
costSummary | object | Credit usage summary for the run |
costSummary.tool_credits | number | Credits used for tool calls |
costSummary.llm_credits | number | Credits used for LLM inference |
costSummary.total_credits | number | Total credits consumed |
Related Tools
phoenix_invoke_agent, phoenix_list_agents, phoenix_get_artifact, phoenix_list_artifacts