---
title: "Read a conversation's words"
method: GET
path: "/api/v1/conversations/{thread_id}/transcript"
tags: ["authed"]
---

# Read a conversation's words

`GET /api/v1/conversations/{thread_id}/transcript`

## Request

- Base URL: `https://api.teaflask.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.teaflask.com/api/v1/conversations/{thread_id}/transcript`
- Auth: none declared

Read one conversation as it happened: each exchange's visitor
message, the assistant's replies, and which tools it called and how
each ended (never what they were given or returned), with the
exchange's status, plain-words error and cost. Returns the newest
exchanges, oldest first; page backwards for earlier ones.

## Path parameters

- `thread_id` string, uuid, required: The conversation's id, as list_conversations or search_conversations returns it.

## Query parameters

- `before_created_at` string, date-time, nullable: The created_at of the oldest exchange already read; pass with before_id to read earlier ones.
- `before_id` string, uuid, nullable: The id of the oldest exchange already read; pass with before_created_at.
- `limit` integer: The most exchanges to return.

## Response `200`

Successful Response

- ConversationTranscriptResponse: A conversation and a window of its exchanges, read as words.
  - `conversation` ConversationResponse, required: One conversation between the organization's assistant and a visitor to the organization's product.
    - `id` string, uuid, required: The conversation's id.
    - `title` string, required: A short title: the first line of the first message, or its first file's name when it had no text.
    - `owner_end_user_id` string, nullable, required: The organization's own id for the identified visitor; null for an anonymous visitor.
    - `channel` 'web' | 'slack', required: Where a conversation happened.
    - `owner_display_name` string, nullable, required: Who the conversation belongs to where it happened: the person's Slack name for a direct message, or #channel for a Slack channel; null for website visitors.
    - `agent_definition_id` string, uuid, nullable, required: The agent that answered the latest exchange that recorded one; null when none did or the organization's default assistant answered.
    - `agent_name` string, nullable, required: That agent's name; null when the agent is unknown.
    - `last_turn_status` 'queued' | 'working' | 'awaiting_input' | 'succeeded' | 'failed' | 'parked' | 'superseded' | 'stopped', required
    - `turn_count` integer, required: How many exchanges the whole conversation holds.
    - `total_charged_microusd` integer, required: What the conversation cost, in millionths of a US dollar, including work done outside any single exchange.
    - `created_at` string, date-time, required: When the conversation started.
    - `updated_at` string, date-time, required: When the conversation was last active.
  - `turns` TranscriptTurnResponse[], required: The window of exchanges, oldest first. A full window means earlier exchanges may exist: pass the first one's created_at and id as before_created_at and before_id to read them.
    - `id` string, uuid, required: The exchange's id.
    - `status` 'queued' | 'working' | 'awaiting_input' | 'succeeded' | 'failed' | 'parked' | 'superseded' | 'stopped', required
    - `error` string, nullable, required: What stopped the exchange, in plain words; set only when it failed.
    - `charged_microusd` integer, required: What this exchange cost, in millionths of a US dollar.
    - `created_at` string, date-time, required: When the exchange started.
    - `updated_at` string, date-time, required: When the exchange last changed; when it finished, once it has.
    - `entries` TranscriptEntryResponse[], required: The exchange's messages and tool calls, in order.
      - `role` 'user' | 'assistant' | 'tool', required: Who an entry speaks for: the person, the assistant's own text, or one tool call the assistant made.
      - `text` string, nullable, required: The message's words; null for a tool call.
      - `tool` string, nullable, required: The name of the tool called; null for a message.
      - `outcome` 'succeeded' | 'failed' | 'refused' | 'declined' | 'cancelled' | 'pending' | 'unfinished', required: How a tool call ended: succeeded; failed (the tool reported an error); refused (the tool declined and said why); declined (a person turned down the approval it needed); cancelled (it never ran); pending (the turn is still waiting on it); unfinished (it will never answer: the turn ended first, or the assistant retried and called again).
      - `in_progress` boolean, required: True when the assistant is still writing this reply, so its text is partial.
      - `speaker_display_name` string, nullable, required: Who wrote this message, for a Slack conversation; null otherwise.

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `405`: Method not allowed
- `422`: Validation error
- `500`: Internal server error

---

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