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