> ## 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 optional filters and pagination

## Request

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

<ParamField query="promptSlug" type="string">
  Filter by prompt slug
</ParamField>

<ParamField query="status" type="string">
  Filter by status: `SUCCESS` or `ERROR`
</ParamField>

<ParamField query="startDate" type="string">
  Filter spans created after this ISO 8601 date
</ParamField>

<ParamField query="endDate" type="string">
  Filter spans created before this ISO 8601 date
</ParamField>

<ParamField query="userId" type="string">
  Filter by end user ID
</ParamField>

<ParamField query="sessionId" type="string">
  Filter by session ID
</ParamField>

<ParamField query="tags" type="string">
  Comma-separated list of tags (AND logic)
</ParamField>

<ParamField query="limit" type="number">
  Number of results per page (max 100, default 50)
</ParamField>

<ParamField query="cursor" type="string">
  Cursor for pagination (from previous response)
</ParamField>

## Response

<ResponseField name="spans" type="array">
  Array of span objects

  <Expandable title="Span object">
    <ResponseField name="id" type="string">
      Internal identifier
    </ResponseField>

    <ResponseField name="spanId" type="string">
      External span ID (e.g., `sp_abc123`)
    </ResponseField>

    <ResponseField name="traceId" type="string | null">
      Trace session ID if part of a multi-turn conversation
    </ResponseField>

    <ResponseField name="promptSlug" type="string | null">
      Slug of the prompt that was run (null for runLocal spans)
    </ResponseField>

    <ResponseField name="model" type="string">
      Model used (e.g., `gpt-4o`)
    </ResponseField>

    <ResponseField name="status" type="string">
      `SUCCESS` or `ERROR`
    </ResponseField>

    <ResponseField name="latencyMs" type="number">
      Execution time in milliseconds
    </ResponseField>

    <ResponseField name="inputTokens" type="number">
      Number of input tokens
    </ResponseField>

    <ResponseField name="outputTokens" type="number">
      Number of output tokens
    </ResponseField>

    <ResponseField name="totalTokens" type="number">
      Total tokens used
    </ResponseField>

    <ResponseField name="cost" type="number | null">
      Cost in USD
    </ResponseField>

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

<ResponseField name="nextCursor" type="string | null">
  Cursor for the next page of results
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://app.tracia.io/api/v1/spans?promptSlug=welcome-email&limit=20" \
    -H "Authorization: Bearer tr_your_api_key"
  ```

  ```typescript SDK theme={null}
  const { spans, nextCursor } = await tracia.spans.list({
    promptSlug: 'welcome-email',
    limit: 20
  });
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "spans": [
      {
        "id": "clx1abc123",
        "spanId": "sp_abc123def456",
        "traceId": "tr_session123",
        "promptSlug": "welcome-email",
        "model": "gpt-4o",
        "status": "SUCCESS",
        "latencyMs": 1250,
        "inputTokens": 150,
        "outputTokens": 320,
        "totalTokens": 470,
        "cost": 0.0234,
        "createdAt": "2024-01-15T10:30:00.000Z"
      }
    ],
    "nextCursor": "clx2def456"
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "message": "Invalid or missing API key"
    }
  }
  ```
</ResponseExample>


## OpenAPI

````yaml GET /spans
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:
    get:
      tags:
        - Spans
      summary: List Spans
      description: Get spans with optional filters and pagination
      operationId: listSpans
      parameters:
        - name: promptSlug
          in: query
          schema:
            type: string
          description: Filter by prompt slug
        - name: status
          in: query
          schema:
            type: string
            enum:
              - SUCCESS
              - ERROR
          description: Filter by status
        - name: startDate
          in: query
          schema:
            type: string
            format: date-time
          description: Filter spans created after this ISO 8601 date
        - name: endDate
          in: query
          schema:
            type: string
            format: date-time
          description: Filter spans created before this ISO 8601 date
        - name: userId
          in: query
          schema:
            type: string
          description: Filter by end user ID
        - name: sessionId
          in: query
          schema:
            type: string
          description: Filter by session ID
        - name: tags
          in: query
          schema:
            type: string
          description: Comma-separated list of tags (AND logic)
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
            maximum: 100
          description: Number of results per page (max 100, default 50)
        - name: cursor
          in: query
          schema:
            type: string
          description: Cursor for pagination (from previous response)
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  spans:
                    type: array
                    items:
                      $ref: '#/components/schemas/SpanSummary'
                  nextCursor:
                    type: string
                    nullable: true
                    description: Cursor for the next page of results
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    SpanSummary:
      type: object
      properties:
        id:
          type: string
        spanId:
          type: string
        traceId:
          type: string
          nullable: true
        promptSlug:
          type: string
          nullable: true
        model:
          type: string
        status:
          type: string
          enum:
            - SUCCESS
            - ERROR
        latencyMs:
          type: integer
        inputTokens:
          type: integer
        outputTokens:
          type: integer
        totalTokens:
          type: integer
        cost:
          type: number
          nullable: true
        createdAt:
          type: string
          format: date-time
    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_`

````