---
title: "List conversations"
method: GET
path: "/api/v1/conversations"
tags: ["authed"]
---

# List conversations

`GET /api/v1/conversations`

## 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`
- Auth: none declared

Browse the organization's assistant conversations with visitors,
most recently active first, by time, agent or how the latest exchange
ended. Use search_conversations when you know words the visitor typed;
read a conversation in full with get_conversation_transcript. A full
page means more may exist.

## Query parameters

- `agent_definition_id` string, uuid, nullable: Only conversations whose agent_definition_id is this id.
- `since` string, date-time, nullable: Only conversations last active at or after this time (ISO 8601; a date or a time without a zone is read as UTC).
- `until` string, date-time, nullable: Only conversations last active before this time (ISO 8601; a date or a time without a zone is read as UTC).
- `status` 'queued' | 'working' | 'awaiting_input' | 'succeeded' | 'failed' | 'parked' | 'superseded' | 'stopped'
- `before_updated_at` string, date-time, nullable: The updated_at of the last row of the previous page; pass with before_id to fetch the next page.
- `before_id` string, uuid, nullable: The id of the last row of the previous page; pass with before_updated_at to fetch the next page.
- `limit` integer: The most conversations to return.

## Response `200`

Successful Response

- ConversationResponse[]
  - `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.

## 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)