> ## 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 in bulk for a creator
> Returns detailed insights for multiple fans of the specified creator in a single request.
Maximum 20 fan UUIDs per request.
**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
openapi: 3.1.0
info:
title: Fanvue API
version: '0.1'
servers:
- url: https://api.fanvue.com
security: []
paths:
/v1/creators/{creatorUserUuid}/insights/fans:
get:
summary: Get fan insights in bulk for a creator
description: >-
Returns detailed insights for multiple fans of the specified creator in
a single request.
Maximum 20 fan UUIDs per request.
operationId: getCreatorBulkFanInsights
parameters:
- $ref: '#/components/parameters/ApiVersionHeader'
- schema:
type: string
format: uuid
required: true
name: creatorUserUuid
in: path
- schema:
type: string
description: Comma-separated fan UUIDs to fetch insights for (max 20)
required: true
description: Comma-separated fan UUIDs to fetch insights for (max 20)
name: fanUuids
in: query
responses:
'200':
description: Insight data about the creator's fans
content:
application/json:
schema:
type: object
properties:
results:
type: object
additionalProperties:
type:
- object
- 'null'
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
description: Map fan UUID -> insights payload (null when unavailable)
errors:
type: array
items:
type: object
properties:
fanUuid:
type: string
format: uuid
code:
type: string
enum:
- NOT_FOUND
- INTERNAL
message:
type: string
required:
- fanUuid
- code
- message
description: Per-fan errors for unresolved entries
required:
- results
- errors
example:
results:
11111111-1111-1111-1111-111111111111:
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
22222222-2222-2222-2222-222222222222: null
errors:
- fanUuid: 22222222-2222-2222-2222-222222222222
code: NOT_FOUND
message: >-
The specified fan does not exist or is not connected to
this creator.
'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.
````