Spans

Search and manage spans with @arizeai/phoenix-client

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

Relevant Source Files

• src/spans/getSpans.ts for the exact filter names and query behavior

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 model
const 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.

Source Map

• src/spans/getSpans.ts
• src/spans/addSpanNote.ts
• src/spans/deleteSpan.ts
• src/spans/getSpanAnnotations.ts
• src/types/spans.ts