curl --request GET \
--url https://api.fanvue.com/v1/insights/top-spenders \
--header 'Authorization: Bearer <token>' \
--header 'X-Fanvue-API-Version: <x-fanvue-api-version>'import requests
url = "https://api.fanvue.com/v1/insights/top-spenders"
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/insights/top-spenders', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"data": [
{
"gross": 15000,
"net": 12750,
"messages": 342,
"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"
}
},
{
"gross": 8500,
"net": 7225,
"messages": 189,
"user": {
"uuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"handle": "mike-smith",
"nickname": null,
"displayName": "Mike Smithly",
"isTopSpender": false,
"avatarUrl": "https://media.fanvue.com/avatars/example-avatar.jpg",
"registeredAt": "2024-01-10T12:00:00.000Z"
}
}
],
"nextCursor": null,
"total": null
}{
"error": "<string>",
"message": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>",
"message": "<string>",
"nextVersion": "<string>"
}{
"error": "<string>"
}Get top-spending fans (cursor-paginated)
Returns a cursor-paginated list of the top-spending fans for the authenticated creator with their spending totals and message counts.
Cursor-paginated: page with the opaque nextCursor from the previous response. The list is ordered by total spend descending, with a stable tiebreak so pages don’t overlap or skip when fans have equal totals.
Totals are summed over the requested date range, so the range is part of the ordering. The cursor carries it: when cursor is supplied, startDate and endDate are ignored and the walk continues over the range the first page used. Change the range by starting a new walk without a cursor.
Totals are a snapshot taken when the walk started. Because the sort key is a recomputed sum, the whole walk has to aggregate one fixed set of payments or fans would move between pages and be missed. The first page fixes that set, and every later page reuses it, so the figures you page through stay mutually consistent — but a payment that lands mid-walk is not counted anywhere in it. Start a new walk without a cursor to pick up payments made since. In rare cases a fan can appear on two pages; de-duplicate on the fan uuid.
curl --request GET \
--url https://api.fanvue.com/v1/insights/top-spenders \
--header 'Authorization: Bearer <token>' \
--header 'X-Fanvue-API-Version: <x-fanvue-api-version>'import requests
url = "https://api.fanvue.com/v1/insights/top-spenders"
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/insights/top-spenders', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"data": [
{
"gross": 15000,
"net": 12750,
"messages": 342,
"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"
}
},
{
"gross": 8500,
"net": 7225,
"messages": 189,
"user": {
"uuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"handle": "mike-smith",
"nickname": null,
"displayName": "Mike Smithly",
"isTopSpender": false,
"avatarUrl": "https://media.fanvue.com/avatars/example-avatar.jpg",
"registeredAt": "2024-01-10T12:00:00.000Z"
}
}
],
"nextCursor": null,
"total": null
}{
"error": "<string>",
"message": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>",
"message": "<string>",
"nextVersion": "<string>"
}{
"error": "<string>"
}read:insights— Access analytics, metrics, and insights data for performance tracking.read:fan— Access fan-related data and information within the platform.
Authorizations
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
API version to use for the request
"2025-06-26"
Query Parameters
Opaque pagination cursor from a previous response's nextCursor
Number of items to return (1-50, default: 15)
1 <= x <= 50Start date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-20T00:00:00+01:00 or 2024-10-20T00:00:00Z).
End date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-25T00:00:00+01:00 or 2024-10-25T00:00:00Z). Non-inclusive - data before this date is included.
Response
Cursor-paginated list of top-spending fans
Was this page helpful?