---
title: "List a business's chats"
method: GET
path: "/api/v1/chats"
tags: ["chats"]
---

# List a business's chats

`GET /api/v1/chats`

## Request

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

Returns the business's conversations with paging, and optional filters for kind and assistant. The business is taken from the `business-id` header rather than the URL; the path-scoped form of this operation is deprecated.

## Query parameters

- `kind` string: Filter by Chat.kind. 'trainer' (default) returns sandbox conversations from the AI Trainer UI; 'real' returns customer conversations created from WhatsApp webhooks; 'all' returns both. The default is 'trainer' to preserve the historical behavior of this endpoint, which was trainer-only via a consumer-nickname heuristic.
- `page` integer: 1-based page number for chat pagination (used by the trainer's infinite scroll).
- `page_size` integer: Number of chats to return per page (default 30, max 100).
- `messages_per_chat` integer: How many of the most-recent messages to embed per chat. Defaults to 1, which is enough for the list's last-message preview and ordering. Full conversation threads should be fetched on demand from GET /chats/{chat_id}/messages (paginated) rather than over-fetched here — embedding the whole thread for every chat on the page made this endpoint load thousands of messages per request.
- `refine_queue` string, nullable: Refine trainer queue filter for kind=real. 'pending' = no OK review and no issues; 'reviewed' = has OK review or any issue.
- `chatbot_id` string, uuid, nullable: Optional assistant ID to filter chats by (per-assistant trainer from dash).
- `since` string, date-time, nullable: ISO-8601 timestamp. When set, only chats whose last activity (the same timestamp this list orders by) is strictly *newer than* `since` are returned — exclusive, not inclusive, so polling with `since=<last seen timestamp>` never returns a chat already seen. For incremental sync: pass the newest `timestamp` from the previous response as `since` on the next poll instead of refetching and diffing a full page client-side.

## Headers

- `business-id` string, nullable, required: UUID of the business the request is scoped to. Required on this route; the deprecated /businesses/{business_id}/... form takes it from the path instead.

## Response `200`

Successful Response

- ChatListOut
  - `chats` ChatOut[], required
    - `id` string, uuid, required
    - `conversation_id` string, uuid, nullable
    - `business_id` string, uuid, required
    - `session_id` string, uuid, required
    - `last_message` LastMessageOut
      - `status` string, required
      - `content` string, required
      - `no_reply` boolean
    - `timestamp` string, date-time, required
    - `messages` unknown[], required
      - unknown
    - `created` string, date-time, required
    - `instructions` unknown[], nullable
      - unknown
    - `custom_instructions` unknown[], nullable
      - unknown
    - `kind` string
    - `consumer` ChatConsumerOut
      - `id` string, uuid, required
      - `nickname` string, nullable
      - `phone_number` string, nullable
    - `refine_reviewed` boolean
    - `refine_verdict` string, nullable
  - `pagination` PaginationMeta, required
    - `page` integer, required
    - `page_size` integer, required
    - `total_count` integer, required
    - `total_pages` integer, required
    - `has_next` boolean, required
    - `has_previous` boolean, required

## Other responses

- `401`: Missing or invalid credentials.
- `403`: The credential is valid but not authorized for this action.
- `404`: The resource, or the business named in the request, does not exist.
- `422`: Validation Error
- `default`: Unexpected error.

---

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