> ## Documentation Index
> Fetch the complete documentation index at: https://api.fanvue.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
Requires: Agency admin access
**Required scopes**
* `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.
## OpenAPI
````yaml /openapi-v1.json get /v1/agencies/insights/top-fans
openapi: 3.1.0
info:
title: Fanvue API
version: '0.1'
servers:
- url: https://api.fanvue.com
security: []
paths:
/v1/agencies/insights/top-fans:
get:
summary: Get the agency's five highest-spending fans
description: >-
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.
Requires: Agency admin access
operationId: getAgencyTopFans
parameters:
- $ref: '#/components/parameters/ApiVersionHeader'
- schema:
type: string
format: date-time
description: >-
Start of the date range (inclusive). UTC ISO 8601 datetime with
offset.
required: true
description: >-
Start of the date range (inclusive). UTC ISO 8601 datetime with
offset.
name: startDate
in: query
- schema:
type: string
format: date-time
description: >-
End of the date range (exclusive). UTC ISO 8601 datetime with
offset.
required: true
description: >-
End of the date range (exclusive). UTC ISO 8601 datetime with
offset.
name: endDate
in: query
- schema:
type: array
items:
type: string
format: uuid
maxItems: 50
description: Comma-separated list of creator UUIDs (max 50)
required: false
description: >-
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.
name: creatorUuids
in: query
style: form
explode: false
- schema:
type: string
enum:
- net
- gross
default: gross
description: >-
Which earnings figure to rank by. Both figures are returned on
every row regardless.
required: false
description: >-
Which earnings figure to rank by. Both figures are returned on every
row regardless.
name: earningsView
in: query
responses:
'200':
description: The agency's five highest-spending fans
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
uuid:
type: string
format: uuid
description: UUID of the fan
handle:
type: string
description: Fan's handle on the platform
displayName:
type: string
description: Fan's display name
avatarUrl:
type:
- string
- 'null'
description: URL of the fan's avatar image, or null
gross:
type: integer
description: >-
Gross spend by this fan across the agency's creators
in the range, net of refunds and chargebacks. USD
cents.
net:
type: integer
description: >-
Net spend by this fan across the agency's creators
in the range, net of refunds and chargebacks. USD
cents.
topCreator:
type:
- object
- 'null'
properties:
uuid:
type: string
format: uuid
description: UUID of the creator
handle:
type: string
description: Creator's handle on the platform
required:
- uuid
- handle
description: >-
The agency creator this fan spent the most on in the
date range, by the same earnings view, or null if it
cannot be resolved
required:
- uuid
- handle
- displayName
- avatarUrl
- gross
- net
- topCreator
description: Highest-spending fans, best first, at most five rows
required:
- data
example:
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
'400':
description: >-
Bad Request - API version not supported OR validation failed (dates,
sources, cursor, pagination)
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/UnsupportedVersionError'
- $ref: '#/components/schemas/ValidationError'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/UnauthorizedResponse'
'410':
$ref: '#/components/responses/SunsetVersionResponse'
'429':
$ref: '#/components/responses/RateLimitResponse'
security:
- BearerAuth:
- read:agency
- read:creator
- read:fan
components:
parameters:
ApiVersionHeader:
name: X-Fanvue-API-Version
in: header
required: true
schema:
type: string
default: '2025-06-26'
example: '2025-06-26'
description: API version to use for the request
schemas:
UnsupportedVersionError:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
- message
description: API version not supported
ValidationError:
type: object
properties:
errors:
type: array
items:
type: string
required:
- errors
description: Request validation failed
responses:
UnauthorizedResponse:
description: Unauthorized Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
SunsetVersionResponse:
description: API version no longer supported (sunset)
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
nextVersion:
type: string
required:
- error
- message
RateLimitResponse:
description: Too many requests - rate limit exceeded
headers:
Retry-After:
description: Number of seconds to wait before retrying the request
schema:
type: integer
X-RateLimit-Limit:
description: The maximum number of requests allowed in the current window
schema:
type: integer
X-RateLimit-Remaining:
description: The number of requests remaining in the current window
schema:
type: integer
X-RateLimit-Reset:
description: The Unix timestamp (seconds) when the rate limit window resets
schema:
type: integer
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
securitySchemes:
BearerAuth:
type: oauth2
description: >-
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.
flows:
authorizationCode:
authorizationUrl: https://auth.fanvue.com/oauth2/auth
tokenUrl: https://auth.fanvue.com/oauth2/token
refreshUrl: https://auth.fanvue.com/oauth2/token
scopes:
read:self: >-
Access your own user profile information, including basic account
details and settings.
read:chat: >-
Read chat conversations, messages, and chat-related data. This
includes viewing chat lists and message history.
write:chat: >-
Create new chats and send messages. This scope is required for any
chat-related actions that modify data.
read:experience: >-
Exchange a fan's experience token for the resolved experience and
the fan's identity, so an embedded fan-facing experience can
render the right content.
write:experience: >-
Request that the creator publish or unpublish a fan-facing
experience. The app mints a request token; the creator confirms
and Fanvue performs the change.
read:fan: Access fan-related data and information within the platform.
read:post: Read posts, including post details, comments, likes, and tips.
write:post: Create, edit, and manage posts and content on behalf of users.
read:media: Access media files, images, videos, and other content assets.
write:media: >-
Upload, modify, and manage media files and content assets. Also
required for vault folder management.
read:creator: >-
Access creator profiles, content, and creator-specific
information.
write:creator: Modify creator profiles, settings, and creator-specific data.
read:insights: >-
Access analytics, metrics, and insights data for performance
tracking.
read:tracking_links: >-
Read tracking links and the users associated with them, including
per-user tracking metadata.
write:tracking_links: Create and delete tracking links.
read:agency: Read agency information, including the agency's team members.
write:agency: >-
Manage agency team members and invites, including inviting new
team members and creators.
````