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. <Info>Requires: Agency admin access</Info>
Query parameters
Start of the date range (inclusive). UTC ISO 8601 datetime with offset.
Start of the date range (inclusive). UTC ISO 8601 datetime with offset.
End of the date range (exclusive). UTC ISO 8601 datetime with offset.
End of the date range (exclusive). UTC ISO 8601 datetime with offset.
Comma-separated list of creator UUIDs (max 50)
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.
Headers
API version to use for the request
Response
Agency insights headline metrics