Retrieve Traces via CLI

Phoenix CLI (@arizeai/phoenix-cli) is a command-line interface tool for retrieving trace data from your Phoenix projects. It allows you to use Phoenix’s tracing and debugging features directly in your terminal and development workflows. You can use Phoenix CLI for the following use cases:

Immediate debugging: Fetch the most recent trace of a failed or unexpected run with a single command.
Bulk export for analysis: Export large numbers of traces to JSON files for offline analysis, building evaluation datasets, or regression tests.
Terminal-based workflows: Integrate trace data into your existing tools; for example, piping output to Unix utilities like jq, or feeding traces into an AI coding assistant for automated analysis.
AI coding assistant integration: Use with Claude Code, Cursor, Windsurf, or other AI-powered development tools to analyze and debug your LLM application traces.

Installation

npm install -g @arizeai/phoenix-cli

Or run directly without installation:

npx @arizeai/phoenix-cli

Setup

1. Set your Phoenix endpoint

export PHOENIX_HOST=http://localhost:6006

For Phoenix Cloud:

export PHOENIX_HOST=https://app.phoenix.arize.com

2. Set your project name

export PHOENIX_PROJECT=your-project-name

The CLI will automatically fetch traces from PHOENIX_PROJECT. Replace your-project-name with the name of your Phoenix project.

3. Set your API key (if required)

export PHOENIX_API_KEY=your-api-key

If you’re using Phoenix Cloud or a Phoenix instance with authentication enabled, you’ll need to set the PHOENIX_API_KEY environment variable or use the --api-key flag.

Use with AI Coding Assistants

Phoenix CLI is designed to work seamlessly with AI coding assistants like Claude Code, Cursor, Windsurf, and other AI-powered development tools.

Claude Code

After setting up the CLI, ask Claude Code questions like:

Use px to fetch the last 3 traces from my Phoenix project and analyze them for potential improvements

Run px trace list --limit 5 --format raw and identify any errors or slow spans in my agent workflow

Claude Code will use the px --help command to discover the CLI capabilities and fetch your traces for analysis.

Cursor / Windsurf

In Cursor or Windsurf, you can:

Run px trace list --limit 1 --format json in the terminal
Select the output and ask the AI to analyze it
Or ask the AI directly to run the command and interpret results

Example prompts:

Fetch my recent Phoenix traces using px and explain what my agent is doing

Use the Phoenix CLI to get the last failed trace and help me debug it

Find Project and Trace IDs

In most cases, you won’t need to find IDs manually (the CLI uses your environment’s project name and latest traces by default). However, if you want to fetch a specific item by ID, you can find the IDs in the Phoenix UI:

Project Name/ID: Each project has a unique name and ID. You can find it in the project selector dropdown or in the project’s URL.
Trace ID: Every trace has an ID. In the traces view, click on a specific trace to see its Trace ID (copyable from the trace details panel). You can use px trace get <trace-id> to retrieve that exact trace.

Usage

After installation and setup, you can use the px command to retrieve traces. The general usage is:

px <resource> <action> [ARGUMENTS] [OPTIONS]

Phoenix CLI provides the following commands:

Command	Fetches	Output location
`project list`	List of all projects	stdout
`trace get <id>`	A specific trace by ID	stdout (or to a file with `--file`)
`trace list [directory]`	Recent traces from the project	Saves each trace as a JSON file in the given directory, or prints to stdout if no directory is provided
`session list`	List sessions for a project	stdout
`session get <id>`	A specific session with its traces	stdout (or to a file with `--file`)

Traces are fetched chronologically with most recent first.

Options

The commands support additional flags to filter and format the output:

Option / Flag	Applies to	Description	Default
`-n, --limit <int>`	`trace list`	Maximum number of traces to fetch	10
`--last-n-minutes <int>`	`trace list`	Only fetch traces from the last N minutes	No filter
`--since <timestamp>`	`trace list`	Only fetch traces since a specific time (ISO 8601 format)	No filter
`--project <name>`	`trace get`, `trace list`	Override the configured project	From env
`--format <type>`	All commands	Output format: `pretty`, `json`, or `raw`	`pretty`
`--file <path>`	`trace get`	Save the fetched trace to a file instead of printing	stdout
`--max-concurrent <int>`	`trace list`	Maximum concurrent fetch requests	10
`--no-progress`	All commands	Disable progress bar output (useful for scripts and AI assistants)	Progress on
`--include-annotations`	`trace get`, `trace list`	Include span annotations in trace export	Off

