Traces

The traces module provides trace retrieval, project transfer, 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/transferTraces.ts for moving traces between projects
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 }

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

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/transferTraces.ts
src/traces/types.ts
src/types/projects.ts

Python

TypeScript

Rest API

OpenInference SDK

Relevant Source Files

Retrieve Traces

Supported Filters

Notes

Move Traces To Another Project

Annotate a Single Trace

TraceAnnotation Fields

Annotate Multiple Traces

Source Map

​Relevant Source Files

​Retrieve Traces

​Supported Filters

​Notes

​Move Traces To Another Project

​Annotate a Single Trace

​TraceAnnotation Fields

​Annotate Multiple Traces

​Source Map

Relevant Source Files

Retrieve Traces

Supported Filters

Notes

Move Traces To Another Project

Annotate a Single Trace

TraceAnnotation Fields

Annotate Multiple Traces

Source Map