--- title: vercel agent-runs product: vercel url: /docs/cli/agent-runs canonical_url: "https://vercel.com/docs/cli/agent-runs" last_updated: 2018-10-20 type: reference prerequisites: - /docs/cli related: - /docs/eve/agent-runs - /docs/cli/link - /docs/cli/global-options - /docs/agent-resources/vercel-mcp/tools/agent-runs - /docs/cli/traces summary: Find projects with Agent Runs, list recent runs, and inspect run metadata and conversation traces from the command line. install_vercel_plugin: npx plugins add vercel/vercel-plugin --- # vercel agent-runs The `vercel agent-runs` command reads [Agent Runs](/docs/eve/agent-runs) data from your terminal. Use it to investigate an eve agent's lifecycle events, subagents, messages, reasoning, tool calls, and token usage. ## Usage Find projects with Agent Runs activity, then list and inspect runs for a project: ```bash filename="terminal" vercel agent-runs projects --scope my-team vercel agent-runs list --scope my-team --project my-app vercel agent-runs inspect run_1234567890 --scope my-team --project my-app vercel agent-runs trace run_1234567890 --scope my-team --project my-app ``` Replace `run_1234567890` with a run ID from the list response. The `list`, `inspect`, and `trace` commands use your [linked project](/docs/cli/link) unless you pass `--project`. The `projects` command works at the team level. From an unlinked directory, pass [`--scope`](/docs/cli/global-options#scope) for `projects`, and both `--scope` and `--project` for the other commands. When selecting a different team from a linked directory, pass both flags to select a project in that team. All four commands query the `production` environment by default. Use `--environment preview` for preview deployments. When inspecting a run from a filtered list, keep the same team, project, environment, and time window. ## Subcommands ### List projects `vercel agent-runs projects` finds projects in the selected team with Agent Runs activity: ```bash filename="terminal" vercel agent-runs projects --scope my-team --since 7d vercel agent-runs projects --environment preview --json ``` ### List runs `vercel agent-runs list` (alias `ls`) lists runs for a project. Filter by time or title, and limit the number of results per page: ```bash filename="terminal" vercel agent-runs list --environment preview --since 1d vercel agent-runs list --query "checkout" --limit 20 vercel agent-runs list --project my-app --json ``` | Option | Description | | --- | --- | | `--query `, `-q` | Search runs by title. `--search` is a deprecated alias. | | `--limit `, `-n` | Number of runs per page, up to 100. | | `--next ` | Continue a list using the cursor from the previous response. | To continue a list, use the next-page command printed by the CLI. Cursor-based JSON responses expose the next cursor in `pagination.next`. Keep the same team, project, environment, and query. The cursor preserves the time window, so omit `--since` and `--until` when continuing: ```bash filename="terminal" vercel agent-runs list --project my-app --next "$NEXT_CURSOR" --json ``` Set `NEXT_CURSOR` to the cursor from the previous response. A page can contain no runs and still provide a next cursor. Continue while a cursor is available, and start without `--next` if it is invalid or expired. If the CLI prints a numeric next-page value instead, use its complete suggested command, including the time filters. ### Inspect a run `vercel agent-runs inspect ` retrieves a run's metadata, lifecycle events, usage, and subagent data: ```bash filename="terminal" vercel agent-runs inspect run_1234567890 vercel agent-runs inspect run_1234567890 --environment preview --json ``` ### Read a trace `vercel agent-runs trace ` retrieves the conversation trace, including turns, messages, reasoning, tool calls, token usage, and tool inputs and outputs: ```bash filename="terminal" vercel agent-runs trace run_1234567890 vercel agent-runs trace run_1234567890 --json --max-field-length 0 ``` | Option | Description | | --- | --- | | `--max-field-length ` | Limit individual string fields before formatting. Defaults to 8000; positive values are capped at 50,000. Use `--json --max-field-length 0` to output fields without CLI truncation. | | `--next ` | Fetch newer trace activity using a cursor from a previous response. | | `--previous ` | Fetch older trace activity using a cursor from a previous response. | Markdown output separately shortens displayed messages, reasoning, and tool inputs and outputs to 2,000 characters, even with `--max-field-length 0`. Use `--json` to retain fields omitted from the Markdown view, such as per-turn token usage, and combine it with `--max-field-length 0` for untruncated field values. This doesn't combine trace pages or restore content the service didn't return. You can't combine `--next` and `--previous`. Use the continuation commands printed by the CLI, or the `pagination.next` and `pagination.previous` cursors in JSON output. Keep the same run, team, project, environment, and time window: ```bash filename="terminal" vercel agent-runs trace run_1234567890 --next "$NEXT_CURSOR" --json vercel agent-runs trace run_1234567890 --previous "$PREVIOUS_CURSOR" --json ``` Set each variable to the corresponding cursor from the previous response. A trace page may contain only part of a conversation. Follow available cursors before treating the response as the complete run. ## Shared options These options apply to all four subcommands unless noted: | Option | Description | | --- | --- | | `--environment `, `-e` | Query `production` or `preview`. Defaults to `production`. | | `--since