curl --request GET \
--url https://api.fanvue.com/v1/agencies/insights/top-fans \
--header 'Authorization: Bearer <token>' \
--header 'X-Fanvue-API-Version: <x-fanvue-api-version>'import requests
url = "https://api.fanvue.com/v1/agencies/insights/top-fans"
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/insights/top-fans', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"data": [
{
"uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"handle": "alex-fan",
"displayName": "Alex Fan",
"avatarUrl": "https://media.fanvue.com/avatars/example-avatar.jpg",
"gross": 124000,
"net": 105400,
"topCreator": {
"uuid": "c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8",
"handle": "sarah-jones"
}
},
{
"uuid": "3bbe6394-2830-4646-a8ba-4a0a05426947",
"handle": "jordan-cool",
"displayName": "Jordan Cool",
"avatarUrl": null,
"gross": 86000,
"net": 73100,
"topCreator": null
}
]
}{
"error": "<string>",
"message": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>",
"message": "<string>",
"nextVersion": "<string>"
}{
"error": "<string>"
}Get the agency's five highest-spending fans
Returns at most five rows: the fans who spent the most across the agency’s creators over the requested date range, best first. Not paginated — ranking is done in the database by earningsView so that the five rows returned are the five highest by the figure you are showing.
A fan can spend across several of the agency’s creators, so gross/net are their combined spend and topCreator is the creator they spent the most on in the range, by the same earnings view. Amounts are USD cents, served from the daily warehouse export for the whole UTC days inside the range and read live from invoices for the current day and either partial edge day.
Every row carries both figures: gross is what the payer paid, net is the creators’ cut after platform fees. Both are already net of refunds and chargebacks, which is stricter than the creator-level /insights/top-spenders. The payer is not always a fan: as on /agencies/insights/demographics, the live branch counts an App Store invoice, which records a creator buying an app from its developer.
curl --request GET \
--url https://api.fanvue.com/v1/agencies/insights/top-fans \
--header 'Authorization: Bearer <token>' \
--header 'X-Fanvue-API-Version: <x-fanvue-api-version>'import requests
url = "https://api.fanvue.com/v1/agencies/insights/top-fans"
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/insights/top-fans', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"data": [
{
"uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"handle": "alex-fan",
"displayName": "Alex Fan",
"avatarUrl": "https://media.fanvue.com/avatars/example-avatar.jpg",
"gross": 124000,
"net": 105400,
"topCreator": {
"uuid": "c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8",
"handle": "sarah-jones"
}
},
{
"uuid": "3bbe6394-2830-4646-a8ba-4a0a05426947",
"handle": "jordan-cool",
"displayName": "Jordan Cool",
"avatarUrl": null,
"gross": 86000,
"net": 73100,
"topCreator": null
}
]
}{
"error": "<string>",
"message": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>",
"message": "<string>",
"nextVersion": "<string>"
}{
"error": "<string>"
}read:agency— Read agency information, including the agency’s team members.read:creator— Access creator profiles, content, and creator-specific information.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
Start of the date range (inclusive). UTC ISO 8601 datetime with offset.
End of the date range (exclusive). UTC ISO 8601 datetime with offset.
Comma-separated list of creator UUIDs to restrict results to a subset of the agency's managed creators (max 50). Every uuid must belong to the agency: one that does not fails the whole request with 403 rather than being ignored. Comma-separated list of creator UUIDs (max 50)
50Which earnings figure to rank by. Both figures are returned on every row regardless.
net, gross Response
The agency's five highest-spending fans
Highest-spending fans, best first, at most five rows
Show child attributes
Show child attributes
Was this page helpful?