curl --request GET \
--url https://api.fanvue.com/v1/agencies/insights/overview \
--header 'Authorization: Bearer <token>' \
--header 'X-Fanvue-API-Version: <x-fanvue-api-version>'import requests
url = "https://api.fanvue.com/v1/agencies/insights/overview"
headers = {
"X-Fanvue-API-Version": "<x-fanvue-api-version>",
"Authorization": "Bearer <token>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {
'X-Fanvue-API-Version': '<x-fanvue-api-version>',
Authorization: 'Bearer <token>'
}
};
fetch('https://api.fanvue.com/v1/agencies/insights/overview', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"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
}
}{
"error": "<string>",
"message": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>",
"message": "<string>",
"nextVersion": "<string>"
}{
"error": "<string>"
}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.
curl --request GET \
--url https://api.fanvue.com/v1/agencies/insights/overview \
--header 'Authorization: Bearer <token>' \
--header 'X-Fanvue-API-Version: <x-fanvue-api-version>'import requests
url = "https://api.fanvue.com/v1/agencies/insights/overview"
headers = {
"X-Fanvue-API-Version": "<x-fanvue-api-version>",
"Authorization": "Bearer <token>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {
'X-Fanvue-API-Version': '<x-fanvue-api-version>',
Authorization: 'Bearer <token>'
}
};
fetch('https://api.fanvue.com/v1/agencies/insights/overview', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"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
}
}{
"error": "<string>",
"message": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": "<string>",
"message": "<string>",
"nextVersion": "<string>"
}{
"error": "<string>"
}read:agency— Read agency information, including the agency’s team members.read:creator— Access creator profiles, content, and creator-specific information.
Authorizations
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.
Headers
API version to use for the request
"2025-06-26"
Query Parameters
Start of the date range (inclusive). UTC ISO 8601 datetime with offset.
End of the date range (exclusive). UTC ISO 8601 datetime with offset.
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. Comma-separated list of creator UUIDs (max 50)
50Response
Agency insights headline metrics
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.
Show child attributes
Show child attributes
Distinct fans first acquired by any of the agency's creators in the date range
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.
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
Was this page helpful?