> ## Documentation Index
> Fetch the complete documentation index at: https://arize-ax.mintlify.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Spans

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

<Note>
  The `spans` functions are currently in **ALPHA**. The API may change without notice. A one-time warning is emitted on first use.
</Note>

## List Spans

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

```typescript theme={null}
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).

```typescript theme={null}
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.

```typescript theme={null}
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"],
});
```