---
title: "Get Trace"
method: GET
path: "/api/v1/public/traces/{trace_id}"
tags: ["Traces"]
---

# Get Trace

`GET /api/v1/public/traces/{trace_id}`

## Request

- Base URL: `https://app.traceroot.ai`
- URL: `https://app.traceroot.ai/api/v1/public/traces/{trace_id}`
- Auth: HTTP bearer

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.

## Path parameters

- `trace_id` string, required

## Query parameters

- `fields` string, nullable: 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.
- `project_id` string, nullable: 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.

## Response `200`

Successful Response

- PublicTraceDetailResponse: Full trace payload plus a backend-built link to its UI detail view.
  - `git_ref` string, nullable, required
  - `git_repo` string, nullable, required
  - `input` string, nullable, required
  - `metadata` string, nullable, required
  - `name` string, required
  - `output` string, nullable, required
  - `project_id` string, required
  - `session_id` string, nullable, required
  - `spans` SpanResponse[], required
    - `cost` number, nullable, required
    - `cost_details` object
    - `error_type` string
    - `git_source_file` string, nullable
    - `git_source_function` string, nullable
    - `git_source_line` integer, nullable
    - `input` string, nullable
    - `input_tokens` integer, nullable, required
    - `metadata` string, nullable
    - `model_name` string, nullable, required
    - `name` string, required
    - `output` string, nullable
    - `output_tokens` integer, nullable, required
    - `parent_span_id` string, nullable, required
    - `span_end_time` string, date-time, nullable, required
    - `span_id` string, required
    - `span_kind` string, required
    - `span_start_time` string, date-time, required
    - `status` string, required
    - `status_message` string, nullable, required
    - `total_tokens` integer, nullable, required
    - `trace_id` string, required
    - `usage_details` object
  - `trace_id` string, required
  - `trace_start_time` string, date-time, required
  - `trace_url` string, required
  - `user_id` string, nullable, required

## Other responses

- `400`: Invalid fields parameter
- `401`: Authentication failed
- `404`: Trace not found
- `422`: Validation Error
- `500`: Failed to get trace
- `503`: Authentication service unavailable

---

[API](https://skmtc.dev/traceroot/apis/traceroot-public-api.md) - [All operations](https://skmtc.dev/traceroot/apis/traceroot-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/traceroot/apis/traceroot-public-api/revisions/ce6aef96c0d6?raw)