> ## Documentation Index
> Fetch the complete documentation index at: https://veryfront.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# List Agent Runs

> List durable agent runs for a conversation.

export const McpToolCall = ({tool, initialArguments = {}}) => {
  const endpoint = "https://api.veryfront.com/mcp";
  const tokenStorageKey = 'veryfront.docs.mcpBearerToken';
  const escapeHtml = value => value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
  const highlightJson = value => {
    const escaped = escapeHtml(value);
    return escaped.replace(/("(?:\\u[a-fA-F0-9]{4}|\\[^u]|[^\\"])*"(\s*:)?|\btrue\b|\bfalse\b|\bnull\b|-?\d+(?:\.\d+)?(?:[eE][+\-]?\d+)?)/g, match => {
      let color = '#f3f4f6';
      if (match.endsWith(':')) {
        color = '#7dd3fc';
      } else if (match.startsWith('"')) {
        color = '#86efac';
      } else if ((/true|false/).test(match)) {
        color = '#c4b5fd';
      } else if ((/null/).test(match)) {
        color = '#fcd34d';
      } else {
        color = '#67e8f9';
      }
      return `<span style="color: ${color}">${match}</span>`;
    });
  };
  const expandJsonStrings = value => {
    if (typeof value === 'string') {
      const trimmed = value.trim();
      if (trimmed.startsWith('{') && trimmed.endsWith('}') || trimmed.startsWith('[') && trimmed.endsWith(']')) {
        try {
          return expandJsonStrings(JSON.parse(trimmed));
        } catch {}
      }
      return value;
    }
    if (Array.isArray(value)) {
      return value.map(expandJsonStrings);
    }
    if (value && typeof value === 'object') {
      return Object.fromEntries(Object.entries(value).map(([key, nestedValue]) => [key, expandJsonStrings(nestedValue)]));
    }
    return value;
  };
  const formatJson = value => {
    try {
      return JSON.stringify(expandJsonStrings(value), null, 2);
    } catch {
      return String(value);
    }
  };
  const formatResponseText = text => {
    const trimmed = text.trim();
    if (!trimmed) return 'No response body.';
    try {
      return formatJson(JSON.parse(trimmed));
    } catch {}
    const ssePayloads = trimmed.split(/\n\n+/).flatMap(chunk => chunk.split('\n').filter(line => line.startsWith('data:')).map(line => line.slice(5).trim()).filter(Boolean));
    for (let index = ssePayloads.length - 1; index >= 0; index -= 1) {
      try {
        return formatJson(JSON.parse(ssePayloads[index]));
      } catch {}
    }
    return trimmed;
  };
  const readStoredToken = () => {
    if (typeof window === 'undefined') return '';
    try {
      return window.sessionStorage.getItem(tokenStorageKey) || '';
    } catch {
      return '';
    }
  };
  const writeStoredToken = value => {
    if (typeof window === 'undefined') return;
    try {
      if (value) {
        window.sessionStorage.setItem(tokenStorageKey, value);
      } else {
        window.sessionStorage.removeItem(tokenStorageKey);
      }
    } catch {}
  };
  const [token, setToken] = useState(readStoredToken);
  const [argumentText, setArgumentText] = useState(formatJson(initialArguments));
  const [status, setStatus] = useState('Ready');
  const [response, setResponse] = useState('No response yet.');
  const [copied, setCopied] = useState(false);
  const callTool = async () => {
    if (!token.trim()) {
      setStatus('Paste a bearer token first.');
      return;
    }
    let parsedArguments;
    try {
      parsedArguments = argumentText.trim() ? JSON.parse(argumentText) : {};
    } catch {
      setStatus('Input must be valid JSON.');
      return;
    }
    const body = {
      jsonrpc: '2.0',
      id: Date.now(),
      method: 'tools/call',
      params: {
        name: tool,
        arguments: parsedArguments
      }
    };
    setStatus('Calling tool...');
    setResponse(formatJson(body));
    try {
      const result = await fetch(endpoint, {
        method: 'POST',
        headers: {
          accept: 'application/json, text/event-stream',
          'content-type': 'application/json',
          authorization: `Bearer ${token.trim()}`,
          'x-veryfront-origin': 'docs-mcp-tool-page'
        },
        body: JSON.stringify(body)
      });
      const text = await result.text();
      setStatus(result.ok ? 'Response received.' : `Request failed with HTTP ${result.status}.`);
      setResponse(formatResponseText(text));
    } catch (error) {
      setStatus('Request failed.');
      setResponse(error instanceof Error ? error.message : String(error));
    }
  };
  const copyResponse = async () => {
    try {
      await navigator.clipboard.writeText(response);
      setCopied(true);
      setTimeout(() => setCopied(false), 1500);
    } catch {
      setStatus('Copy failed.');
    }
  };
  return <div className="not-prose my-6 rounded-xl border border-gray-200 bg-white p-4 dark:border-gray-800 dark:bg-gray-950">
      <div className="mb-4">
        <div className="text-sm font-semibold text-gray-900 dark:text-gray-100">MCP tool call</div>
        <div className="mt-1 text-sm text-gray-600 dark:text-gray-400">
          Call <code>{tool}</code> against the Veryfront MCP endpoint.
        </div>
      </div>

      <label className="mb-2 block text-sm font-medium text-gray-900 dark:text-gray-100" htmlFor={`${tool}-token`}>
        Bearer token
      </label>
      <input id={`${tool}-token`} className="mb-4 w-full rounded-md border border-gray-300 bg-white px-3 py-2 text-sm text-gray-900 dark:border-gray-700 dark:bg-gray-900 dark:text-gray-100" type="password" value={token} onChange={event => {
    const value = event.target.value;
    setToken(value);
    writeStoredToken(value);
  }} placeholder="Paste API key or JWT" />

      <label className="mb-2 block text-sm font-medium text-gray-900 dark:text-gray-100" htmlFor={`${tool}-arguments`}>
        Input JSON
      </label>
      <textarea id={`${tool}-arguments`} className="mb-4 min-h-40 w-full rounded-md border border-gray-300 bg-white px-3 py-2 font-mono text-sm text-gray-900 dark:border-gray-700 dark:bg-gray-900 dark:text-gray-100" value={argumentText} onChange={event => setArgumentText(event.target.value)} spellCheck={false} />

      <button className="rounded-md bg-gray-900 px-3 py-2 text-sm font-medium text-white hover:bg-gray-700 dark:bg-gray-100 dark:text-gray-950 dark:hover:bg-gray-300" type="button" onClick={callTool}>
        Call tool
      </button>

      <div className="mt-4 text-sm font-medium text-gray-900 dark:text-gray-100">{status}</div>
      <div className="mt-3 overflow-hidden rounded-md border border-gray-300 dark:border-gray-700">
        <div className="flex items-center justify-between bg-gray-100 px-3 py-2 text-sm font-medium text-gray-900 dark:bg-gray-900 dark:text-gray-100">
          <span>Output JSON</span>
          <button className="rounded border border-gray-300 bg-white px-2 py-1 text-xs text-gray-900 hover:bg-gray-50 dark:border-gray-700 dark:bg-gray-950 dark:text-gray-100 dark:hover:bg-gray-800" type="button" onClick={copyResponse}>
            {copied ? 'Copied' : 'Copy'}
          </button>
        </div>
      <pre className="max-h-96 overflow-auto whitespace-pre-wrap break-words bg-gray-950 p-4 text-sm text-gray-100">
        <code dangerouslySetInnerHTML={{
    __html: highlightJson(response)
  }} />
      </pre>
      </div>
    </div>;
};

List durable agent runs for a conversation.

## Tool details

| Field | Value             |
| ----- | ----------------- |
| Name  | `list_agent_runs` |
| Group | Conversations     |

## Playground

<McpToolCall
  tool="list_agent_runs"
  initialArguments={{
"conversation_id": ""
}}
/>

## Input schema

```json title="Input schema" theme={null}
{
  "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

```json title="Output schema" theme={null}
{
  "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#"
}
```
