Skip to main content
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