---
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 from the daily warehouse export.
<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.net/fanvue/apis/fanvue-api.md) · [All operations](https://skmtc.net/fanvue/apis/fanvue-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/fanvue/fanvue-api/revisions/c5ddcd5c7e72/schema)