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

# Public Get Trace

`GET /v1/traces/{trace_key}`

Fetch one trace by its full R2 key (as returned in the queue's
`trace_key`). The handler verifies the key's tenant prefix belongs to
the calling team before reading — 404 otherwise.

## Path parameters

- `trace_key` string, required

## Headers

- `authorization` string, nullable

## Response `200`

Successful Response

- TraceDocument — A single trace JSON blob written by the gateway to R2. See gateway `src/types.ts::TraceDocument` for the source of truth on field semantics. Notable gotcha: `request.body_text` contains the upstream-mapped model name (after `modelMapping` rewrite), so always use the top-level `request_model` field for "what the client sent".
  - `traceId` string, required
  - `traceDate` string, required
  - `teamId` string, required
  - `apiKeyId` string, required
  - `upstreamId` string, required
  - `fallbackFrom` string, nullable
  - `requestModel` string, nullable
  - `actualModel` string, nullable
  - `timestamp` string, required
  - `latencyMs` integer, required
  - `statusCode` integer, required
  - `isStreaming` boolean, required
  - `request` TraceBody, required — Captured request or response body. `body_text` is null when tracing was disabled at request time, or when the body exceeded the 10 MB capture cap (in which case `truncated=True` and the rest of the trace document is still preserved).
    - `contentType` string, nullable
    - `bodyText` string, nullable
    - `truncated` boolean
  - `response` TraceBody, required — Captured request or response body. `body_text` is null when tracing was disabled at request time, or when the body exceeded the 10 MB capture cap (in which case `truncated=True` and the rest of the trace document is still preserved).
    - `contentType` string, nullable
    - `bodyText` string, nullable
    - `truncated` boolean
  - `tokenUsage` TokenUsage — Token counts reported by the upstream provider.
    - `promptTokens` integer, required
    - `completionTokens` integer, required
    - `totalTokens` integer, required
  - `conversationId` string, nullable
  - `previousResponseId` string, nullable
  - `responseId` string, nullable
  - `errorMessage` string, nullable
  - `tenantId` string, nullable
  - `environment` string, nullable
  - `trafficType` string, nullable
  - `sessionId` string, nullable
  - `initiatedBy` string, nullable
  - `requestDelta` RequestDelta — Delta-storage metadata (gateway PR #36). Present when `request.body_text` holds a SLICED message list — `messages[from_index:]` of what the client actually sent — rather than the literal wire request. `from_index` 0 = first turn: the full wire request is also a valid delta.
    - `fromIndex` integer, required
    - `fullMessageCount` integer, required
  - `historyEdited` boolean

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/trainloop/apis/trainloop-api.md) · [All operations](https://skmtc.dev/trainloop/apis/trainloop-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/trainloop/trainloop-api/revisions/aedb0e4b59f8/schema)