---
title: "The trace bundle [read]"
method: GET
path: "/traces/{id}"
tags: ["traces"]
---

# The trace bundle \[read\]

`GET /traces/{id}`

## Request

- Base URL: `https://api.agentsky.dev/v1`
- URL: `https://api.agentsky.dev/v1/traces/{id}`
- Auth: HTTP bearer

Spans, the sessions and tasks they reach, cost counted once per session, and gaps. A session joins by an event naming it or by its own `metadata.trace_id`. Returns 404 when the TASK_TRACES switch is off for the workspace and 503 not_migrated before the tables exist.

## Path parameters

- `id` string, required

## Response `200`

OK

- TaskTraceBundle
  - `trace` TaskTrace, required
    - `id` string, required: trc_… — the public id
    - `name` string, nullable, required
    - `created_at` string, date-time, required
    - `expires_at` string, date-time, required: 30 days after creation; the trace and its events are deleted then
  - `coverage` 'metadata_only' | 'partial' | 'redacted', required: metadata_only when no event carries content; redacted when any kept content had a value replaced or was dropped
  - `spans` object[], required: What sources reported, oldest first. `edge` is root, resolved, pending (its parent may still arrive) or unresolved (the parent never arrived within 10 minutes). A span its source left open that names a session ends with that session's turn (`outcome_source: platform`): failed on `session.error`, completed on `session.status_idle`, cancelled when the session was archived or deleted first. Events with content carry `content.text`, up to 4 MiB per bundle.
  - `sessions` object[], required: Platform sessions the trace reaches, with their tasks' members; each listed once
  - `task_ids` string[], required
  - `consumed_cost` object, required: Summed over the listed sessions, each counted once; external spend is not known and not included
    - `amount` string, required: Whole US cents
    - `currency` 'USD', required
    - `unit` 'cents': The unit of `amount`; present on every amount the API returns
    - `amount_usd` string: The exact amount in US dollars, up to six decimals — "0.0038" for spend that rounds to 0 cents. Returned, never accepted.
    - `sessions` integer: How many sessions were summed
  - `gaps` object[], required

## Other responses

- `default`: Error — { error: { code, message } }

## Changes

- **2026-11-02** `e5e8f0229a99`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/traces/:id/get.md)

---

[API](https://skmtc.dev/agentsky/apis/agentsky-developer-api.md) - [All operations](https://skmtc.dev/agentsky/apis/agentsky-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentsky/apis/agentsky-developer-api/revisions/0d435187cd55?raw)