Skip to main content

Documentation Index

Fetch the complete documentation index at: https://arizeai-433a7140.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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

FieldTypeRequiredDescription
traceIdstringYesOpenTelemetry Trace ID (hex, no 0x prefix)
namestringYesWhat is being measured (e.g. "groundedness"). The name "note" is reserved — use addTraceNote instead.
annotatorKind"HUMAN" | "LLM" | "CODE"NoDefaults to "HUMAN"
labelstringAt least one of label/score/explanationCategorical result (e.g. "correct")
scorenumberAt least one of label/score/explanationNumeric result (e.g. 0.95)
explanationstringAt least one of label/score/explanationFree-text justification
identifierstringNoStable ID for idempotent upserts
metadataRecord<string, unknown>NoArbitrary 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