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

# Get Trace

> Get a single trace for the caller's project.

Defaults to the lightweight `skeleton` projection (no per-span I/O); pass
`fields=full` (or `fields=io,metadata`) for per-span input/output/metadata.

Args:
    auth (DualStampedAuth): Resolved credential context (API key or user
        session token); scopes the read to its project and stamps the
        rate-limit identity.
    trace_id (str): Trace to fetch.
    fields (str | None): Comma-separated projection groups (e.g. ``io``,
        ``metadata``) or an alias (``skeleton``/``full``). ``None`` selects
        the default `skeleton` projection.

Returns:
    PublicTraceDetailResponse: The trace with span skeletons, plus per-span
        I/O when the projection requests it.

Raises:
    HTTPException: 400 if `fields` is invalid, 404 if the trace is missing
        or outside the key's project, 500 on a reader failure.



## OpenAPI

````yaml /api-reference/openapi.json get /api/v1/public/traces/{trace_id}
openapi: 3.1.0
info:
  title: TraceRoot Public API
  version: 0.1.0
servers:
  - description: TraceRoot Cloud
    url: https://app.traceroot.ai
  - description: Self-hosted
    url: '{baseUrl}'
    variables:
      baseUrl:
        default: http://localhost:8000
        description: Your TraceRoot backend URL
security: []
paths:
  /api/v1/public/traces/{trace_id}:
    get:
      tags:
        - Traces
      summary: Get Trace
      description: >-
        Get a single trace for the caller's project.


        Defaults to the lightweight `skeleton` projection (no per-span I/O);
        pass

        `fields=full` (or `fields=io,metadata`) for per-span
        input/output/metadata.


        Args:
            auth (DualStampedAuth): Resolved credential context (API key or user
                session token); scopes the read to its project and stamps the
                rate-limit identity.
            trace_id (str): Trace to fetch.
            fields (str | None): Comma-separated projection groups (e.g. ``io``,
                ``metadata``) or an alias (``skeleton``/``full``). ``None`` selects
                the default `skeleton` projection.

        Returns:
            PublicTraceDetailResponse: The trace with span skeletons, plus per-span
                I/O when the projection requests it.

        Raises:
            HTTPException: 400 if `fields` is invalid, 404 if the trace is missing
                or outside the key's project, 500 on a reader failure.
      operationId: get_trace
      parameters:
        - in: path
          name: trace_id
          required: true
          schema:
            title: Trace Id
            type: string
        - description: >-
            Comma-separated field groups to include: 'core' (tree/timing/status,
            always included), 'usage' (tokens/cost), 'io' (per-span
            input/output), 'metadata' (per-span metadata). Aliases: 'skeleton'
            (core,usage), 'full' (everything). Unknown groups return 400.
          in: query
          name: fields
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Comma-separated field groups to include: 'core'
              (tree/timing/status, always included), 'usage' (tokens/cost), 'io'
              (per-span input/output), 'metadata' (per-span metadata). Aliases:
              'skeleton' (core,usage), 'full' (everything). Unknown groups
              return 400.
            title: Fields
        - description: >-
            Target project for the request. Required when authenticating with a
            user session token (a user credential is only meaningful scoped to a
            project); for an API key it is optional and, if given, must match
            the key's project.
          in: query
          name: project_id
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Target project for the request. Required when authenticating with
              a user session token (a user credential is only meaningful scoped
              to a project); for an API key it is optional and, if given, must
              match the key's project.
            title: Project Id
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicTraceDetailResponse'
          description: Successful Response
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid fields parameter
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Authentication failed
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Trace not found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Failed to get trace
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Authentication service unavailable
      security:
        - BearerAuth: []
