---
title: "Get list of chats"
method: GET
path: "/chats"
---

# Get list of chats

`GET /chats`

Returns a paginated list of chat conversations with optional filtering, searching, and sorting.

**Available Filters** (via `filter` parameter):
- `unread` - Only unread chats
- `online` - Only online users
- `subscribed_to` - Users you're subscribed to
- `not_muted` - Exclude muted chats
- `muted` - Only muted chats
- `subscribers` - Only subscribers (creator-only)
- `followers` - Only followers (creator-only)
- `recent_subscribers` - Recently subscribed (creator-only)
- `not_answered` - Unanswered chats (creator-only)
- `spent_more_than_50` - High spenders (creator-only)
- `on_free_trial` - Free trial users (creator-only)
- `has_tipped` - Users who have tipped (creator-only)
- `spenders` - All spenders (creator-only)
- `exclude_creators` - Exclude creator accounts (creator-only)

**Sort Options** (via `sortBy` parameter):
- `most_recent_messages` (default) - Sort by most recent message
- `online_now` - Prioritize online users
- `most_unanswered_chats` - Sort by unanswered count

**Sort Direction** (via `sortDirection` parameter):
- `desc` (default) - Highest-ranked chats first (most recent / most online / most unanswered)
- `asc` - Reverses the order (least recent / least online / fewest unanswered)

<Warning>Some filters are only available to creators. Using creator-only filters as a non-creator will return a 403 error.</Warning>

## Query parameters

- `page` integer — Page number to retrieve (starts from 1)
- `size` integer — Number of items to return per page (1-50, default: 15)
- `customListId` string, uuid — Filter chats by custom list UUID
- `userUuids` string[] — Filter chats to these counterpart (fan) user UUIDs (repeat the param for multiple, max 100)
- `smartListIds` string[] — Filter chats by smart list type(s)
- `filter` string[] — Filter types to apply (can specify multiple via repeated params)
- `search` string — Search term to filter chats by user name/handle
- `sortBy` 'most_recent_messages' | 'online_now' | 'most_unanswered_chats' — Sort order for chat list (default: most_recent_messages)
- `sortDirection` 'asc' | 'desc' — Sort direction for chat list (default: desc)

## Headers

- `X-Fanvue-API-Version` string, required

## Response `200`

List of chats

- object
  - `data` object[], required — Array of chat conversations
    - `createdAt` string, date, nullable, required
    - `lastMessageAt` string, date, nullable, required — Date of the last message in this chat
    - `isRead` boolean, required — Whether the chat is read. Authoritative for unread badges: it is false either when unread messages exist or when the chat was manually marked unread via PATCH /chats/{userUuid}, in which case `unreadMessagesCount` stays 0.
    - `isMuted` boolean, required
    - `unreadMessagesCount` number, required — Number of messages in this chat the authenticated user has not read. 0 for a chat that was manually marked unread — use `isRead` for badge state.
    - `user` object, required
      - `uuid` string, uuid, required
      - `handle` string, required
      - `displayName` string, required
      - `nickname` string, nullable, required
      - `isTopSpender` boolean, required
      - `avatarUrl` string, nullable, required
      - `registeredAt` string, date-time, required
    - `lastMessage` object, nullable, required
      - `text` string, nullable, required
      - `type` 'AUTOMATED_CANCELED' | 'AUTOMATED_NEW_FOLLOWER' | 'AUTOMATED_NEW_PURCHASE' | 'AUTOMATED_NEW_SUBSCRIBER' | 'AUTOMATED_RE_SUBSCRIBED' | 'AUTOMATED_RENEWED' | 'AUTOMATED_CHAT_MESSAGE_REPLY' | 'AUTOMATED_FIRST_MESSAGE_REPLY' | 'CHAT_TEXT_GENERATION' | 'CHAT_TEXT_REPLY' | 'CHAT_TEXT_REWRITE' | 'SINGLE_RECIPIENT' | 'TIP' | 'VOICE_CALL' | 'BROADCAST' | 'GHOST_PROMOTION', required
      - `uuid` string, required
      - `sentAt` string, date, nullable, required
      - `hasMedia` boolean, nullable, required
      - `hasGif` boolean, required — Whether the last message is a GIF message. Its text may still be set as a caption. Fetch the message to get the GIF itself.
      - `mediaType` 'image' | 'video' | 'audio' | 'document', nullable, required
      - `senderUuid` string, uuid, required
      - `senderRole` 'FAN' | 'CREATOR' | 'AGENCY' | 'SYSTEM', required — Who sent the last message: CREATOR (the creator, sent directly), AGENCY (a team member sent it on the creator's behalf), FAN (the counterpart fan) or SYSTEM (an automated/platform message such as a subscription automation or KYC prompt).
      - `sentByUserId` string, uuid, nullable, required — UUID of the team member who sent the message on behalf of the creator, or null if sent directly by the creator
      - `status` 'Sent' | 'Delivered' | 'Read', nullable — Delivery status of the last message from the sender's perspective: Sent (still in flight), Delivered (sent but not yet read by the recipient) or Read. Null when the last message was received by the authenticated user (inbound).
    - `isCreator` boolean — Whether the chat counterpart is also a creator on the platform
    - `online` boolean — Whether the counterpart is currently online. Provided inline to avoid a separate /chats/statuses request.
    - `lastSeenAt` string, date, nullable — When the counterpart was last seen online, or null if unknown/hidden
    - `customLists` object[] — Custom lists owned by the authenticated user that the counterpart belongs to
      - `uuid` string, uuid, required — Custom list UUID
      - `name` string, required — Custom list name
  - `pagination` object, required — Pagination information
    - `page` number, required — Current page number
    - `size` number, required — Number of records returned in this response
    - `hasMore` boolean, required — Whether there are more items available on subsequent pages

## Other responses

- `400` — Bad Request - API version not supported OR validation failed
- `401` — Unauthorized Response
- `403` — Unauthorized Response
- `410` — API version no longer supported (sunset)
- `429` — Too many requests - rate limit exceeded

---

[API](https://skmtc.net/fanvue/apis/fanvue-api.md) · [All operations](https://skmtc.net/fanvue/apis/fanvue-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/fanvue/fanvue-api/revisions/c5ddcd5c7e72/schema)