> ## 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 agency insights headline metrics
> Returns the headline metrics for the authenticated user's agency: total earnings, newly acquired fans, average revenue per paying fan, the 30-day retention snapshot and average fan lifetime, aggregated across every creator the agency manages.
`totalEarnings`, `newFans` and `arpu` are served from the daily warehouse export for the whole UTC days inside the range and read live for the current day and for any partial day at either edge, so they include today. The live reads differ by metric: `totalEarnings` and `arpu` come from invoices, while `newFans` counts a fan's first follow or first subscribe to a creator, so it moves on a free follow or a free trial with no payment behind it. `retention` and `averageFanLifetime` have no live branch and come only from the warehouse snapshots. All money is USD cents; rates are fractions, not percentages.
Almost every money figure comes as a pair: `gross` is pre-fee earnings, `net` is the creators' cut after platform fees. That is the only axis the two words describe here. Reversals are already handled on both, as each field states. The exception is the `retention` snapshot: `cohortGrossRevenue` and `retainedGrossRevenue` are gross-only with no net counterpart, so `revenueRetentionRate` is a gross-on-gross ratio and there is no net retention figure to select.
`totalEarnings` and `arpu` are not two views of one number and will not reconcile. `totalEarnings` is what the agency's creators earned, excluding refunds and chargebacks, and includes money no fan paid for, such as referrals. `arpu` measures what payers paid, so it drops those and subtracts reversals; the one payer that is not a fan is an App Store invoice, which records a creator buying an app from its developer and is counted by the live branch. Note that this is stricter than the creator-level `/insights/top-spenders`, which counts positive invoices only and so leaves a refunded purchase in at full value. Expect `arpu.grossSpend` to be the smaller figure.
`retention` and `averageFanLifetime` are snapshots computed on the warehouse's own windows — the 30-day cohort and all-time respectively — so `startDate`/`endDate` do not affect them.
No comparison period is returned: to show a change against the preceding period, request the same endpoint again for that range.
Requires: Agency admin access
**Required scopes**
* `read:agency` — Read agency information, including the agency's team members.
* `read:creator` — Access creator profiles, content, and creator-specific information.
## OpenAPI
````yaml /openapi-v1.json get /v1/agencies/insights/overview
openapi: 3.1.0
info:
title: Fanvue API
version: '0.1'
servers:
- url: https://api.fanvue.com
security: []
paths:
/v1/agencies/insights/overview:
get:
summary: Get agency insights headline metrics
description: >-
Returns the headline metrics for the authenticated user's agency: total
earnings, newly acquired fans, average revenue per paying fan, the
30-day retention snapshot and average fan lifetime, aggregated across
every creator the agency manages.
`totalEarnings`, `newFans` and `arpu` are served from the daily
warehouse export for the whole UTC days inside the range and read live
for the current day and for any partial day at either edge, so they
include today. The live reads differ by metric: `totalEarnings` and
`arpu` come from invoices, while `newFans` counts a fan's first follow
or first subscribe to a creator, so it moves on a free follow or a free
trial with no payment behind it. `retention` and `averageFanLifetime`
have no live branch and come only from the warehouse snapshots. All
money is USD cents; rates are fractions, not percentages.
Almost every money figure comes as a pair: `gross` is pre-fee earnings,
`net` is the creators' cut after platform fees. That is the only axis
the two words describe here. Reversals are already handled on both, as
each field states. The exception is the `retention` snapshot:
`cohortGrossRevenue` and `retainedGrossRevenue` are gross-only with no
net counterpart, so `revenueRetentionRate` is a gross-on-gross ratio and
there is no net retention figure to select.
`totalEarnings` and `arpu` are not two views of one number and will not
reconcile. `totalEarnings` is what the agency's creators earned,
excluding refunds and chargebacks, and includes money no fan paid for,
such as referrals. `arpu` measures what payers paid, so it drops those
and subtracts reversals; the one payer that is not a fan is an App Store
invoice, which records a creator buying an app from its developer and is
counted by the live branch. Note that this is stricter than the
creator-level `/insights/top-spenders`, which counts positive invoices
only and so leaves a refunded purchase in at full value. Expect
`arpu.grossSpend` to be the smaller figure.
`retention` and `averageFanLifetime` are snapshots computed on the
warehouse's own windows — the 30-day cohort and all-time respectively —
so `startDate`/`endDate` do not affect them.
No comparison period is returned: to show a change against the preceding
period, request the same endpoint again for that range.
Requires: Agency admin access
operationId: getAgencyInsightsOverview
parameters:
- $ref: '#/components/parameters/ApiVersionHeader'
- schema:
type: string
format: date-time
description: >-
Start of the date range (inclusive). UTC ISO 8601 datetime with
offset.
required: true
description: >-
Start of the date range (inclusive). UTC ISO 8601 datetime with
offset.
name: startDate
in: query
- schema:
type: string
format: date-time
description: >-
End of the date range (exclusive). UTC ISO 8601 datetime with
offset.
required: true
description: >-
End of the date range (exclusive). UTC ISO 8601 datetime with
offset.
name: endDate
in: query
- schema:
type: array
items:
type: string
format: uuid
maxItems: 50
description: Comma-separated list of creator UUIDs (max 50)
required: false
description: >-
Comma-separated list of creator UUIDs to restrict results to a
subset of the agency's managed creators (max 50). Every uuid must
belong to the agency: one that does not fails the whole request with
403 rather than being ignored.
name: creatorUuids
in: query
style: form
explode: false
responses:
'200':
description: Agency insights headline metrics
content:
application/json:
schema:
type: object
properties:
totalEarnings:
type: object
properties:
gross:
type: integer
description: >-
Gross earnings across the agency's creators in the
date range, excluding reversals. USD cents.
net:
type: integer
description: >-
Creator-net earnings (after platform fees) across the
agency's creators in the date range, excluding
reversals. USD cents.
currency:
type: string
enum:
- USD
description: Always 'USD'. Warehouse figures are reported in USD.
required:
- gross
- net
- currency
description: >-
Total agency earnings over the requested date range.
Everything the agency's creators earned, whether or not a
fan was behind it, with refunds and chargebacks left out —
so this does not equal `arpu.grossSpend`/`netSpend`.
newFans:
type: integer
description: >-
Distinct fans first acquired by any of the agency's
creators in the date range
arpu:
type: object
properties:
grossArpu:
type: number
description: >-
Gross spend divided by paying fan count, in USD cents.
Not rounded.
netArpu:
type: number
description: >-
Net spend divided by paying fan count, in USD cents.
Not rounded.
grossSpend:
type: integer
description: >-
Total gross fan spend in the date range, net of
refunds and chargebacks. USD cents.
netSpend:
type: integer
description: >-
Total net fan spend in the date range, net of refunds
and chargebacks. USD cents.
fanCount:
type: integer
description: Distinct fans who spent in the date range
currency:
type: string
enum:
- USD
description: Always 'USD'. Warehouse figures are reported in USD.
required:
- grossArpu
- netArpu
- grossSpend
- netSpend
- fanCount
- currency
description: >-
Average revenue per paying fan over the requested date
range. These are fan-spend figures, not earnings: money no
fan paid for (referrals, affiliate) is excluded, and
reversals are subtracted. The one payer that is not a fan
is an App Store invoice, which records a creator buying an
app from its developer and is counted by the live branch.
Subtracting reversals is stricter than the creator-level
`/insights/top-spenders`: that endpoint counts positive
invoices only, so it leaves a refunded purchase in at full
value. Both are therefore lower than `totalEarnings` and
the two will not reconcile.
retention:
type: object
properties:
retentionRate:
type: number
description: >-
Retained fans divided by cohort fans, as a fraction
(0.88 means 88%). 0 when the cohort is empty.
cohortFanCount:
type: integer
description: Paying fans in the cohort window
retainedFanCount:
type: integer
description: Cohort fans who paid again in the reporting window
revenueRetentionRate:
type: number
description: >-
Retained gross revenue divided by cohort gross
revenue, as a fraction. Can exceed 1 when retained
fans spend more than the cohort did.
cohortGrossRevenue:
type: integer
description: Gross revenue from the cohort window. USD cents.
retainedGrossRevenue:
type: integer
description: >-
Gross revenue retained in the reporting window. USD
cents.
required:
- retentionRate
- cohortFanCount
- retainedFanCount
- revenueRetentionRate
- cohortGrossRevenue
- retainedGrossRevenue
description: >-
Fixed 30-day retention snapshot, cohort-weighted across
the agency's creators. Computed by the data warehouse on
its own cohort/reporting windows and therefore NOT
affected by startDate/endDate.
averageFanLifetime:
type: object
properties:
activeAvgDays:
type: number
description: >-
Average lifetime in days of fans still active with one
of the agency's creators
activeFanCount:
type: integer
description: Fans counted in activeAvgDays
churnedAvgDays:
type: number
description: Average lifetime in days of fans who have churned
churnedFanCount:
type: integer
description: Fans counted in churnedAvgDays
required:
- activeAvgDays
- activeFanCount
- churnedAvgDays
- churnedFanCount
description: >-
All-time average fan lifetime, split by active and churned
fans. Only fans with two or more paid transactions are
counted, and the figures are NOT affected by
startDate/endDate.
required:
- totalEarnings
- newFans
- arpu
- retention
- averageFanLifetime
example:
totalEarnings:
gross: 4820000
net: 4097000
currency: USD
newFans: 412
arpu:
grossArpu: 2881.25
netArpu: 2449.0625
grossSpend: 4610000
netSpend: 3918500
fanCount: 1600
currency: USD
retention:
retentionRate: 0.88
cohortFanCount: 900
retainedFanCount: 792
revenueRetentionRate: 1.05
cohortGrossRevenue: 2100000
retainedGrossRevenue: 2205000
averageFanLifetime:
activeAvgDays: 72.2
activeFanCount: 310
churnedAvgDays: 41.5
churnedFanCount: 590
'400':
description: >-
Bad Request - API version not supported OR validation failed (dates,
sources, cursor, pagination)
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:agency
- read:creator
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.
````