ax spans export PROJECT --trace-id TRACE_ID --output-dir .arize-tmp-traces

ax spans export PROJECT --span-id SPAN_ID --output-dir .arize-tmp-traces

ax spans export PROJECT --session-id SESSION_ID --output-dir .arize-tmp-traces

ax spans export PROJECT --trace-id TRACE_ID --output-dir .arize-tmp-traces

ax spans export PROJECT --space SPACE --filter "status_code = 'ERROR'" --all --output-dir .arize-tmp-traces

Do you have a --trace-id, --span-id, or --session-id?
├─ YES: count is bounded → omit --all. If result is exactly 500, re-run with --all.
└─ NO (exploratory export):
 ├─ Just browsing a sample? → use -l 50
 └─ Need all matching spans?
 ├─ Expected **Check span count first:** Before a large exploratory export, check how many spans match your filter:

 **Requirements for `--all`:**

 

- `--space` is required (Flight uses space + project name) 

- `--limit` is ignored when `--all` is set 

 **Networking notes for `--all`:**
Arrow Flight connects to `flight.arize.com:443` via gRPC+TLS -- this is a different host from the REST API (`api.arize.com`). On internal or private networks, the Flight endpoint may use a different host/port. Configure via:

 

- ax profile: `flight_host`, `flight_port`, `flight_scheme` 

- Environment variables: `ARIZE_FLIGHT_HOST`, `ARIZE_FLIGHT_PORT`, `ARIZE_FLIGHT_SCHEME` 

 **Internal/private deployment note:** On internal Arize deployments, Arrow Flight may fail with auth errors even with a valid API key (the Flight endpoint may have additional network or auth restrictions). If `--all` fails, fall back to REST with batched time windows: loop over `--start-time`/`--end-time` ranges (e.g., day by day) using `-l 500` per batch.

 The `--all` flag is also available on `ax traces export`, `ax datasets export`, and `ax experiments export` with the same behavior (REST by default, Flight with `--all`).

## Export Traces: `ax traces export`

Export full traces -- all spans belonging to traces that match a filter. Uses a two-phase approach:

 

- **Phase 1:** Find spans matching `--filter` (up to `--limit` via REST, or all via Flight with `--all`) 

- **Phase 2:** Extract unique trace IDs, then fetch every span for those traces 

### Flags

 Flag Type Default Description 
 `PROJECT` string required Project name or base64 ID (positional arg) 
 `--filter` string none Filter expression for phase-1 span lookup 
 `--space` string none Space name or ID; required when `PROJECT` is a name or when using `--all` (Arrow Flight) 
 `--limit, -l` int 50 Max number of traces to export 
 `--days` int 30 Lookback window in days 
 `--start-time` string none Override start (ISO 8601) 
 `--end-time` string none Override end (ISO 8601) 
 `--output-dir` string `.` Output directory 
 `--stdout` bool false Print JSON to stdout instead of file 
 `--all` bool false Use Arrow Flight for both phases (see spans `--all` docs above) 
 `-p, --profile` string default Configuration profile 
 

### How it differs from `ax spans export`

 

- `ax spans export` exports individual spans matching a filter 

- `ax traces export` exports complete traces -- it finds spans matching the filter, then pulls ALL spans for those traces (including siblings and children that may not match the filter) 

### Time-series index lag

 Arize uses two storage tiers:

 

- **Primary trace store** (indexed by `trace_id`) — spans are written here immediately on ingestion. `--trace-id` direct lookups (`ax spans export PROJECT_ID --trace-id TRACE_ID`) hit this store and are always up to date. 

- **Time-series query index** (used by `--days`, `--start-time`, `--end-time`) — built asynchronously from the primary store and lags **6–12 hours**. Queries scoped by time range will miss very recent traces. 

 **Implication:** If you already have a `trace_id`, use `ax spans export PROJECT_ID --trace-id TRACE_ID` — it's faster and immediately consistent. Use time-range queries only for historical exploration, and set `--start-time` at least 12 hours in the past to guarantee results are indexed.

## Filter Syntax Reference

SQL-like expressions passed to `--filter`.

