> ## 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 (POST batch)
> Returns detailed insights for up to 100 fans in a single request, keyed by the input fan UUID.
This is the high-cap, JSON-body counterpart to `GET /insights/fans` (capped at 20 via query string). It is intended for initial-sync flows that need to hydrate many fans without per-fan round trips.
Per-key errors are reported inside the 200 response body so a single forbidden or missing fan never collapses the whole request — consumers can keep partial results and only retry the failing keys.
Maximum 100 fan UUIDs per request. Failed keys are reported as `{ "error": "forbidden" | "not_found" | "internal" }`.
**Required scopes**
* `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.json post /insights/fans/batch
openapi: 3.1.0
info:
title: Fanvue API
version: '0.1'
servers: []
security: []
paths:
/insights/fans/batch:
post:
summary: Get fan insights in bulk (POST batch)
description: >-
Returns detailed insights for up to 100 fans in a single request, keyed
by the input fan UUID.
This is the high-cap, JSON-body counterpart to `GET /insights/fans`
(capped at 20 via query string). It is intended for initial-sync flows
that need to hydrate many fans without per-fan round trips.
Per-key errors are reported inside the 200 response body so a single
forbidden or missing fan never collapses the whole request — consumers
can keep partial results and only retry the failing keys.
Maximum 100 fan UUIDs per request. Failed keys are reported as `{
"error": "forbidden" | "not_found" | "internal" }`.
operationId: batchFanInsights
parameters:
- $ref: '#/components/parameters/ApiVersionHeader'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
userUuids:
type: array
items:
type: string
format: uuid
minItems: 1
maxItems: 100
description: Array of fan UUIDs to fetch insights for (1-100)
required:
- userUuids
responses:
'200':
description: >-
Per-key insights or error for each requested fan. Always 200 when
the request itself is valid, even if every key fails.
content:
application/json:
schema:
type: object
additionalProperties:
anyOf:
- 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: >-
Date of last purchase (ISO 8601) or null if no
purchases
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`.
total:
type: number
description: >-
Total amount this fan paid across all
transactions, in USD cents
required:
- gross
- total
maxSinglePayment:
type: object
properties:
gross:
type: number
description: >-
DEPRECATED: use `total`. Largest single
payment this fan made, in USD cents. Same
value as `total`.
total:
type: number
description: >-
Largest single payment this fan made, in USD
cents
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`.
total:
type: number
description: >-
Total amount paid by the fan for this
source type, in USD cents
required:
- gross
- total
description: Breakdown of spending by source
required:
- lastPurchaseAt
- 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
- type: object
properties:
error:
type: string
enum:
- forbidden
- not_found
- internal
required:
- error
description: >-
Map of input fan UUID to insights or a per-key error
(forbidden, not_found, or internal).
example:
11111111-1111-4111-8111-111111111111:
status: subscriber
spending:
lastPurchaseAt: '2026-04-12T08:32:00.000Z'
total:
gross: 12000
total: 12000
maxSinglePayment:
gross: 5000
total: 5000
sources:
subscription:
gross: 7000
total: 7000
tips:
gross: 5000
total: 5000
subscription:
createdAt: '2026-01-15T00:00:00.000Z'
renewsAt: '2026-06-15T00:00:00.000Z'
autoRenewalEnabled: true
22222222-2222-4222-8222-222222222222:
error: not_found
33333333-3333-4333-9333-333333333333:
error: internal
'400':
description: Bad Request - API version not supported OR validation failed
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/UnsupportedVersionError'
- $ref: '#/components/schemas/ValidationError'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/UnauthorizedResponse'
'410':
$ref: '#/components/responses/SunsetVersionResponse'
'429':
$ref: '#/components/responses/RateLimitResponse'
security:
- BearerAuth:
- 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
responses:
UnauthorizedResponse:
description: Unauthorized Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
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.
````