components:
  schemas:
    PublicTraceDetailResponse:
      description: Full trace payload plus a backend-built link to its UI detail view.
      properties:
        git_ref:
          anyOf:
            - type: string
            - type: 'null'
          title: Git Ref
        git_repo:
          anyOf:
            - type: string
            - type: 'null'
          title: Git Repo
        input:
          anyOf:
            - type: string
            - type: 'null'
          title: Input
        metadata:
          anyOf:
            - type: string
            - type: 'null'
          title: Metadata
        name:
          title: Name
          type: string
        output:
          anyOf:
            - type: string
            - type: 'null'
          title: Output
        project_id:
          title: Project Id
          type: string
        session_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Session Id
        spans:
          items:
            $ref: '#/components/schemas/SpanResponse'
          title: Spans
          type: array
        trace_id:
          title: Trace Id
          type: string
        trace_start_time:
          format: date-time
          title: Trace Start Time
          type: string
        trace_url:
          title: Trace Url
          type: string
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
      required:
        - trace_id
        - project_id
        - name
        - trace_start_time
        - user_id
        - session_id
        - git_ref
        - git_repo
        - input
        - output
        - metadata
        - spans
        - trace_url
      title: PublicTraceDetailResponse
      type: object
    ErrorResponse:
      description: >-
        The canonical public error envelope (matches the gateway's normalized
        shape).
      properties:
        detail:
          title: Detail
          type: string
      required:
        - detail
      title: ErrorResponse
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    SpanResponse:
      description: >-
        A span skeleton plus its per-span I/O blobs
        (``input``/``output``/``metadata``).


        The projection-capable superset returned by the trace get/export
        endpoints.

        The blobs default to ``None`` and are populated only when the caller
        requests

        the matching field group (``io``/``metadata``; see

        ``rest.projection``). The default ``skeleton`` projection leaves them
        ``None``

        and never runs the bulk span-I/O query, so there is no payload or
        query-cost

        regression for the dashboard. Keeping the fields present (as ``null``)
        rather

        than omitting them is additive: a few bytes per span, and it matches the

        fields the shipped CLI's generated types already declare.


        One internal-only exception: the dashboard's trace-detail read leaves a
        small

        SDK span-path subset in ``metadata`` on the skeleton, which it needs to

        rebuild the tree of an in-flight trace. The public routes drop it (see

        ``rest.projection.drop_span_tree_metadata``), so for API clients the
        contract

        above holds exactly: ``metadata`` is ``null`` unless requested.
      properties:
        cost:
          anyOf:
            - type: number
            - type: 'null'
          title: Cost
        cost_details:
          additionalProperties:
            type: number
          default: {}
          title: Cost Details
          type: object
        error_type:
          default: ''
          title: Error Type
          type: string
        git_source_file:
          anyOf:
            - type: string
            - type: 'null'
          title: Git Source File
        git_source_function:
          anyOf:
            - type: string
            - type: 'null'
          title: Git Source Function
        git_source_line:
          anyOf:
            - type: integer
            - type: 'null'
          title: Git Source Line
        input:
          anyOf:
            - type: string
            - type: 'null'
          title: Input
        input_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Input Tokens
        metadata:
          anyOf:
            - type: string
            - type: 'null'
          title: Metadata
        model_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Model Name
        name:
          title: Name
          type: string
        output:
          anyOf:
            - type: string
            - type: 'null'
          title: Output
        output_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Output Tokens
        parent_span_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Parent Span Id
        span_end_time:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Span End Time
        span_id:
          title: Span Id
          type: string
        span_kind:
          title: Span Kind
          type: string
        span_start_time:
          format: date-time
          title: Span Start Time
          type: string
        status:
          title: Status
          type: string
        status_message:
          anyOf:
            - type: string
            - type: 'null'
          title: Status Message
        total_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total Tokens
        trace_id:
          title: Trace Id
          type: string
        usage_details:
          additionalProperties:
            type: integer
          default: {}
          title: Usage Details
          type: object
      required:
        - span_id
        - trace_id
        - parent_span_id
        - name
        - span_kind
        - span_start_time
        - span_end_time
        - status
        - status_message
        - model_name
        - cost
        - input_tokens
        - output_tokens
        - total_tokens
      title: SpanResponse
      type: object
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object
  securitySchemes:
    BearerAuth:
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.