---
title: "Read a saved conversation using its opaque source reference"
method: GET
path: "/api/v1/transcripts/read"
tags: ["transcripts"]
---

# Read a saved conversation using its opaque source reference

`GET /api/v1/transcripts/read`

## Request

- Base URL: `https://composal.com` (the document declares no server; this is the origin it was published from)
- URL: `https://composal.com/api/v1/transcripts/read`
- Auth: HTTP bearer

Uses the same authorized indexed reader as the session route.

## Query parameters

- `source_ref` string
- `cursor` string
- `limit` integer
- `max_bytes` integer
- `include_tools` boolean
- `around_event` integer
- `event_digest` string

## Response `200`

Indexed events or an explicit content availability state.

- TranscriptReadPage
  - `status` 'available' | 'preparing' | 'pending' | 'unavailable' | 'expired' | 'no_checkpoint', required
  - `session_id` string, required
  - `checkpoint_id` string, nullable, required
  - `source_ref` string, nullable, required
  - `scope` 'checkpoint' | 'whole_session', required
  - `events` TranscriptReadEvent[], required
    - `index` integer, required
    - `kind` 'message' | 'tool_use' | 'tool_result', required
    - `role` string, nullable, required
    - `text` string, required
    - `truncated` boolean, required
    - `timestamp` string, nullable, required
    - `citation` object, required
      - `checkpoint_id` string, required
      - `event_index` integer, required
      - `digest` string, required
  - `older_cursor` string, nullable, required
  - `has_more` boolean, required
  - `limits` object, required
    - `events` integer, required
    - `bytes` integer, required
    - `include_tools` boolean, required
  - `contains_truncated_events` boolean, required
  - `truncation_notice` string, nullable, required
  - `newer_cursor` string, nullable, required

## Other responses

- `400`: Invalid limits or source reference.
- `401`: Authentication required.
- `403`: Forbidden
- `404`: Missing or inaccessible session or checkpoint.
- `409`: The cursor no longer identifies the same content or filters.
- `413`: Increase max_bytes to fit the next complete indexed event.
- `422`: Unprocessable entity
- `502`: Bad gateway

---

[API](https://skmtc.dev/composal/apis/vex-api.md) - [All operations](https://skmtc.dev/composal/apis/vex-api/llms.txt) - [OpenAPI document](https://skmtc.dev/composal/apis/vex-api/revisions/74298a24e040?raw)