Get top-spending fans for a creator | Fanvue API Documentation

import requests
url = "https://api.fanvue.com/creators/creatorUserUuid/insights/top-spenders"
headers = {
    "X-Fanvue-API-Version": "2025-06-26",
    "Authorization": "Bearer <token>"
}
response = requests.get(url, headers=headers)
print(response.json())

{
  "data": [
    {
      "gross": 15000,
      "net": 12750,
      "messages": 342,
      "user": {
        "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "handle": "sarah-jones",
        "displayName": "Sarah Jones",
        "nickname": "SarahK",
        "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",
        "displayName": "Mike Smithly",
        "nickname": "string",
        "isTopSpender": false,
        "avatarUrl": "https://media.fanvue.com/avatars/example-avatar.jpg",
        "registeredAt": "2024-01-10T12:00:00.000Z"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "size": 2,
    "hasMore": true
  }
}

Returns a paginated list of the top-spending fans for the specified creator with their spending totals and message counts.

Scopes required: read:creator, read:insights, read:fan

Returns a paginated list of the top-spending fans for the specified creator with their spending totals and message counts. <Info>Scopes required: `read:creator`, `read:insights`, `read:fan`</Info>

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

creatorUserUuidstringRequiredformat: "uuid"

Query parameters

startDatestringOptionalformat: "date-time"

Start 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).

endDatestringOptionalformat: "date-time"

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.

pagedoubleOptional>=1Defaults to 1

Page number to retrieve (starts from 1)

sizedoubleOptional1-50Defaults to 15

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

Response

Top spending fans with pagination

datalist of objects

Array of top spending fans with their spending totals and message counts

paginationobject

Pagination information

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

410

Gone Error