vercel agent-runs

The vercel agent-runs command reads Agent Runs data from your terminal. Use it to investigate an eve agent's lifecycle events, subagents, messages, reasoning, tool calls, and token usage.

Find projects with Agent Runs activity, then list and inspect runs for a project:

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 unless you pass --project. The projects command works at the team level. From an unlinked directory, pass --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.

vercel agent-runs projects finds projects in the selected team with Agent Runs activity:

vercel agent-runs projects --scope my-team --since 7d
vercel agent-runs projects --environment preview --json

vercel agent-runs list (alias ls) lists runs for a project. Filter by time or title, and limit the number of results per page:

vercel agent-runs list --environment preview --since 1d
vercel agent-runs list --query "checkout" --limit 20
vercel agent-runs list --project my-app --json

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:

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.

vercel agent-runs inspect <runId> retrieves a run's metadata, lifecycle events, usage, and subagent data:

vercel agent-runs inspect run_1234567890
vercel agent-runs inspect run_1234567890 --environment preview --json

vercel agent-runs trace <runId> retrieves the conversation trace, including turns, messages, reasoning, tool calls, token usage, and tool inputs and outputs:

vercel agent-runs trace run_1234567890
vercel agent-runs trace run_1234567890 --json --max-field-length 0

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:

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.

These options apply to all four subcommands unless noted:

For example, list runs from a specific time window:

vercel agent-runs list --since 7d --until 1d

Every subcommand supports --json. Without --json, the CLI renders recognized conversation turns as Markdown, including when you pipe or redirect output. If it can't find turns to render, it prints the response as JSON instead. This lets a coding agent inspect traces through shell commands without an MCP connection:

vercel agent-runs list --json
vercel agent-runs trace run_1234567890 > agent-run.md
vercel agent-runs trace run_1234567890 --json --max-field-length 0 > agent-run.json

The trace contains only the content Agent Runs collected. Review trace sampling and trace content settings if expected activity or fields are missing.

The following global options can be passed when using the vercel agent-runs command:

• --cwd
• --debug
• --global-config
• --help
• --local-config
• --no-color
• --non-interactive
• --scope
• --team
• --token
• --version

For more information on global options and their usage, refer to the options section.

• Agent Runs
• Agent Runs tools in Edgenivo MCP
• vercel traces