Output formats

The --format option controls how the fetched data is displayed:

pretty (default): A human-readable tree view showing span hierarchy, status, and timing. Great for quick debugging:

┌─ Trace: abc123def456
│
│  Input: What is the weather in San Francisco?
│  Output: The weather is currently sunny...
│
│  Spans:
│  └─ ✓ agent_run (CHAIN) - 1250ms
│     ├─ ✓ llm_call (LLM) - 800ms
│     └─ ✓ tool_execution (TOOL) - 400ms
└─

json: Well-formatted JSON output with indentation. Use this if you want to examine the data structure:
px trace get <trace-id> --format json

raw: Compact JSON with no extra whitespace. Ideal for piping to jq or other tools:

px trace get <trace-id> --format raw | jq '.spans[] | select(.span_kind == "LLM")'

Fetch a Single Trace

You can fetch a single trace with its ID. The command will output to the terminal by default:

px trace get <trace-id>

You can optionally save the trace to a file using the --file option:

px trace get <trace-id> --file ./my-trace.json

To include span annotations in the trace export:

px trace get <trace-id> --include-annotations --format json

To fetch a trace from a different project than the one configured:

px trace get <trace-id> --project different-project

Fetch Multiple Traces

For bulk fetches of traces, we recommend specifying a target directory path. Each fetched trace will be saved as a separate JSON file in that folder, making it easy to browse or process them later.

You can specify a destination directory for bulk exports. For example, the following command will save the 10 most recent traces as JSON files in the my-traces-data directory:

px trace list ./my-traces-data --limit 10

Include span annotations in the export:

px trace list ./my-traces-data --limit 10 --include-annotations

If you omit the directory, the tool will output the results to your terminal:

px trace list --limit 10

When saving to a directory, files will be named by trace ID (e.g., 3b0b15fe-1e3a-4aef-afa8-48df15879cfe.json).

Filter by time

Fetch traces from a specific time range:

# Traces from the last 30 minutes
px trace list ./my-traces --limit 50 --last-n-minutes 30

# Traces since a specific time
px trace list ./my-traces --since 2026-01-15T00:00:00Z

Export to Files

You can fetch traces and export them for offline analysis or building datasets:

px trace list ./exported-traces --since 2026-01-01T00:00:00Z --limit 100

This command retrieves traces that occurred since January 1, 2026, saving each as a JSON file under ./exported-traces. This is useful for:

Building regression test datasets
Offline analysis and debugging
Creating evaluation datasets for experiments

Sessions

Sessions group multiple traces into a single multi-turn conversation. Use the session list and session get commands to explore them.

List Sessions

px session list --limit 10
px session list --format raw --no-progress | jq '.[].session_id'

View a Session

px session get my-chat-session-001
px session get my-chat-session-001 --include-annotations
px session get my-chat-session-001 --format raw | jq '.traces[].trace_id'

To drill into a specific turn’s input/output, use px trace get <trace-id> with the trace ID from the session output.

Trace Output Structure

When using json or raw format, traces are output with the following structure:

{
  "traceId": "abc123def456",
  "spans": [
    {
      "name": "chat_completion",
      "context": {
        "trace_id": "abc123def456",
        "span_id": "span-1"
      },
      "span_kind": "LLM",
      "parent_id": null,
      "start_time": "2026-01-17T10:00:00.000Z",
      "end_time": "2026-01-17T10:00:01.250Z",
      "status_code": "OK",
      "attributes": {
        "llm.model_name": "gpt-4",
        "llm.token_count.prompt": 512,
        "llm.token_count.completion": 256,
        "input.value": "What is the weather?",
        "output.value": "The weather is sunny..."
      },
      "annotations": [
        {
          "span_id": "span-1",
          "name": "quality_score",
          "annotator_kind": "LLM",
          "result": {
            "label": "good",
            "score": 0.95
          }
        }
      ]
    }
  ],
  "rootSpan": { ... },
  "startTime": "2026-01-17T10:00:00.000Z",
  "endTime": "2026-01-17T10:00:01.250Z",
  "duration": 1250,
  "status": "OK"
}

