Traces

The traces module provides trace retrieval, project transfer, and trace-level annotation functions.

Retrieve Traces#

Use getTraces when you want trace-centric pagination by project, optional inline spans, or filtering by session, error status, or latency.

import { getTraces } from "@arizeai/phoenix-client/traces";const result = await getTraces({  project: { projectName: "support-bot" },  startTime: new Date("2026-03-01T00:00:00Z"),  endTime: new Date("2026-03-02T00:00:00Z"),  includeSpans: true,  limit: 50,});for (const trace of result.traces) {  console.log(trace.trace_id);}console.log(result.nextCursor);

Supported Filters#

• project
• startTime
• endTime
• sort
• order
• limit
• cursor
• includeSpans
• sessionId
• filter — a trace DSL expression, combined with other filters using AND
• error (deprecated; use filter)
• minLatencyMs (deprecated; use filter)
• maxLatencyMs (deprecated; use filter)

// Slow traces that contain at least one errored spanconst slowFailures = await getTraces({  project: { projectName: "support-bot" },  filter: "error_count > 0 and latency_ms >= 1000",});

Notes#

• getTraces requires a Phoenix server that supports project trace listing
• Use the returned nextCursor to continue pagination
• Set includeSpans when you need a trace-centric fetch that also contains span details
• project accepts { project }, { projectId }, or { projectName }
• filter takes a trace filter expression; the language is documented on the Filter Expressions page, and its Finding field names section covers discovering valid names for your project.
• error, minLatencyMs, and maxLatencyMs remain supported on Phoenix server >= 20.8.0. Replace them with error_count > 0 / error_count == 0, latency_ms >= N, and latency_ms <= N respectively. Latency bounds are inclusive and errors include child spans.

Move Traces To Another Project#

Use transferTraces to move one or more traces from their current project to a destination project. This operation moves rather than copies the traces: after a successful transfer, they no longer appear in the source project.

All traces in one call must currently belong to the same source project. Each trace identifier can be either an OpenTelemetry trace ID or a Phoenix trace GlobalID, and the destination can be either a project name or project GlobalID.

import { transferTraces } from "@arizeai/phoenix-client/traces";const result = await transferTraces({  traceIdentifiers: ["8f3a...", "VHJhY2U6Mg=="],  destinationProjectIdentifier: "production",});console.log(`Moved ${result.transferredTraceCount} traces`);console.log(`Destination project: ${result.destinationProjectId}`);

The result contains the number of distinct traces moved and the resolved GlobalID of the destination project. Phoenix rejects an empty list, trace or project identifiers that do not resolve, and requests that combine traces from multiple source projects.

transferTraces requires Phoenix server 20.4.0 or newer.

Annotate a Single Trace#

Use addTraceAnnotation to attach a label, score, or explanation to one trace. If you supply an identifier, Phoenix upserts the annotation when an annotation with that identifier already exists.

import { addTraceAnnotation } from "@arizeai/phoenix-client/traces";const result = await addTraceAnnotation({  traceAnnotation: {    traceId: "abc123",    name: "correctness",    label: "correct",    score: 1.0,    annotatorKind: "HUMAN",  },});// result is { id: string } when sync: true, or null when sync: false (default)

Set sync: true to receive the annotation ID immediately; omit it (or pass false) for higher-throughput async writes.

TraceAnnotation Fields#

Annotate Multiple Traces#

Use logTraceAnnotations to batch-write annotations across many traces in a single request.

import { logTraceAnnotations } from "@arizeai/phoenix-client/traces";const results = await logTraceAnnotations({  traceAnnotations: [    { traceId: "abc123", name: "faithfulness", score: 0.9, annotatorKind: "LLM" },    { traceId: "def456", name: "faithfulness", score: 0.7, annotatorKind: "LLM" },  ],  sync: true,});for (const r of results) {  console.log(r.id);}

logTraceAnnotations sends all annotations in a single POST and returns an array of { id: string } objects (or an empty array when sync: false).