Traces

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

Python

TypeScript

Rest API

OpenInference SDK

Relevant Source Files

Retrieve Traces

Supported Filters

Notes

Annotate a Single Trace

TraceAnnotation Fields

Annotate Multiple Traces

Source Map

​Relevant Source Files

​Retrieve Traces

​Supported Filters

​Notes

​Annotate a Single Trace

​TraceAnnotation Fields

​Annotate Multiple Traces

​Source Map

Relevant Source Files

Retrieve Traces

Supported Filters

Notes

Annotate a Single Trace

TraceAnnotation Fields

Annotate Multiple Traces

Source Map