Traces

Retrieve traces and annotate them with @arizeai/phoenix-client

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

Relevant Source Files

• src/traces/getTraces.ts for the exact query shape and server requirement

• src/traces/addTraceAnnotation.ts for single annotation writes

• src/traces/logTraceAnnotations.ts for batched annotation writes

• src/traces/types.ts for the TraceAnnotation type

Retrieve Traces

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

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

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 }

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

Field	Type	Required	Description
traceId	string	Yes	OpenTelemetry Trace ID (hex, no 0x prefix)
name	string	Yes	What is being measured (e.g. "groundedness"). The name "note" is reserved — use addTraceNote instead.
annotatorKind	"HUMAN" | "LLM" | "CODE"	No	Defaults to "HUMAN"
label	string	At least one of label/score/explanation	Categorical result (e.g. "correct")
score	number	At least one of label/score/explanation	Numeric result (e.g. 0.95)
explanation	string	At least one of label/score/explanation	Free-text justification
identifier	string	No	Stable ID for idempotent upserts
metadata	Record<string, unknown>	No	Arbitrary context

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).

Source Map

• src/traces/getTraces.ts
• src/traces/addTraceAnnotation.ts
• src/traces/logTraceAnnotations.ts
• src/traces/types.ts
• src/types/projects.ts