---
title: "Retrieve a trace"
method: GET
path: "/api/traces/{trace_unique_id}/"
tags: ["traces"]
---

# Retrieve a trace

`GET /api/traces/{trace_unique_id}/`

Retrieve a single trace by `trace_unique_id`, including aggregate metrics and the full span tree. Metadata keys beginning with `_` are reserved for platform use and are omitted from customer-facing span and trace responses, so they do not round-trip through read APIs.

## Path parameters

- `trace_unique_id` string, required

## Headers

- `Authorization` string, required

## Response `200`

Trace detail with span tree.

- TracesRetrieveTraceResponse200
  - `id` string — Trace identifier.
  - `trace_unique_id` string — Unique trace identifier.
  - `root_span_unique_id` string — Root span ID for the trace.
  - `unique_organization_id` string — Organization unique ID.
  - `organization_id` string — Alias of `unique_organization_id`.
  - `organization_name` string — Organization name when available.
  - `organization_key_id` string — API key identifier used to create the trace.
  - `environment` string — Environment for the trace.
  - `customer_identifier` string — Customer or user identifier.
  - `start_time` string, date-time — When the trace started.
  - `end_time` string, date-time — When the trace ended.
  - `duration` number, double — Total duration in seconds.
  - `span_count` integer — Total spans in the trace.
  - `llm_call_count` integer — Number of LLM-call spans.
  - `total_cost` number, double — Total cost in USD.
  - `total_prompt_tokens` integer — Sum of prompt tokens.
  - `total_completion_tokens` integer — Sum of completion tokens.
  - `total_tokens` integer — Sum of all tokens.
  - `error_count` integer — Number of error spans.
  - `name` string — Root span name.
  - `input` string — Root span input. API key responses may include full storage-enriched content.
  - `output` string — Root span output. API key responses may include full storage-enriched content.
  - `metadata` ApiTracesTraceUniqueIdGetResponsesContentApplicationJsonSchemaMetadata — Customer metadata. Keys beginning with `_` are reserved and omitted from customer-facing responses.
  - `trace_group_identifier` string — Workflow or trace-group identifier.
  - `session_identifier` string — Session identifier when present.
  - `model` string — Primary/root model used.
  - `storage_object_key` string — Storage object key for the root span payload when present.
  - `span_tree` ApiTracesTraceUniqueIdGetResponsesContentApplicationJsonSchemaSpanTreeItems[] — Hierarchical span tree for the trace.
    - `id` string — Span identifier.
    - `unique_id` string — Underlying log unique ID.
    - `span_unique_id` string — Unique span identifier within the trace.
    - `span_name` string — Span name.
    - `span_parent_id` string, nullable — Parent span ID.
    - `trace_unique_id` string — Trace ID.
    - `customer_identifier` string — Customer identifier.
    - `thread_identifier` string — Thread identifier when present.
    - `session_identifier` string — Session identifier when present.
    - `organization_key_id` string — API key identifier.
    - `organization_id` string — Organization unique ID.
    - `environment` string — Environment.
    - `log_type` string — Span/log type.
    - `timestamp` string, date-time — Span end time.
    - `start_time` string, date-time — Span start time.
    - `end_time` string, date-time — Alias of `timestamp`.
    - `prompt_tokens` integer — Prompt tokens for this span.
    - `completion_tokens` integer — Completion tokens for this span.
    - `total_request_tokens` integer — Total tokens for this span.
    - `cost` number, double — Span cost in USD.
    - `model` string — Model used by the span.
    - `latency` number, double — Span duration in seconds.
    - `status_code` integer — Status code recorded for the span.
    - `status` string — Span status.
    - `input` string — Span input.
    - `output` string — Span output.
    - `metadata` ApiTracesTraceUniqueIdGetResponsesContentApplicationJsonSchemaSpanTreeItemsMetadata — Customer metadata. Keys beginning with `_` are reserved and omitted from customer-facing responses.
    - `span_links` string — Serialized OTEL span links when present.
    - `storage_object_key` string — Backing storage object key when present.
    - `span_workflow_name` string — Workflow name when present.
    - `children` ApiTracesTraceUniqueIdGetResponsesContentApplicationJsonSchemaSpanTreeItemsChildrenItems[] — Nested child spans.

## Other responses

- `401` — Unauthorized - Missing/invalid authentication
- `404` — Not Found
- `429` — Rate Limited
- `500` — Internal Server Error

---

[API](https://skmtc.net/keywordsai/apis/api-reference.md) · [All operations](https://skmtc.net/keywordsai/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/keywordsai/api-reference/revisions/4e064cf81dae/schema)