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

# Get Span

> Get full details of a single 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 (e.g., `sp_abc123def456`)
</ParamField>

## Response

<ResponseField name="id" type="string">
  Internal identifier
</ResponseField>

<ResponseField name="spanId" type="string">
  External span ID
</ResponseField>

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

<ResponseField name="parentSpanId" type="string | null">
  Parent span ID for chained conversations
</ResponseField>

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

<ResponseField name="promptVersion" type="number | null">
  Version of the prompt used
</ResponseField>

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

<ResponseField name="provider" type="string">
  Provider name (e.g., `openai`, `amazon_bedrock`)
</ResponseField>

<ResponseField name="input" type="object">
  Input messages sent to the model

  <Expandable title="Input object">
    <ResponseField name="messages" type="array">
      Array of message objects with `role` and `content`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="variables" type="object | null">
  Template variables used in the prompt
</ResponseField>

<ResponseField name="output" type="string | null">
  Model response text
</ResponseField>

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

<ResponseField name="error" type="string | null">
  Error message if status is `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="tags" type="string[]">
  Tags associated with this span
</ResponseField>

<ResponseField name="userId" type="string | null">
  End user ID
</ResponseField>

<ResponseField name="sessionId" type="string | null">
  Session ID
</ResponseField>

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

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET https://app.tracia.io/api/v1/spans/sp_abc123def456 \
    -H "Authorization: Bearer tr_your_api_key"
  ```

  ```typescript SDK theme={null}
  const span = await tracia.spans.get('sp_abc123def456');
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "clx1abc123",
    "spanId": "sp_abc123def456",
    "traceId": "tr_session123",
    "parentSpanId": null,
    "promptSlug": "welcome-email",
    "promptVersion": 3,
    "model": "gpt-4o",
    "provider": "openai",
    "input": {
      "messages": [
        {
          "role": "system",
          "content": "You are a helpful assistant that writes professional emails."
        },
        {
          "role": "user",
          "content": "Write a welcome email for Alice who just signed up for Tracia."
        }
      ]
    },
    "variables": {
      "name": "Alice",
      "product": "Tracia"
    },
    "output": "Subject: Welcome to Tracia, Alice!\n\nDear Alice,\n\nThank you for signing up...",
    "status": "SUCCESS",
    "error": null,
    "latencyMs": 1250,
    "inputTokens": 150,
    "outputTokens": 320,
    "totalTokens": 470,
    "cost": 0.0234,
    "tags": ["production", "v2"],
    "userId": "user_123",
    "sessionId": "session_456",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
  ```

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


## OpenAPI

````yaml GET /spans/{spanId}
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}:
    get:
      tags:
        - Spans
      summary: Get Span
      description: Get full details of a single span
      operationId: getSpan
      parameters:
        - name: spanId
          in: path
          required: true
          schema:
            type: string
          description: The span ID (e.g., `sp_abc123def456`)
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Span'
        '404':
          description: Span not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Span:
      type: object
      properties:
        id:
          type: string
          description: Internal identifier
        spanId:
          type: string
          description: External span ID (e.g., `sp_abc123`)
        traceId:
          type: string
          nullable: true
          description: Session/trace ID for multi-turn conversations
        parentSpanId:
          type: string
          nullable: true
          description: Parent span ID for chained conversations
        promptSlug:
          type: string
          nullable: true
          description: Slug of the prompt that was run (null for runLocal spans)
        promptVersion:
          type: integer
          nullable: true
          description: Version of the prompt used
        model:
          type: string
          description: Model used (e.g., `gpt-4o`)
        provider:
          type: string
          description: Provider name (e.g., `openai`, `amazon_bedrock`)
        input:
          type: object
          properties:
            messages:
              type: array
              items:
                type: object
                properties:
                  role:
                    type: string
                  content:
                    type: string
        variables:
          type: object
          nullable: true
          additionalProperties:
            type: string
          description: Template variables used in the prompt
        output:
          type: string
          nullable: true
          description: Model response text
        status:
          type: string
          enum:
            - SUCCESS
            - ERROR
        error:
          type: string
          nullable: true
          description: Error message if status is ERROR
        latencyMs:
          type: integer
          description: Execution time in milliseconds
        inputTokens:
          type: integer
        outputTokens:
          type: integer
        totalTokens:
          type: integer
        cost:
          type: number
          nullable: true
          description: Cost in USD
        tags:
          type: array
          items:
            type: string
        userId:
          type: string
          nullable: true
        sessionId:
          type: string
          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_`

````