> ## Documentation Index
> Fetch the complete documentation index at: https://arize-ax.mintlify.site/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 **BETA**. 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). If any span ID in the batch is not found within the window, the entire request is rejected with a 404 error.

```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: "c3Bhbl9pZF9hYmMxMjM=", // base64-encoded span ID
      values: [
        { name: "quality", score: 0.9 },
        { name: "topic", label: "science" },
      ],
    },
  ],
});
```

### Parameters

| Parameter     | Type                    | Description                                                                                                                                     |
| ------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `project`     | `string`                | The name or ID of the project containing the spans to annotate.                                                                                 |
| `space`       | `string`                | The space name or ID. Required when `project` is a name.                                                                                        |
| `annotations` | `AnnotateRecordInput[]` | Batch of annotations. Each item specifies a `recordId` (span ID) and `values` (list of annotation values to set). Up to 1000 spans per request. |
| `startTime`   | `Date`                  | Start of the time window used to look up spans. Defaults to 31 days ago.                                                                        |
| `endTime`     | `Date`                  | End of the time window used to look up spans. Defaults to now.                                                                                  |

Returns `void`. The writes are submitted to the database layer but may not be immediately visible in queries (HTTP 202 Accepted).

## Delete Spans

Permanently delete spans by their IDs. This operation is irreversible. Only spans within the supported lookback window (2 years) are considered; older spans are not affected. All span IDs are sent in a single request (maximum 5,000 per call).

```typescript theme={null}
import { deleteSpans } from "@arizeai/ax-client";

// By project ID
const result = await deleteSpans({
  project: "UHJvamVjdDox",
  spanIds: ["a1b2c3d4e5f6a7b8", "f8e7d6c5b4a39281"],
});
if (!result.completed) {
  // retry the original full request — the delete is idempotent
}

// By project name (requires space)
const result2 = await deleteSpans({
  project: "My Project",
  space: "my-space",
  spanIds: ["a1b2c3d4e5f6a7b8"],
});
```

### Parameters

| Parameter | Type       | Description                                              |
| --------- | ---------- | -------------------------------------------------------- |
| `project` | `string`   | The project name or ID containing the spans to delete.   |
| `space`   | `string`   | The space name or ID. Required when `project` is a name. |
| `spanIds` | `string[]` | List of span IDs to delete. Maximum 5,000 per call.      |

### Return Value

Returns a `SpanDeleteResult` with the following fields:

| Field               | Type       | Description                                                                                                                                                                                                              |
| ------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `completed`         | `boolean`  | `true` when the server fully processed all data for the request — no retry is needed. `false` when processing could not fully complete; retry the original full request (the delete is idempotent).                      |
| `deletedSpanIds`    | `string[]` | Span IDs confirmed deleted in this request.                                                                                                                                                                              |
| `notDeletedSpanIds` | `string[]` | Requested span IDs that were not deleted. When `completed` is `true`, these were not found (never ingested or already deleted). When `completed` is `false`, some IDs may not have been reached — retry to resolve them. |