List chats across all agency creators (cursor-paginated, filterable)

curl --request GET \
  --url https://api.fanvue.com/v1/agencies/chats \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Fanvue-API-Version: <x-fanvue-api-version>'

import requests

url = "https://api.fanvue.com/v1/agencies/chats"

headers = {
    "X-Fanvue-API-Version": "<x-fanvue-api-version>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {
    'X-Fanvue-API-Version': '<x-fanvue-api-version>',
    Authorization: 'Bearer <token>'
  }
};

fetch('https://api.fanvue.com/v1/agencies/chats', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": [
    {
      "createdAt": "2024-01-15T00:00:00.000Z",
      "lastMessageAt": "2024-01-15T00:00:00.000Z",
      "isRead": false,
      "isMuted": false,
      "unreadMessagesCount": 3,
      "creatorUuid": "c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8",
      "user": {
        "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "handle": "sarah-jones",
        "nickname": "SarahK",
        "displayName": "Sarah Jones",
        "isTopSpender": true,
        "avatarUrl": "https://media.fanvue.com/avatars/example-avatar.jpg",
        "registeredAt": "2024-01-10T12:00:00.000Z"
      },
      "lastMessage": {
        "uuid": "a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6",
        "text": "Hey there! How are you doing?",
        "type": "SINGLE_RECIPIENT",
        "sentAt": "2024-01-15T00:00:00.000Z",
        "hasMedia": true,
        "hasGif": false,
        "mediaType": "image",
        "senderUuid": "c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8",
        "senderRole": "CREATOR",
        "sentByUserId": null
      }
    }
  ],
  "nextCursor": "k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "nextVersion": "<string>"
}

{
  "error": "<string>"
}

Agency Insights

List chats across all agency creators (cursor-paginated, filterable)

Cursor-paginated stream of chats across every creator the authenticated agency manages, with full filter parity to the creator-self GET /chats. Each row is tagged with creatorUuid.

Every filter is correlated to the chat’s own creator: filter=subscribers returns chats whose counterpart is a subscriber of that chat’s creator, not of any agency creator.

Designed for incremental sync: pass updatedAfter (and walk asc) to pull only chats that changed since the last sync, then page with the opaque nextCursor. For the default recency sort the cursor is a keyset position, so deep pages cost the same as the first and a page is never shifted by chats added or removed above it — unlike offset paging. It is not a snapshot: the position is lastMessageAt, which moves when a chat receives activity, so a chat can still be missed (walking desc, it moves above a cursor already passed) or returned twice (walking asc, it moves below one). Deduplicate by creatorUuid + user.uuid if you need exactly-once. A cursor is only valid for the sortBy and sortDirection it was minted under; reusing it under different sorting returns 400.

Supported filter[] values: unread, subscribers, followers, online, recent_subscribers, not_answered, spent_more_than_50, on_free_trial, has_tipped, spenders, exclude_creators, subscribed_to, not_muted, muted, archived. Per-creator list filters (customListId, smartListIds) are intentionally omitted — they have no meaning in a cross-creator aggregate.

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

sortBy composes with search, filter and updatedAfter. online_now and most_unanswered_chats rank on live values with no stable position to resume from, so their pages are addressed by an offset carried inside the same opaque cursor: a chat whose presence or unread count changes mid-traversal can be repeated or passed by. Re-request the first page for a fresh ranking.

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)
Requires: Agency admin access

GET

agencies

chats

List chats across all agency creators (cursor-paginated, filterable)

curl --request GET \
  --url https://api.fanvue.com/v1/agencies/chats \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Fanvue-API-Version: <x-fanvue-api-version>'

import requests

url = "https://api.fanvue.com/v1/agencies/chats"

headers = {
    "X-Fanvue-API-Version": "<x-fanvue-api-version>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {
    'X-Fanvue-API-Version': '<x-fanvue-api-version>',
    Authorization: 'Bearer <token>'
  }
};

fetch('https://api.fanvue.com/v1/agencies/chats', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": [
    {
      "createdAt": "2024-01-15T00:00:00.000Z",
      "lastMessageAt": "2024-01-15T00:00:00.000Z",
      "isRead": false,
      "isMuted": false,
      "unreadMessagesCount": 3,
      "creatorUuid": "c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8",
      "user": {
        "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "handle": "sarah-jones",
        "nickname": "SarahK",
        "displayName": "Sarah Jones",
        "isTopSpender": true,
        "avatarUrl": "https://media.fanvue.com/avatars/example-avatar.jpg",
        "registeredAt": "2024-01-10T12:00:00.000Z"
      },
      "lastMessage": {
        "uuid": "a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6",
        "text": "Hey there! How are you doing?",
        "type": "SINGLE_RECIPIENT",
        "sentAt": "2024-01-15T00:00:00.000Z",
        "hasMedia": true,
        "hasGif": false,
        "mediaType": "image",
        "senderUuid": "c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8",
        "senderRole": "CREATOR",
        "sentByUserId": null
      }
    }
  ],
  "nextCursor": "k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "nextVersion": "<string>"
}

{
  "error": "<string>"
}

Required scopes

read:agency — Read agency information, including the agency’s team members.
read:chat — Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history.

Authorizations

Authorization

string

header

required

OAuth 2.0 access token, presented as a JWT bearer token in the Authorization header. Obtain a token via the authorization-code flow; the scopes granted to the token determine which operations it may call.

Headers

X-Fanvue-API-Version

string

default:2025-06-26

required

API version to use for the request

Example:

"2025-06-26"

Query Parameters

cursor

string

Opaque pagination cursor from a previous response's nextCursor

size

number

default:15

Number of items to return (1-50, default: 15)

Required range: 1 <= x <= 50

updatedAfter

string<date-time>

Incremental sync: only return chats with activity strictly after this timestamp. Chats with no messages are excluded.

string

Search term to filter chats by counterpart name or handle

Maximum string length: 100

filter

enum<string>[]

Filter types to apply, correlated to each chat's own creator (repeat the param for multiple)

Available options:

unread,

subscribers,

followers,

online,

recent_subscribers,

not_answered,

spent_more_than_50,

on_free_trial,

has_tipped,

spenders,

exclude_creators,

subscribed_to,

not_muted,

muted,

archived

sortBy

enum<string>

Sort order for the chat list (default: most_recent_messages)

Available options:

most_recent_messages,

online_now,

most_unanswered_chats

sortDirection

enum<string>

Sort direction: desc (highest-ranked first, default) or asc (reversed, for backfills)

Available options:

asc,

desc

Response

Cursor-paginated list of chats across the agency's creators

data

object[]

required

Array of chats across the agency's creators, in the requested sort order

Show child attributes

nextCursor

string | null

required

Cursor for the next page, or null when there are no more results

Overview

Popular endpoints

Account

Chats

Notifications

Posts

Creator Tools

Insights & Earnings

Onboarding

Experiences

Webhooks

Agency

List chats across all agency creators (cursor-paginated, filterable)

Authorizations

Headers

Query Parameters

Response