OpenInference Semantic Attributes

Each span includes OpenInference semantic attributes in the attributes field:

LLM spans: llm.model_name, llm.token_count.prompt, llm.token_count.completion, llm.invocation_parameters
Input/Output: input.value, output.value, input.mime_type, output.mime_type
Tool calls: tool.name, tool.description, tool.parameters
Retrieval: retrieval.documents
Errors: exception.type, exception.message, exception.stacktrace

AI Coding Assistant Examples

Debug a Failed Agent Run

# Fetch recent traces and find errors
px trace list --limit 20 --format raw --no-progress | jq '.[] | select(.status == "ERROR")'

Then ask your AI assistant:

Here's a failed trace from my agent. Can you identify what went wrong and suggest a fix?

Analyze Agent Performance

# Get traces sorted by duration
px trace list --limit 10 --format raw --no-progress | jq 'sort_by(-.duration) | .[0:3]'

Ask your AI assistant:

Analyze these slow traces and suggest optimizations for my agent workflow

Review Token Usage

# Extract LLM spans with token counts
px trace list --limit 50 --format raw --no-progress | \
  jq '[.[].spans[] | select(.span_kind == "LLM") | {name, model: .attributes["llm.model_name"], tokens: .attributes["llm.token_count.total"]}]'

Pipeline Examples

The CLI is designed to work seamlessly in shell pipelines:

# Count traces with errors
px trace list --limit 100 --format raw --no-progress | \
  jq '[.[] | select(.status == "ERROR")] | length'

# Extract all LLM models used
px trace list --limit 50 --format raw --no-progress | \
  jq -r '.[].spans[] | select(.span_kind == "LLM") | .attributes["llm.model_name"] // empty' | \
  sort -u

# Get total duration across traces
px trace list --limit 100 --format raw --no-progress | \
  jq '[.[].duration // 0] | add'

Troubleshooting

”Phoenix endpoint not configured”

Set the PHOENIX_HOST environment variable:

export PHOENIX_HOST=http://localhost:6006

Or use the --endpoint flag:

px trace list --endpoint http://localhost:6006 --limit 10

“Project not configured”

Set the PHOENIX_PROJECT environment variable:

export PHOENIX_PROJECT=my-project

Or use the --project flag:

px trace list --project my-project --limit 10

“Failed to resolve project”

Make sure your project name or ID is correct. List available projects:

px project list

CLI Reference

Full CLI reference documentation

Export Data & Query Spans

Learn how to export trace data using the Phoenix client

​Installation

​Setup

​1. Set your Phoenix endpoint

​2. Set your project name

​3. Set your API key (if required)

​Use with AI Coding Assistants

​Claude Code

​Cursor / Windsurf

​Find Project and Trace IDs

​Usage

​Options

​Output formats

​Fetch a Single Trace

​Fetch Multiple Traces

​Filter by time

​Export to Files

​Sessions

​List Sessions

​View a Session

​Trace Output Structure

​OpenInference Semantic Attributes

​AI Coding Assistant Examples

​Debug a Failed Agent Run

​Analyze Agent Performance

​Review Token Usage

​Pipeline Examples

​Troubleshooting

​”Phoenix endpoint not configured”

​“Project not configured”

​“Failed to resolve project”

​Related

CLI Reference

Export Data & Query Spans

Installation

Setup

1. Set your Phoenix endpoint

2. Set your project name

3. Set your API key (if required)

Use with AI Coding Assistants

Claude Code

Cursor / Windsurf

Find Project and Trace IDs

Usage

Options

Output formats

Fetch a Single Trace

Fetch Multiple Traces

Filter by time

Export to Files

Sessions

List Sessions

View a Session

Trace Output Structure

OpenInference Semantic Attributes

AI Coding Assistant Examples

Debug a Failed Agent Run

Analyze Agent Performance

Review Token Usage

Pipeline Examples

Troubleshooting

”Phoenix endpoint not configured”

“Project not configured”

“Failed to resolve project”

Related