> ## 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 fan insights for a creator > Returns detailed insights about a specific fan for the specified creator, including spending statistics, subscription status, and fan engagement metrics. **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/fans/{userUuid} openapi: 3.1.0 info: title: Fanvue API version: '0.1' servers: - url: https://api.fanvue.com security: [] paths: /v1/creators/{creatorUserUuid}/insights/fans/{userUuid}: get: summary: Get fan insights for a creator description: >- Returns detailed insights about a specific fan for the specified creator, including spending statistics, subscription status, and fan engagement metrics. operationId: getCreatorFanInsights parameters: - $ref: '#/components/parameters/ApiVersionHeader' - schema: type: string format: uuid required: true name: creatorUserUuid in: path - schema: type: string format: uuid description: Fan's UUID required: true description: Fan's UUID name: userUuid in: path responses: '200': description: Fan insights data content: application/json: schema: type: object properties: status: type: string enum: - subscriber - expired - follower - not_contactable description: Current fan status spending: type: object properties: lastPurchaseAt: type: - string - 'null' format: date-time description: >- When this fan last paid this creator (ISO 8601), or null if they never have. Fan-initiated payments only, so an automatic subscription renewal never moves it, and App Store purchases do not count as a purchase here. Reversed purchases are NOT skipped: a purchase later refunded or charged back still counts as the last purchase, because the fan did reach for their wallet at that moment, which makes this recency of intent rather than recency of valid spend. Use `lastValidPurchaseAt` for the latter. lastValidPurchaseAt: type: - string - 'null' format: date-time description: >- Same as `lastPurchaseAt` but skipping purchases later refunded or charged back, so this is recency of valid spend. Null when every self-initiated purchase was reversed. total: type: object properties: gross: type: number description: >- DEPRECATED: use `total`. Total amount this fan paid across all transactions, in USD cents. Same value as `total`, and net of reversals despite the field name. total: type: number description: >- Total amount this fan paid across all transactions, in USD cents. Excludes App Store purchases, which record a creator buying an app from its developer rather than a fan paying this creator. Net of reversals: a refund or chargeback is a separate invoice for the full original amount and is subtracted here, so this is normally lower than the sum of the gross `sources` figures and can be negative. Reversals are selected by their own type rather than by what they reverse, so a clawed-back creator reward the fan never paid for is subtracted here too, and this can fall below what the fan actually paid. It is not the same as `netTotal`, which is aggregated over the surviving purchases instead; the two differ for a purchase reversed without a reversal invoice, which has no negative row for this figure to subtract. netTotal: type: number description: >- Total this fan paid with refunded and charged-back purchases removed, in USD cents. Aggregated over the surviving purchases themselves, so it and the per-source `netTotal` values describe one set of purchases and add up. It usually equals `total`, which subtracts reversals by counting their negative rows; the two part company only for a reversal recorded on the original purchase without a row of its own, which `total` cannot see. required: - gross - total - netTotal maxSinglePayment: type: object properties: gross: type: number description: >- DEPRECATED: use `total`. Largest single payment this fan made, in USD cents. Same value as `total`, and excludes reversed purchases. total: type: number description: >- Largest single payment this fan made, in USD cents. Excludes App Store purchases, as `total` does. Excludes reversed purchases: a payment later refunded or charged back is not eligible, so this can be lower than the largest amount the fan ever paid. Reversal invoices themselves are never counted. This has been the behaviour since July 2025. A refund or chargeback marker on the payment counts as a reversal in its own right when no reversal invoice is linked, so a purchase reversed that way is excluded too; a purchase whose reversal was created and then failed stays eligible, because that reversal never settled. required: - gross - total sources: type: object additionalProperties: type: object properties: gross: type: number description: >- DEPRECATED: use `total`. Total amount paid by the fan for this source type, in USD cents. Same value as `total`, and gross of reversals. total: type: number description: >- Total amount paid by the fan for this source type, in USD cents. Gross of reversals: a purchase that was later refunded or charged back is still counted here in full. Use `netTotal` for the figure with those purchases removed. netTotal: type: number description: >- Total paid from this source with refunded and charged-back purchases removed, in USD cents: the sum of the purchases that still stand, and the numerator of `netAverage`. Net of reversals only, not of Fanvue fees, unlike the `net` returned by /insights/earnings and /agencies/insights/*. count: type: integer description: >- Number of purchases the fan made from this source, counting purchases later refunded or charged back. The denominator of `average`. netCount: type: integer description: >- Number of purchases the fan made from this source that were not later refunded or charged back. The denominator of `netAverage`. average: type: number description: >- Average purchase from this source, in USD cents: `total` divided by `count`, so refunded and charged-back purchases count on both sides. Not rounded. netAverage: type: - number - 'null' description: >- Average surviving purchase from this source, in USD cents: the sum of this source's purchases that were never refunded or charged back, divided by `netCount`. Reversed purchases are dropped from both sides. `null` when `netCount` is 0. Not rounded. required: - gross - total - netTotal - count - netCount - average - netAverage description: >- Breakdown of this fan's spend by source, keyed by the same source names /insights/earnings uses (so `renewal` is a catch-all for every recurring charge after the first payment). `appStore` is never present: an App Store invoice records a creator buying an app from its developer, not a fan paying this creator. `fanExperience` is fan-to-creator spend and is included. Refunds and chargebacks are never a source entry of their own. Each entry carries both treatments: `total`, `count` and `average` are gross of reversals, so the `total` values do not sum to `total.total` and the difference is exactly the reversals, while `netTotal`, `netCount` and `netAverage` drop the reversed purchases and the `netTotal` values do sum to `total.netTotal`. required: - lastPurchaseAt - lastValidPurchaseAt - total - maxSinglePayment - sources subscription: type: object properties: createdAt: type: - string - 'null' format: date-time description: >- Date subscription was created (ISO 8601) or null if no subscription renewsAt: type: - string - 'null' format: date-time description: >- Date subscription renews (ISO 8601) or null if no active subscription autoRenewalEnabled: type: boolean description: Whether fan has active recurring subscription required: - createdAt - renewsAt - autoRenewalEnabled required: - status - spending - subscription example: status: subscriber spending: lastPurchaseAt: '2024-01-14T00:00:00.000Z' lastValidPurchaseAt: '2024-01-14T00:00:00.000Z' total: gross: 25700 total: 25700 netTotal: 25700 maxSinglePayment: gross: 5000 total: 5000 sources: message: gross: 15000 total: 15000 netTotal: 13000 count: 6 netCount: 5 average: 2500 netAverage: 2600 post: gross: 8500 total: 8500 netTotal: 8500 count: 5 netCount: 5 average: 1700 netAverage: 1700 referral: gross: 4200 total: 4200 netTotal: 4200 count: 2 netCount: 2 average: 2100 netAverage: 2100 subscription: createdAt: '2024-01-01T12:00:00.000Z' renewsAt: '2024-02-01T00:00:00.000Z' autoRenewalEnabled: true '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. ````