---
title: "Get fan insights for a creator"
method: GET
path: "/creators/{creatorUserUuid}/insights/fans/{userUuid}"
---

# Get fan insights for a creator

`GET /creators/{creatorUserUuid}/insights/fans/{userUuid}`

Returns detailed insights about a specific fan for the specified creator, including spending statistics, subscription status, and fan engagement metrics.

## Path parameters

- `creatorUserUuid` string, uuid, required
- `userUuid` string, uuid, required — Fan's UUID

## Headers

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

## Response `200`

Fan insights data

- object
  - `status` 'subscriber' | 'expired' | 'follower' | 'not_contactable', required — Current fan status
  - `spending` object, required
    - `lastPurchaseAt` string, date-time, nullable, required — 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` string, date-time, nullable, required — 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` object, required
      - `gross` number, required — 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` number, required — 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` number, required — 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.
    - `maxSinglePayment` object, required
      - `gross` number, required — DEPRECATED: use `total`. Largest single payment this fan made, in USD cents. Same value as `total`, and excludes reversed purchases.
      - `total` number, required — 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.
    - `sources` object, required — 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`.
  - `subscription` object, required
    - `createdAt` string, date-time, nullable, required — Date subscription was created (ISO 8601) or null if no subscription
    - `renewsAt` string, date-time, nullable, required — Date subscription renews (ISO 8601) or null if no active subscription
    - `autoRenewalEnabled` boolean, required — Whether fan has active recurring subscription

## Other responses

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

## Changes

- **2026-08-30** `dce5621fe589` — 7 info
  - added the required property `spending/lastValidPurchaseAt` to the response with the `200` status
  - added the required property `spending/sources/additionalProperties/average` to the response with the `200` status
  - added the required property `spending/sources/additionalProperties/count` to the response with the `200` status
  - added the required property `spending/sources/additionalProperties/netAverage` to the response with the `200` status
  - …3 more

[Change history](https://skmtc.dev/fanvue/apis/fanvue-api/changes/creators/:creatorUserUuid/insights/fans/:userUuid/get.md)

---

[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)