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

# Search conversations

`GET /api/v1/conversations/search`

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

Find the organization's assistant conversations in which a visitor
wrote the given words, most recently active first, each with an
excerpt of the newest matching message. Use list_conversations to
browse by time, agent or outcome instead; read a conversation in full
with get_conversation_transcript. Very common words alone match
nothing. A full page means more matches may exist.

## Query parameters

- `query` string, required: Words the visitor typed; other forms of a word match too. Put a phrase in "double quotes", and put - before a word to exclude it.
- `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).
- `agent_definition_id` string, uuid, nullable: Only conversations whose agent_definition_id is this id.
- `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

- ConversationSearchResultResponse[]
  - `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.
  - `snippet` string, required: An excerpt of the newest visitor message that matched the query.

## Other responses

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

## Changes

- **2026-11-03** `c6ac9fd6657f`: 6 info
  - removed the `STEEP_LEARNING_DISABLED` enum value from the `error/code` response property for the response status `401`
  - removed the `STEEP_LEARNING_DISABLED` enum value from the `error/code` response property for the response status `403`
  - removed the `STEEP_LEARNING_DISABLED` enum value from the `error/code` response property for the response status `404`
  - removed the `STEEP_LEARNING_DISABLED` enum value from the `error/code` response property for the response status `405`
  - …2 more

[Operation history](https://skmtc.dev/teaflask/apis/teaflask-api/changes/api/v1/conversations/search/get.md)

---

[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/c6ac9fd6657f?raw)