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

# Export Trace

> Export the V1 bundle (trace + spans + git_context + manifest) for the caller's project.

Defaults to the `full` projection — an export is explicit intent to take the
complete trace, so per-span input/output/metadata are included unless the
caller narrows `fields`. `bundle.trace` equals the `traces get` payload at the
same projection.

Rate limited on its own `export` bucket because it builds and serializes the
full bundle.

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 export.
    fields (str | None): Comma-separated projection groups or an alias
        (``skeleton``/``full``). ``None`` selects the default `full`
        projection.

Returns:
    PublicTraceExportResponse: The V1 export bundle (manifest, trace, spans,
        git_context) at the requested projection.

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}/export
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}/export:
    get:
      tags:
        - Traces
      summary: Export Trace
      description: >-
        Export the V1 bundle (trace + spans + git_context + manifest) for the
        caller's project.


        Defaults to the `full` projection — an export is explicit intent to take
        the

        complete trace, so per-span input/output/metadata are included unless
        the

        caller narrows `fields`. `bundle.trace` equals the `traces get` payload
        at the

        same projection.


        Rate limited on its own `export` bucket because it builds and serializes
        the

        full bundle.


        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 export.
            fields (str | None): Comma-separated projection groups or an alias
                (``skeleton``/``full``). ``None`` selects the default `full`
                projection.

        Returns:
            PublicTraceExportResponse: The V1 export bundle (manifest, trace, spans,
                git_context) at the requested projection.

        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: export_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/PublicTraceExportResponse'
          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:
    PublicTraceExportResponse:
      description: >-
        V1 export bundle: trace (== `traces get`) + spans + git_context +
        manifest.
      properties:
        git_context:
          $ref: '#/components/schemas/GitContext'
        manifest:
          $ref: '#/components/schemas/ExportManifest'
        spans:
          items:
            $ref: '#/components/schemas/SpanResponse'
          title: Spans
          type: array
        trace:
          $ref: '#/components/schemas/PublicTraceDetailResponse'
      required:
        - manifest
        - trace
        - spans
        - git_context
      title: PublicTraceExportResponse
      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
    GitContext:
      description: 'git_context.json: repo/ref + per-span source locations.'
      properties:
        git_ref:
          anyOf:
            - type: string
            - type: 'null'
          title: Git Ref
        git_repo:
          anyOf:
            - type: string
            - type: 'null'
          title: Git Repo
        sources:
          items:
            $ref: '#/components/schemas/GitSource'
          title: Sources
          type: array
      required:
        - git_repo
        - git_ref
        - sources
      title: GitContext
      type: object
    ExportManifest:
      description: 'manifest.json: index of the bundle''s parts.'
      properties:
        bundle_version:
          title: Bundle Version
          type: string
        files:
          items:
            type: string
          title: Files
          type: array
        project_id:
          title: Project Id
          type: string
        trace_id:
          title: Trace Id
          type: string
      required:
        - trace_id
        - project_id
        - bundle_version
        - files
      title: ExportManifest
      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
    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
    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
    GitSource:
      description: A single span's source location (trace-resident git metadata).
      properties:
        file:
          anyOf:
            - type: string
            - type: 'null'
          title: File
        function:
          anyOf:
            - type: string
            - type: 'null'
          title: Function
        line:
          anyOf:
            - type: integer
            - type: 'null'
          title: Line
        span_id:
          title: Span Id
          type: string
      required:
        - span_id
        - file
        - line
        - function
      title: GitSource
      type: object
  securitySchemes:
    BearerAuth:
      scheme: bearer
      type: http

````

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