Spans

Use the spans module to search project spans and perform span-level maintenance such as deleting spans or adding notes.

Search Spans#

import { getSpans } from "@arizeai/phoenix-client/spans";const result = await getSpans({  project: { projectName: "support-bot" },  limit: 100,  spanKind: ["LLM", "TOOL"],  statusCode: "ERROR",});for (const span of result.spans) {  console.log(span.name, span.context.trace_id);}

Filtering by Attributes#

Use the attributes parameter to filter spans by OpenInference attribute key-value pairs. Multiple entries are ANDed together. The JS type of the value determines how the stored attribute is matched: a number matches a stored integer or float, a boolean matches a stored boolean, and a string matches a stored string.

// Spans from a specific modelconst result = await getSpans({  project: { projectName: "support-bot" },  attributes: { "llm.model_name": "gpt-4o" },});// Spans for a session and a specific user (AND semantics)const result = await getSpans({  project: { projectName: "support-bot" },  attributes: {    "session.id": "sess-abc123",    "user.id": "user-42",  },});

Non-finite number values (Infinity, NaN) throw a RangeError. Requires Phoenix server ≥ 14.9.0.

Root Span Queries#

Use parentId: null to limit results to root spans only.

const rootSpans = await getSpans({  project: { projectName: "support-bot" },  parentId: null,});

Span Maintenance#

Adding Notes#

Use addSpanNote to attach a free-text note to a span. Multiple notes can be added to the same span — they are independent entries, each with its own timestamp.

import { addSpanNote } from "@arizeai/phoenix-client/spans";await addSpanNote({  spanNote: {    spanId: "abc123def456",    note: "Escalated due to failed retrieval",  },});

Deleting Spans#

import { deleteSpan } from "@arizeai/phoenix-client/spans";await deleteSpan({  spanIdentifier: "abc123def456",});

deleteSpan accepts either the OpenTelemetry span_id or Phoenix’s global span ID.

For span-level annotations (labels, scores, evaluations), see Span Annotations and Document Annotations.

Relevant Source Files