> This page is for Voice APIs.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://dev.hume.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://dev.hume.ai/_mcp/server.

# List chats

GET https://api.hume.ai/v0/evi/chats

Fetches a paginated list of **Chats**.

Reference: https://dev.hume.ai/voice/reference/speech-to-speech-evi/chats/list-chats

## Authentication

- `X-Hume-Api-Key` header (required) — API Key authentication via header

## Request

### Query parameters

- `page_number` (integer, optional, default: 0) — Specifies the page number to retrieve, enabling pagination. This parameter uses zero-based indexing. For example, setting `page_number` to 0 retrieves the first page of results (items 0-9 if `page_size` is 10), setting `page_number` to 1 retrieves the second page (items 10-19), and so on. Defaults to 0, which retrieves the first page.
- `page_size` (integer, optional) — Specifies the maximum number of results to include per page, enabling pagination. The value must be between 1 and 100, inclusive. For example, if `page_size` is set to 10, each page will include up to 10 items. Defaults to 10.
- `ascending_order` (boolean, optional) — Specifies the sorting order of the results based on their creation date. Set to true for ascending order (chronological, with the oldest records first) and false for descending order (reverse-chronological, with the newest records first). Defaults to true.
- `config_id` (string, optional) — Filter to only include chats that used this config.
- `status` (string, optional) — Chat status to apply to the chat. String from the ChatStatus enum.

## Response

### 200

Success

- `chats_page` (list of return_chat, required) — List of Chats and their metadata returned for the specified `page_number` and `page_size`.
- `page_number` (integer, required) — The page number of the returned list. This value corresponds to the `page_number` parameter specified in the request. Pagination uses zero-based indexing.
- `page_size` (integer, required) — The maximum number of items returned per page. This value corresponds to the `page_size` parameter specified in the request.
- `pagination_direction` (enum, required)
  - Allowed values: `ASC`, `DESC`
- `total_pages` (integer, required) — The total number of pages in the collection.

## Types

### return_chat

A description of chat and its status

- `chat_group_id` (string, required) — Identifier for the Chat Group. Any chat resumed from this Chat will have the same `chat_group_id`. Formatted as a UUID.
- `id` (string, required) — Identifier for a Chat. Formatted as a UUID.
- `start_timestamp` (long, required) — Time at which the Chat started. Measured in seconds since the Unix epoch.
- `status` (enum, required)
  - Allowed values: `ACTIVE`, `USER_ENDED`, `USER_TIMEOUT`, `MAX_DURATION_TIMEOUT`, `INACTIVITY_TIMEOUT`, `ERROR`
- `config` (return_config_spec, optional) — The Config associated with this Chat.
- `end_timestamp` (long, optional, nullable) — Time at which the Chat ended. Measured in seconds since the Unix epoch.
- `event_count` (long, optional, nullable) — The total number of events currently in this chat.
- `metadata` (string, optional, nullable) — Stringified JSON with additional metadata about the chat.

### return_config_spec

The Config associated with this Chat.

- `id` (string, required) — Identifier for a Config. Formatted as a UUID.
- `version` (integer, optional, nullable) — Version number for a Config. Configs, Prompts, Custom Voices, and Tools are versioned. This versioning system supports iterative development, allowing you to progressively refine configurations and revert to previous versions if needed. Version numbers are integer values representing different iterations of the Config. Each update to the Config increments its version number.

## Examples

**Response**

```json
{
  "chats_page": [
    {
      "chat_group_id": "9fc18597-3567-42d5-94d6-935bde84bf2f",
      "id": "470a49f6-1dec-4afe-8b61-035d3b2d63b0",
      "start_timestamp": 1716244940648,
      "status": "USER_ENDED",
      "config": {
        "id": "1b60e1a0-cc59-424a-8d2c-189d354db3f3",
        "version": 0
      },
      "end_timestamp": 1716244958546,
      "event_count": 3,
      "metadata": ""
    }
  ],
  "page_number": 0,
  "page_size": 1,
  "pagination_direction": "ASC",
  "total_pages": 1
}
```