Tool details
| Field | Value |
|---|---|
| Name | list_agent_runs |
| Group | Conversations |
Playground
Input schema
Input schema
{
"type": "object",
"properties": {
"conversation_id": {
"type": "string",
"format": "uuid",
"description": "Conversation identifier that scopes the request."
},
"cursor": {
"type": "string",
"description": "Opaque pagination cursor returned by a previous response."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Maximum number of results to return."
}
},
"required": [
"conversation_id"
],
"additionalProperties": false,
"description": "Input schema for the list_agent_runs tool.",
"$schema": "http://json-schema.org/draft-07/schema#"
}
Output schema
Output schema
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"run_id": {
"type": "string",
"description": "Agent run identifier."
},
"conversation_id": {
"type": [
"string",
"null"
],
"description": "Conversation that owns the run, or null for headless automation runs."
},
"parent_conversation_id": {
"type": [
"string",
"null"
],
"description": "Parent conversation identifier when the run was spawned from another conversation."
},
"message_id": {
"type": [
"string",
"null"
],
"description": "Message identifier that created or currently anchors the run, or null for headless automation runs."
},
"project_id": {
"type": [
"string",
"null"
],
"description": "Project identifier associated with the run."
},
"requested_by_user_id": {
"type": "string",
"description": "User identifier that requested the run."
},
"agent_id": {
"type": "string",
"description": "Agent identifier used for the run."
},
"status": {
"type": "string",
"description": "Lifecycle status of the run."
},
"implementation_kind": {
"type": [
"string",
"null"
],
"description": "Agent implementation selected for the run, when externally handled."
},
"worker_key": {
"type": [
"string",
"null"
],
"description": "Agent worker key selected for the run, when pinned to a connected agent."
},
"source_target_kind": {
"type": [
"string",
"null"
],
"description": "Source target type used to resolve editable project state."
},
"source_target_environment_id": {
"type": [
"string",
"null"
],
"description": "Environment identifier used as the source target."
},
"source_target_branch_id": {
"type": [
"string",
"null"
],
"description": "Branch identifier used as the source target."
},
"runtime_target_kind": {
"type": [
"string",
"null"
],
"description": "Runtime target type used to execute the run."
},
"runtime_target_environment_id": {
"type": [
"string",
"null"
],
"description": "Environment identifier used as the runtime target."
},
"runtime_target_branch_id": {
"type": [
"string",
"null"
],
"description": "Branch identifier used as the runtime target."
},
"parent_run_id": {
"type": [
"string",
"null"
],
"description": "Parent run identifier when the run was spawned from another run."
},
"spawned_from_message_id": {
"type": [
"string",
"null"
],
"description": "Message identifier that spawned this child run."
},
"spawned_from_tool_call_id": {
"type": [
"string",
"null"
],
"description": "Tool call identifier that spawned this child run."
},
"input_anchor_message_id": {
"type": [
"string",
"null"
],
"description": "Message identifier used as the run input anchor."
},
"handoff_message_id": {
"type": [
"string",
"null"
],
"description": "Message identifier used for handoff back into the conversation."
},
"resolved_deployment_id": {
"type": [
"string",
"null"
],
"description": "Deployment identifier selected for the run, when applicable."
},
"latest_event_id": {
"type": "number",
"description": "Highest persisted event identifier for the run."
},
"waiting_tool_call_id": {
"type": [
"string",
"null"
],
"description": "Tool call identifier the run is currently waiting on, when blocked."
},
"waiting_tool_name": {
"type": [
"string",
"null"
],
"description": "Tool name the run is currently waiting on, when blocked."
},
"terminal_error_code": {
"type": [
"string",
"null"
],
"description": "Terminal error code when the run failed."
},
"terminal_error_message": {
"type": [
"string",
"null"
],
"description": "Terminal error message when the run failed."
},
"created_at": {
"type": "string",
"description": "Timestamp when the run was created."
},
"started_at": {
"type": [
"string",
"null"
],
"description": "Timestamp when the run started executing."
},
"finished_at": {
"type": [
"string",
"null"
],
"description": "Timestamp when the run finished."
},
"run_snapshot": {
"type": "object",
"properties": {
"project_agent": {
"anyOf": [
{
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "source",
"description": "The kind associated with this record."
},
"project_id": {
"type": "string",
"description": "Project identifier associated with the record."
},
"agent_id": {
"type": "string",
"description": "The agent id associated with this record."
}
},
"required": [
"kind",
"project_id",
"agent_id"
],
"additionalProperties": false,
"description": "Structured option 1 details associated with this record."
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "installed",
"description": "The kind associated with this record."
},
"project_id": {
"type": "string",
"description": "Project identifier associated with the record."
},
"agent_id": {
"type": "string",
"description": "The agent id associated with this record."
},
"catalog_entry_id": {
"type": "string",
"description": "The catalog entry id associated with this record."
},
"agent_access_grant_id": {
"type": "string",
"description": "The agent access grant id associated with this record."
},
"service_account_id": {
"type": "string",
"description": "The service account id associated with this record."
}
},
"required": [
"kind",
"project_id",
"agent_id",
"catalog_entry_id",
"agent_access_grant_id",
"service_account_id"
],
"additionalProperties": false,
"description": "Structured option 2 details associated with this record."
}
],
"description": "The project agent associated with this record."
},
{
"type": "null",
"description": "The project agent returned by the tool."
}
],
"description": "Runnable project-agent identity selected for this run, or null when legacy provenance is incomplete."
},
"source": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "The type associated with this record."
},
"path": {
"type": [
"string",
"null"
],
"description": "The path associated with this record."
},
"hash": {
"type": [
"string",
"null"
],
"description": "The hash associated with this record."
},
"catalog_entry_id": {
"type": [
"string",
"null"
],
"description": "The catalog entry id associated with this record."
}
},
"required": [
"type",
"path",
"hash",
"catalog_entry_id"
],
"additionalProperties": false,
"description": "Source/catalog provenance captured when the run was queued."
},
"runtime_target": {
"type": "object",
"properties": {
"kind": {
"type": [
"string",
"null"
],
"description": "The kind associated with this record."
},
"environment_id": {
"type": [
"string",
"null"
],
"description": "The environment id associated with this record."
},
"branch_id": {
"type": [
"string",
"null"
],
"description": "Branch identifier associated with the record."
},
"resolved_target_id": {
"type": [
"string",
"null"
],
"description": "The resolved target id associated with this record."
},
"resolved_target_kind": {
"type": [
"string",
"null"
],
"description": "The resolved target kind associated with this record."
},
"deployment_id": {
"type": [
"string",
"null"
],
"description": "The deployment id associated with this record."
}
},
"required": [
"kind",
"environment_id",
"branch_id",
"resolved_target_id",
"resolved_target_kind",
"deployment_id"
],
"additionalProperties": false,
"description": "Runtime target selected for execution."
},
"requester": {
"type": "object",
"properties": {
"user_id": {
"type": "string",
"description": "The user id associated with this record."
}
},
"required": [
"user_id"
],
"additionalProperties": false,
"description": "User that requested the run."
}
},
"required": [
"project_agent",
"source",
"runtime_target",
"requester"
],
"additionalProperties": false,
"description": "Durable run identity projection derived from persisted run columns."
}
},
"required": [
"run_id",
"conversation_id",
"parent_conversation_id",
"message_id",
"project_id",
"requested_by_user_id",
"agent_id",
"status",
"implementation_kind",
"worker_key",
"source_target_kind",
"source_target_environment_id",
"source_target_branch_id",
"runtime_target_kind",
"runtime_target_environment_id",
"runtime_target_branch_id",
"parent_run_id",
"spawned_from_message_id",
"spawned_from_tool_call_id",
"input_anchor_message_id",
"handoff_message_id",
"resolved_deployment_id",
"latest_event_id",
"waiting_tool_call_id",
"waiting_tool_name",
"terminal_error_code",
"terminal_error_message",
"created_at",
"started_at",
"finished_at",
"run_snapshot"
],
"additionalProperties": false,
"description": "Agent run record returned by conversation run tools."
},
"description": "Agent runs for the requested page."
},
"page_info": {
"type": "object",
"properties": {
"self": {
"type": [
"string",
"null"
],
"description": "Cursor representing the current page."
},
"first": {
"type": "null",
"description": "Always null because these MCP pagination flows do not expose a first-page cursor."
},
"next": {
"type": [
"string",
"null"
],
"description": "Cursor for the next page, or null when there are no more results."
},
"prev": {
"type": [
"string",
"null"
],
"description": "Cursor for the previous page, or null when unavailable."
}
},
"required": [
"self",
"first",
"next",
"prev"
],
"additionalProperties": false,
"description": "Pagination cursors for the agent run list."
}
},
"required": [
"data",
"page_info"
],
"additionalProperties": false,
"description": "Paginated agent run list response.",
"$schema": "http://json-schema.org/draft-07/schema#"
}