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

# Overview

> SDK reference for span operations

All span operations are available under the `tracia.spans` namespace. Spans are automatically created when you run prompts or use `runLocal()`, providing visibility into LLM usage, performance, and costs.

<Note>
  **Terminology**: A **span** represents a single LLM call. Multiple spans can be grouped into a **trace** (session) using the `traceId` parameter.
</Note>

```typescript theme={null}
import { Tracia, Eval } from 'tracia';

const tracia = new Tracia({ apiKey: process.env.TRACIA_API_KEY });

// List spans with filters
const { spans, nextCursor } = await tracia.spans.list({
  promptSlug: 'welcome-email',
  status: 'SUCCESS',
  limit: 20
});

// Get a single span
const span = await tracia.spans.get('sp_abc123def456');

// Submit an evaluation for a span
await tracia.spans.evaluate('sp_abc123def456', {
  evaluator: 'quality',
  value: Eval.POSITIVE
});
```

## Available Methods

<CardGroup cols={3}>
  <Card title="List" icon="list" href="/sdk-node/spans/list">
    Get spans with filters and pagination
  </Card>

  <Card title="Get" icon="eye" href="/sdk-node/spans/get">
    Retrieve full details of a single span
  </Card>

  <Card title="Evaluate" icon="star" href="/sdk-node/spans/evaluate">
    Submit evaluations for spans
  </Card>
</CardGroup>

## Types

### Span

```typescript theme={null}
interface Span {
  id: string;
  spanId: string;
  traceId: string | null;
  parentSpanId: string | null;
  promptSlug: string | null;
  promptVersion: number | null;
  model: string;
  provider: string;
  input: { messages: PromptMessage[] };
  variables: Record<string, string> | null;
  output: string | null;
  status: 'SUCCESS' | 'ERROR';
  error: string | null;
  latencyMs: number;
  inputTokens: number;
  outputTokens: number;
  totalTokens: number;
  cost: number | null;
  tags: string[];
  userId: string | null;
  sessionId: string | null;
  createdAt: string;
}
```

### SpanListItem

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

### ListSpansOptions

```typescript theme={null}
interface ListSpansOptions {
  promptSlug?: string;
  status?: 'SUCCESS' | 'ERROR';
  startDate?: Date;
  endDate?: Date;
  userId?: string;
  sessionId?: string;
  tags?: string[];
  limit?: number;
  cursor?: string;
}
```

### EvaluateOptions

```typescript theme={null}
interface EvaluateOptions {
  evaluator: string;
  value: number;
  note?: string;
}
```

### EvaluateResult

```typescript theme={null}
interface EvaluateResult {
  id: string;
  evaluatorKey: string;
  evaluatorName: string;
  value: number;
  source: string;
  note: string | null;
  createdAt: string;
}
```

### Eval Constant

Use the `Eval` constant for binary evaluations:

```typescript theme={null}
import { Eval } from 'tracia';

Eval.POSITIVE  // 1
Eval.NEGATIVE  // 0
```