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

# Evaluate Span

> Submit evaluations for spans

```typescript theme={null}
const evaluation = await tracia.spans.evaluate(spanId, options);
```

Submit an evaluation for a span. Evaluations allow you to score spans, providing feedback on response quality.

## Parameters

| Parameter           | Type     | Required | Description                                                          |
| ------------------- | -------- | -------- | -------------------------------------------------------------------- |
| `spanId`            | `string` | Yes      | The span ID to evaluate                                              |
| `options.evaluator` | `string` | Yes      | The evaluator key. Currently only `quality` is supported.            |
| `options.value`     | `number` | Yes      | The evaluation score. Use `Eval.POSITIVE` (1) or `Eval.NEGATIVE` (0) |
| `options.note`      | `string` | No       | Optional note explaining the evaluation                              |

## Response

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

## Examples

### Binary Evaluation (Thumbs Up/Down)

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

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

// Positive evaluation
await tracia.spans.evaluate('sp_abc123def456', {
  evaluator: 'quality',
  value: Eval.POSITIVE
});

// Negative evaluation
await tracia.spans.evaluate('sp_abc123def456', {
  evaluator: 'quality',
  value: Eval.NEGATIVE
});
```

### Adding a Note

```typescript theme={null}
await tracia.spans.evaluate('sp_abc123def456', {
  evaluator: 'quality',
  value: Eval.NEGATIVE,
  note: 'Response was off-topic and did not address the user question'
});
```

### User Feedback Integration

```typescript theme={null}
// Capture user feedback from your application
async function submitUserFeedback(spanId: string, isHelpful: boolean, comment?: string) {
  await tracia.spans.evaluate(spanId, {
    evaluator: 'quality',
    value: isHelpful ? Eval.POSITIVE : Eval.NEGATIVE,
    note: comment
  });
}
```

## Error Handling

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

try {
  await tracia.spans.evaluate('sp_abc123def456', {
    evaluator: 'quality',
    value: Eval.POSITIVE
  });
} catch (error) {
  if (error instanceof TraciaError) {
    if (error.code === TraciaErrorCode.NOT_FOUND) {
      console.error('Span not found');
    } else if (error.code === TraciaErrorCode.INVALID_REQUEST) {
      console.error('Invalid evaluation value');
    }
  }
}
```