> ## 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 top-spending fans for a creator (cursor-paginated) > Returns a cursor-paginated list of the top-spending fans for the specified creator with their spending totals and message counts. Cursor-paginated: page with the opaque `nextCursor` from the previous response. The list is ordered by total spend descending, with a stable tiebreak so pages don't overlap or skip when fans have equal totals. Totals are summed over the requested date range, so the range is part of the ordering. The cursor carries it: when `cursor` is supplied, `startDate` and `endDate` are ignored and the walk continues over the range the first page used. Change the range by starting a new walk without a cursor. **Totals are a snapshot taken when the walk started.** Because the sort key is a recomputed sum, the whole walk has to aggregate one fixed set of payments or fans would move between pages and be missed. The first page fixes that set, and every later page reuses it, so the figures you page through stay mutually consistent — but a payment that lands mid-walk is not counted anywhere in it. Start a new walk without a cursor to pick up payments made since. In rare cases a fan can appear on two pages; de-duplicate on the fan `uuid`. **Required scopes** * `read:creator` — Access creator profiles, content, and creator-specific information. * `read:insights` — Access analytics, metrics, and insights data for performance tracking. * `read:fan` — Access fan-related data and information within the platform. ## OpenAPI ````yaml /openapi-v1.json get /v1/creators/{creatorUserUuid}/insights/top-spenders openapi: 3.1.0 info: title: Fanvue API version: '0.1' servers: - url: https://api.fanvue.com security: [] paths: /v1/creators/{creatorUserUuid}/insights/top-spenders: get: summary: Get top-spending fans for a creator (cursor-paginated) description: >- Returns a cursor-paginated list of the top-spending fans for the specified creator with their spending totals and message counts. Cursor-paginated: page with the opaque `nextCursor` from the previous response. The list is ordered by total spend descending, with a stable tiebreak so pages don't overlap or skip when fans have equal totals. Totals are summed over the requested date range, so the range is part of the ordering. The cursor carries it: when `cursor` is supplied, `startDate` and `endDate` are ignored and the walk continues over the range the first page used. Change the range by starting a new walk without a cursor. **Totals are a snapshot taken when the walk started.** Because the sort key is a recomputed sum, the whole walk has to aggregate one fixed set of payments or fans would move between pages and be missed. The first page fixes that set, and every later page reuses it, so the figures you page through stay mutually consistent — but a payment that lands mid-walk is not counted anywhere in it. Start a new walk without a cursor to pick up payments made since. In rare cases a fan can appear on two pages; de-duplicate on the fan `uuid`. operationId: getCreatorTopSpendersV1 parameters: - $ref: '#/components/parameters/ApiVersionHeader' - schema: type: string format: uuid required: true name: creatorUserUuid in: path - schema: type: string description: Opaque pagination cursor from a previous response's `nextCursor` required: false description: Opaque pagination cursor from a previous response's `nextCursor` name: cursor in: query - schema: type: integer minimum: 1 maximum: 50 default: 15 description: 'Number of items to return (1-50, default: 15)' required: false description: 'Number of items to return (1-50, default: 15)' name: size in: query - schema: type: string format: date-time description: >- 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). required: false description: >- 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). name: startDate in: query - schema: type: string format: date-time description: >- 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. required: false description: >- 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. name: endDate in: query responses: '200': description: Cursor-paginated list of top-spending fans content: application/json: schema: type: object properties: data: type: array items: type: object properties: gross: type: number description: >- Total amount this fan paid, in USD cents. Gross of reversals: only positive invoices are counted, so a refunded or charged-back purchase is left in at its full amount rather than subtracted. App Store purchases are counted here as well. Both differ from `spending.total` on /insights/fans/{userUuid}, which is net of reversals and leaves App Store purchases out because they record a creator buying an app from its developer. net: type: number description: >- Creator's total cut from this fan after Fanvue fees, in USD cents. Same reversal treatment as `gross`: fees are the only thing taken off. messages: type: number description: Number of messages exchanged with this fan user: type: object properties: uuid: type: string format: uuid handle: type: string displayName: type: string nickname: type: - string - 'null' isTopSpender: type: boolean avatarUrl: type: - string - 'null' registeredAt: type: string format: date-time required: - uuid - handle - displayName - nickname - isTopSpender - avatarUrl - registeredAt description: Fan's user information required: - gross - net - messages - user description: Top-spending fans, highest total spend first nextCursor: type: - string - 'null' description: >- Opaque cursor for the next page, or null when there are no more results total: type: - number - 'null' description: >- Total number of items, or null when a count is not computed for this list required: - data - nextCursor - total example: data: - gross: 15000 net: 12750 messages: 342 user: uuid: f47ac10b-58cc-4372-a567-0e02b2c3d479 handle: sarah-jones nickname: SarahK displayName: Sarah Jones 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 nickname: null displayName: Mike Smithly isTopSpender: false avatarUrl: https://media.fanvue.com/avatars/example-avatar.jpg registeredAt: '2024-01-10T12:00:00.000Z' nextCursor: null total: null '400': description: >- Bad Request - API version not supported OR validation failed (dates, sources, cursor, pagination) OR invalid UUID content: application/json: schema: oneOf: - $ref: '#/components/schemas/UnsupportedVersionError' - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/InvalidUuidError' '401': $ref: '#/components/responses/UnauthorizedResponse' '403': $ref: '#/components/responses/UnauthorizedResponse' '404': $ref: '#/components/responses/NotFoundResponse' '410': $ref: '#/components/responses/SunsetVersionResponse' '429': $ref: '#/components/responses/RateLimitResponse' security: - BearerAuth: - read:creator - read:insights - 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 InvalidUuidError: type: object properties: message: type: string required: - message description: Invalid UUID format provided responses: UnauthorizedResponse: description: Unauthorized Response content: application/json: schema: type: object properties: error: type: string required: - error NotFoundResponse: description: Not Found Response content: application/json: schema: type: object properties: message: type: string required: - message 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. ````