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

# List Spans

> Get spans with filters and pagination

```typescript theme={null}
const { spans, nextCursor } = await tracia.spans.list(options);
```

Retrieve spans with optional filters and cursor-based pagination.

## Parameters

| Parameter            | Type                   | Required | Description                            |
| -------------------- | ---------------------- | -------- | -------------------------------------- |
| `options.promptSlug` | `string`               | No       | Filter by prompt slug                  |
| `options.status`     | `'SUCCESS' \| 'ERROR'` | No       | Filter by status                       |
| `options.startDate`  | `Date`                 | No       | Filter spans created after this date   |
| `options.endDate`    | `Date`                 | No       | Filter spans created before this date  |
| `options.userId`     | `string`               | No       | Filter by end user ID                  |
| `options.sessionId`  | `string`               | No       | Filter by session ID                   |
| `options.tags`       | `string[]`             | No       | Filter by tags (AND logic)             |
| `options.limit`      | `number`               | No       | Results per page (max 100, default 50) |
| `options.cursor`     | `string`               | No       | Cursor from previous response          |

## Response

```typescript theme={null}
interface ListSpansResult {
  spans: SpanListItem[];
  nextCursor?: string;
}

interface SpanListItem {
  id: string;
  spanId: string;
  traceId: string | null;
  promptSlug: string | null;
  model: string;
  status: 'SUCCESS' | 'ERROR';
  latencyMs: number;
  inputTokens: number;
  outputTokens: number;
  totalTokens: number;
  cost: number | null;
  createdAt: string;
}
```

## Examples

### Basic Usage

```typescript theme={null}
const { spans } = await tracia.spans.list();

console.log(`Found ${spans.length} spans`);
```

### Filtering by Prompt

```typescript theme={null}
const { spans } = await tracia.spans.list({
  promptSlug: 'welcome-email',
  status: 'SUCCESS'
});

spans.forEach(span => {
  console.log(`${span.spanId}: ${span.latencyMs}ms, ${span.totalTokens} tokens`);
});
```

### Date Range Filtering

```typescript theme={null}
const { spans } = await tracia.spans.list({
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31')
});
```

### Filtering by Tags

```typescript theme={null}
const { spans } = await tracia.spans.list({
  tags: ['production', 'v2']  // Must have ALL tags
});
```

### Pagination

```typescript theme={null}
async function getAllSpans() {
  const allSpans = [];
  let cursor: string | undefined;

  do {
    const { spans, nextCursor } = await tracia.spans.list({
      limit: 100,
      cursor
    });

    allSpans.push(...spans);
    cursor = nextCursor;
  } while (cursor);

  return allSpans;
}
```

### Calculating Costs

```typescript theme={null}
const { spans } = await tracia.spans.list({
  promptSlug: 'welcome-email',
  startDate: new Date('2024-01-01')
});

const totalCost = spans.reduce((sum, s) => sum + (s.cost || 0), 0);
const totalTokens = spans.reduce((sum, s) => sum + s.totalTokens, 0);

console.log(`Total cost: $${totalCost.toFixed(4)}`);
console.log(`Total tokens: ${totalTokens}`);
```

## Error Handling

```typescript theme={null}
import { TraciaError, TraciaErrorCode } from 'tracia';

try {
  const { spans } = await tracia.spans.list();
} catch (error) {
  if (error instanceof TraciaError) {
    if (error.code === TraciaErrorCode.UNAUTHORIZED) {
      console.error('Invalid API key');
    }
  }
}
```