---
title: "Get the agency's five highest-spending fans"
method: GET
path: "/agencies/insights/top-fans"
---

# Get the agency's five highest-spending fans

`GET /agencies/insights/top-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.
<Info>Requires: Agency admin access</Info>

## Query parameters

- `startDate` string, date-time, required — Start of the date range (inclusive). UTC ISO 8601 datetime with offset.
- `endDate` string, date-time, required — End of the date range (exclusive). UTC ISO 8601 datetime with offset.
- `creatorUuids` string[] — Comma-separated list of creator UUIDs (max 50)
- `earningsView` 'net' | 'gross' — Which earnings figure to rank by. Both figures are returned on every row regardless.

## Headers

- `X-Fanvue-API-Version` string, required

## Response `200`

The agency's five highest-spending fans

- object
  - `data` object[], required — Highest-spending fans, best first, at most five rows
    - `uuid` string, uuid, required — UUID of the fan
    - `handle` string, required — Fan's handle on the platform
    - `displayName` string, required — Fan's display name
    - `avatarUrl` string, nullable, required — URL of the fan's avatar image, or null
    - `gross` integer, required — Gross spend by this fan across the agency's creators in the range, net of refunds and chargebacks. USD cents.
    - `net` integer, required — Net spend by this fan across the agency's creators in the range, net of refunds and chargebacks. USD cents.
    - `topCreator` object, nullable, required — 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
      - `uuid` string, uuid, required — UUID of the creator
      - `handle` string, required — Creator's handle on the platform

## Other responses

- `400` — Bad Request - API version not supported OR validation failed (dates, sources, cursor, pagination)
- `401` — Unauthorized Response
- `403` — Unauthorized Response
- `410` — API version no longer supported (sunset)
- `429` — Too many requests - rate limit exceeded

---

[API](https://skmtc.dev/fanvue/apis/fanvue-api.md) · [All operations](https://skmtc.dev/fanvue/apis/fanvue-api/llms.txt) · [OpenAPI document](https://skmtc.dev/fanvue/apis/fanvue-api/revisions/431868e8a264?raw)