Spans

Query and filter LLM trace spans for a project using the Arize TypeScript SDK.

The spans functions are currently in ALPHA. The API may change without notice. A one-time warning is emitted on first use.

List Spans

List spans for a given project. Supports time-window filtering, SQL-style filter expressions, and cursor-based pagination.

import { listSpans } from "@arizeai/ax-client";

// By project ID
const { data: spans, pagination } = await listSpans({
  project: "your_project_id",
  limit: 50,
});

// By project name (requires space)
const { data: spans, pagination } = await listSpans({
  project: "My Project",
  space: "my-space",
  startTime: "2026-03-01T00:00:00Z",
  endTime: "2026-03-08T00:00:00Z",
  filter: "status_code = 'ERROR'",
  limit: 100,
});

Parameters

Parameter	Type	Description
project	string	The project name or ID.
space	string	The space name or ID. Required when project is a name.
startTime	string	ISO 8601 timestamp. Defaults to 1 week ago.
endTime	string	ISO 8601 timestamp. Defaults to current time.
filter	string	SQL-style filter expression (e.g. "status_code = 'ERROR'").
limit	number	Maximum number of spans to return.
cursor	string	Cursor for pagination.

Span Fields

Each returned Span object includes:

Field	Type	Description
name	string	The span name.
context.traceId	string	The trace ID.
context.spanId	string	The span ID.
kind	string	The span kind (e.g. "LLM", "CHAIN").
parentId	string | null	Parent span ID, if any.
startTime	Date	When the span started.
endTime	Date	When the span ended.
statusCode	string | null	Status code (e.g. "OK", "ERROR").
statusMessage	string | null	Status message, if any.
attributes	object | null	Span attributes (e.g. LLM inputs/outputs).
annotations	Annotation[]	Human annotations attached to this span.
evaluations	Evaluation[]	LLM-as-judge evaluations for this span.
events	SpanEvent[]	Events recorded during the span.