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: new Date("2026-03-01T00:00:00Z"),
endTime: new Date("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 | Date | Defaults to 1 week ago. |
endTime | Date | 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. |
Annotate Spans
Write human annotations to a batch of spans in a project. Annotations are upserted by annotation config name for each span; submitting the same name for the same span overwrites the previous value. Up to 1000 spans may be annotated per request. Spans are looked up within the specified time window (defaulting to the last 31 days).
import { annotateSpans } from "@arizeai/ax-client";
await annotateSpans({
project: "My Project", // project name or ID
space: "my-space", // required when project is a name
annotations: [
{
recordId: "your_span_id",
values: [
{ name: "quality", score: 0.9 },
{ name: "topic", label: "science" },
],
},
],
});
Delete Spans
Permanently delete spans by their IDs. This operation is irreversible. Only spans within the supported lookback window (2 years) are considered. Maximum 5,000 span IDs per call.
import { deleteSpans } from "@arizeai/ax-client";
await deleteSpans({
project: "My Project", // project name or ID
space: "my-space", // required when project is a name
spanIds: ["a1b2c3d4e5f6a7b8", "f8e7d6c5b4a39281"],
});
