> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atla-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Trace

> Get a single trace by ID

Retrieve a specific trace by its unique identifier. Returns
complete trace data including all spans, annotations, trace summary, and
custom metric values.


## OpenAPI

````yaml api-reference/openapi.yaml get /api/sdk/v1/traces/{traceId}
openapi: 3.1.0
info:
  title: Atla Insights API
  description: Development documentation
  version: 1.0.0
servers:
  - url: https://app.atla-ai.com
    description: API server
security: []
paths:
  /api/sdk/v1/traces/{traceId}:
    get:
      tags:
        - SDK
      summary: Get a single trace by ID
      description: >-
        Retrieve a specific trace by its unique identifier. Returns complete
        trace data including all spans, annotations, trace summary, and custom
        metric values.
      operationId: getTraceById
      parameters:
        - in: query
          name: include
          schema:
            type: array
            items:
              type: string
              enum:
                - spans
                - annotations
                - customMetrics
        - schema:
            type: string
          in: path
          name: traceId
          required: true
      responses:
        '200':
          description: Successfully retrieved trace with complete data
          content:
            application/json:
              schema:
                type: object
                properties:
                  trace:
                    type: object
                    properties:
                      id:
                        type: string
                      environment:
                        type: string
                        enum:
                          - PROD
                          - DEV
                      isSuccess:
                        type:
                          - boolean
                          - 'null'
                      isCompleted:
                        type: boolean
                      metadata:
                        type:
                          - object
                          - 'null'
                        additionalProperties:
                          type: string
                      stepCount:
                        type: integer
                      startedAt:
                        type: string
                      endedAt:
                        type: string
                      durationSeconds:
                        type: number
                      ingestedAt:
                        type: string
                      spans:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            traceId:
                              type: string
                            parentSpanId:
                              type:
                                - string
                                - 'null'
                            spanName:
                              type:
                                - string
                                - 'null'
                            startTimestamp:
                              type: string
                            endTimestamp:
                              type: string
                            isException:
                              type:
                                - boolean
                                - 'null'
                            otelEvents:
                              type: array
                              items: {}
                            annotations:
                              type: array
                              items:
                                type: object
                                properties:
                                  spanId:
                                    type: string
                                  failureMode:
                                    type: string
                                  atlaCritique:
                                    type: string
                                  id:
                                    type: string
                                required:
                                  - spanId
                                  - failureMode
                                  - atlaCritique
                                  - id
                          required:
                            - id
                            - traceId
                            - parentSpanId
                            - spanName
                            - startTimestamp
                            - endTimestamp
                            - isException
                            - otelEvents
                      customMetricValues:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            traceId:
                              type: string
                            customMetricId:
                              type: string
                            value:
                              type: string
                            customMetric:
                              type: object
                              properties:
                                id:
                                  type: string
                                name:
                                  type: string
                                dataType:
                                  type: string
                                  enum:
                                    - BOOLEAN
                                    - LIKERT_1_TO_5
                              required:
                                - id
                                - name
                                - dataType
                          required:
                            - id
                            - traceId
                            - customMetricId
                            - value
                    required:
                      - id
                      - environment
                      - isSuccess
                      - isCompleted
                      - stepCount
                      - startedAt
                      - endedAt
                      - durationSeconds
                      - ingestedAt
                required:
                  - trace
        '401':
          description: Unauthorized - Invalid or missing API key
        '404':
          description: Trace not found or access denied
        '500':
          description: Internal server error
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key authentication using Bearer token

````