### Common filterable columns

 Column Type Description Example Values 
 `name` string Span name `'ChatCompletion'`, `'retrieve_docs'` 
 `status_code` string Status `'OK'`, `'ERROR'`, `'UNSET'` 
 `latency_ms` number Duration in ms `100`, `5000` 
 `parent_id` string Parent span ID null for root spans 
 `context.trace_id` string Trace ID 
 `context.span_id` string Span ID 
 `attributes.session.id` string Session ID 
 `attributes.openinference.span.kind` string Span kind `'LLM'`, `'CHAIN'`, `'TOOL'`, `'AGENT'`, `'RETRIEVER'`, `'RERANKER'`, `'EMBEDDING'`, `'GUARDRAIL'`, `'EVALUATOR'` 
 `attributes.llm.model_name` string LLM model `'gpt-4o'`, `'claude-3'` 
 `attributes.input.value` string Span input 
 `attributes.output.value` string Span output 
 `attributes.error.type` string Error type `'ValueError'`, `'TimeoutError'` 
 `attributes.error.message` string Error message 
 `event.attributes` string Error tracebacks Use CONTAINS (not exact match) 
 

### Operators

 `=`, `!=`, `<`, `<=`, `>`, `>=`, `AND`, `OR`, `IN`, `CONTAINS`, `LIKE`, `IS NULL`, `IS NOT NULL`

### Examples

### Tips

 

- Prefer `IN` over multiple `OR` conditions: `name IN ('a', 'b', 'c')` not `name = 'a' OR name = 'b' OR name = 'c'` 

- Start broad with `LIKE`, then switch to `=` or `IN` once you know exact values 

- Use `CONTAINS` for `event.attributes` (error tracebacks) -- exact match is unreliable on complex text 

- Always wrap string values in single quotes

## Workflows

### Debug a failing trace

 

- `ax traces export PROJECT --filter "status_code = 'ERROR'" -l 50 --output-dir .arize-tmp-traces` 

- Read the output file, look for spans with `status_code: ERROR` 

- Check `attributes.error.type` and `attributes.error.message` on error spans 

### Download a conversation session

 

- `ax spans export PROJECT --session-id SESSION_ID --output-dir .arize-tmp-traces` 

- Spans are ordered by `start_time`, grouped by `context.trace_id` 

- If you only have a trace_id, export that trace first, then look for `attributes.session.id` in the output to get the session ID 

### Export for offline analysis

## Span Column Reference (OpenInference Semantic Conventions)

### Core Identity and Timing

 Column Description 
 `name` Span operation name (e.g., `ChatCompletion`, `retrieve_docs`) 
 `context.trace_id` Trace ID -- all spans in a trace share this 
 `context.span_id` Unique span ID 
 `parent_id` Parent span ID. `null` for root spans (= traces) 
 `start_time` When the span started (ISO 8601) 
 `end_time` When the span ended 
 `latency_ms` Duration in milliseconds 
 `status_code` `OK`, `ERROR`, `UNSET` 
 `status_message` Optional message (usually set on errors) 
 `attributes.openinference.span.kind` `LLM`, `CHAIN`, `TOOL`, `AGENT`, `RETRIEVER`, `RERANKER`, `EMBEDDING`, `GUARDRAIL`, `EVALUATOR` 
 

### Where to Find Prompts and LLM I/O

 **Generic input/output (all span kinds):**

 Column What it contains 
 `attributes.input.value` The input to the operation. For LLM spans, often the full prompt or serialized messages JSON. For chain/agent spans, the user's question. 
 `attributes.input.mime_type` Format hint: `text/plain` or `application/json` 
 `attributes.output.value` The output. For LLM spans, the model's response. For chain/agent spans, the final answer. 
 `attributes.output.mime_type` Format hint for output 
 

 **LLM-specific message arrays (structured chat format):**

 Column What it contains 
 `attributes.llm.input_messages` Structured input messages array (system, user, assistant, tool). **Where chat prompts live** in role-based format. 
 `attributes.llm.input_messages.roles` Array of roles: `system`, `user`, `assistant`, `tool` 
 `attributes.llm.input_messages.contents` Array of message content strings 
 `attributes.llm.output_messages` Structured output messages from the model 
 `attributes.llm.output_messages.contents` Model response content 
 `attributes.llm.output_messages.tool_calls.function.names` Tool calls the model wants to make 
 `attributes.llm.output_messages.tool_calls.function.arguments` Arguments for those tool calls 
 

 **Prompt templates:**

 Column What it contains 
 `attributes.llm.prompt_template.template` The prompt template with variable placeholders (e.g., `"Answer {question} using {context}"`) 
 `attributes.llm.prompt_template.variables` Template variable values (JSON object) 
 

 **Finding prompts by span kind:**

 

