> ## 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 an evaluation for a span

## Request

<ParamField header="Authorization" type="string" required>
  Bearer token with your API key: `Bearer tr_your_api_key`
</ParamField>

<ParamField path="spanId" type="string" required>
  The span ID to evaluate (e.g., `sp_abc123def456`)
</ParamField>

<ParamField body="evaluatorKey" type="string" required>
  The evaluator key. Currently only `quality` is supported.
</ParamField>

<ParamField body="value" type="number" required>
  The evaluation score. Use `1` for positive or `0` for negative.
</ParamField>

<ParamField body="note" type="string">
  Optional note explaining the evaluation
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique identifier for the evaluation
</ResponseField>

<ResponseField name="evaluatorKey" type="string">
  Key of the evaluator used
</ResponseField>

<ResponseField name="evaluatorName" type="string">
  Display name of the evaluator
</ResponseField>

<ResponseField name="value" type="number">
  The evaluation score
</ResponseField>

<ResponseField name="source" type="string">
  Source of the evaluation (e.g., `api`, `dashboard`)
</ResponseField>

<ResponseField name="note" type="string | null">
  Optional note explaining the evaluation
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://app.tracia.io/api/v1/spans/sp_abc123def456/evaluations \
    -H "Authorization: Bearer tr_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "evaluatorKey": "quality",
      "value": 1,
      "note": "Response was accurate and helpful"
    }'
  ```

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

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

  await tracia.spans.evaluate('sp_abc123def456', {
    evaluator: 'quality',
    value: Eval.POSITIVE,
    note: 'Response was accurate and helpful'
  });
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "eval_xyz789",
    "evaluatorKey": "quality",
    "evaluatorName": "Quality",
    "value": 1,
    "source": "api",
    "note": "Response was accurate and helpful",
    "createdAt": "2024-01-15T10:35:00.000Z"
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "INVALID_REQUEST",
      "message": "Invalid evaluation value. Must be a number."
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "message": "Span not found: sp_abc123def456"
    }
  }
  ```
</ResponseExample>


## OpenAPI

````yaml POST /spans/{spanId}/evaluations
openapi: 3.1.0
info:
  title: Tracia API
  description: REST API for managing and running AI prompts with tracing
  version: 1.0.0
servers:
  - url: https://app.tracia.io/api/v1
    description: Production server
security:
  - bearerAuth: []
paths:
  /spans/{spanId}/evaluations:
    post:
      tags:
        - Spans
      summary: Evaluate Span
      description: >-
        Submit an evaluation for a span. Evaluations allow you to score spans
        using custom evaluators.
      operationId: evaluateSpan
      parameters:
        - name: spanId
          in: path
          required: true
          schema:
            type: string
          description: The span ID to evaluate (e.g., `sp_abc123def456`)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - evaluatorKey
                - value
              properties:
                evaluatorKey:
                  type: string
                  description: The evaluator key. Currently only `quality` is supported.
                value:
                  type: number
                  description: >-
                    The evaluation score. Use `1` for positive or `0` for
                    negative.
                note:
                  type: string
                  description: Optional note explaining the evaluation
      responses:
        '201':
          description: Evaluation created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Evaluation'
        '400':
          description: Invalid request (e.g., value is not a number)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Span not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Evaluation:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the evaluation
        evaluatorKey:
          type: string
          description: Key of the evaluator used
        evaluatorName:
          type: string
          description: Display name of the evaluator
        value:
          type: number
          description: The evaluation score
        source:
          type: string
          description: Source of the evaluation (e.g., `api`, `dashboard`)
        note:
          type: string
          nullable: true
          description: Optional note explaining the evaluation
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp of creation
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code
            message:
              type: string
              description: Error message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key starting with `tr_`

````