- **LLM span**: Check `attributes.llm.input_messages` for structured chat messages, OR `attributes.input.value` for serialized prompt. Check `attributes.llm.prompt_template.template` for the template. 

- **Chain/Agent span**: Check `attributes.input.value` for the user's question. Actual LLM prompts are on child LLM spans. 

- **Tool span**: Check `attributes.input.value` for tool input, `attributes.output.value` for tool result. 

### LLM Model and Cost

 Column Description 
 `attributes.llm.model_name` Model identifier (e.g., `gpt-4o`, `claude-3-opus-20240229`) 
 `attributes.llm.invocation_parameters` Model parameters JSON (temperature, max_tokens, top_p, etc.) 
 `attributes.llm.token_count.prompt` Input token count 
 `attributes.llm.token_count.completion` Output token count 
 `attributes.llm.token_count.total` Total tokens 
 `attributes.llm.cost.prompt` Input cost in USD 
 `attributes.llm.cost.completion` Output cost in USD 
 `attributes.llm.cost.total` Total cost in USD 
 

### Tool Spans

 Column Description 
 `attributes.tool.name` Tool/function name 
 `attributes.tool.description` Tool description 
 `attributes.tool.parameters` Tool parameter schema (JSON) 
 

### Retriever Spans

 Column Description 
 `attributes.retrieval.documents` Retrieved documents array 
 `attributes.retrieval.documents.ids` Document IDs 
 `attributes.retrieval.documents.scores` Relevance scores 
 `attributes.retrieval.documents.contents` Document text content 
 `attributes.retrieval.documents.metadatas` Document metadata 
 

### Reranker Spans

 Column Description 
 `attributes.reranker.query` The query being reranked 
 `attributes.reranker.model_name` Reranker model 
 `attributes.reranker.top_k` Number of results 
 `attributes.reranker.input_documents.*` Input documents (ids, scores, contents, metadatas) 
 `attributes.reranker.output_documents.*` Reranked output documents 
 

### Session, User, and Custom Metadata

 Column Description 
 `attributes.session.id` Session/conversation ID -- groups traces into multi-turn sessions 
 `attributes.user.id` End-user identifier 
 `attributes.metadata.*` Custom key-value metadata. Any key under this prefix is user-defined (e.g., `attributes.metadata.user_email`). Filterable. 
 

### Errors and Exceptions

 Column Description 
 `attributes.exception.type` Exception class name (e.g., `ValueError`, `TimeoutError`) 
 `attributes.exception.message` Exception message text 
 `event.attributes` Error tracebacks and detailed event data. Use `CONTAINS` for filtering. 
 

### Evaluations and Annotations

 Column Description 
 `annotation.<name>.label` Human or auto-eval label (e.g., `correct`, `incorrect`) 
 `annotation.<name>.score` Numeric score (e.g., `0.95`) 
 `annotation.<name>.text` Freeform annotation text 
 

### Embeddings

 Column Description 
 `attributes.embedding.model_name` Embedding model name 
 `attributes.embedding.texts` Text chunks that were embedded

## Related Skills

- **arize-dataset**: After collecting trace data, create labeled datasets for evaluation → use `arize-dataset` 

- **arize-experiment**: Run experiments comparing prompt versions against a dataset → use `arize-experiment` 

- **arize-prompt-optimization**: Use trace data to improve prompts → use `arize-prompt-optimization` 

- **arize-link**: Turn trace IDs from exported data into clickable Arize UI URLs → use `arize-link`

## Save Credentials for Future Use

See references/ax-profiles.md § Save Credentials for Future Use.