---
title: "Get agency insights headline metrics"
method: GET
path: "/agencies/insights/overview"
---

# Get agency insights headline metrics

`GET /agencies/insights/overview`

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

- `startDate` string, date-time, required — Start of the date range (inclusive). UTC ISO 8601 datetime with offset.
- `endDate` string, date-time, required — End of the date range (exclusive). UTC ISO 8601 datetime with offset.
- `creatorUuids` string[] — Comma-separated list of creator UUIDs (max 50)

## Headers

- `X-Fanvue-API-Version` string, required

## Response `200`

Agency insights headline metrics

- object
  - `totalEarnings` object, required — 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`.
    - `gross` integer, required — Gross earnings across the agency's creators in the date range, excluding reversals. USD cents.
    - `net` integer, required — Creator-net earnings (after platform fees) across the agency's creators in the date range, excluding reversals. USD cents.
    - `currency` 'USD', required — Always 'USD'. Warehouse figures are reported in USD.
  - `newFans` integer, required — Distinct fans first acquired by any of the agency's creators in the date range
  - `arpu` object, required — 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.
    - `grossArpu` number, required — Gross spend divided by paying fan count, in USD cents. Not rounded.
    - `netArpu` number, required — Net spend divided by paying fan count, in USD cents. Not rounded.
    - `grossSpend` integer, required — Total gross fan spend in the date range, net of refunds and chargebacks. USD cents.
    - `netSpend` integer, required — Total net fan spend in the date range, net of refunds and chargebacks. USD cents.
    - `fanCount` integer, required — Distinct fans who spent in the date range
    - `currency` 'USD', required — Always 'USD'. Warehouse figures are reported in USD.
  - `retention` object, required — 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.
    - `retentionRate` number, required — Retained fans divided by cohort fans, as a fraction (0.88 means 88%). 0 when the cohort is empty.
    - `cohortFanCount` integer, required — Paying fans in the cohort window
    - `retainedFanCount` integer, required — Cohort fans who paid again in the reporting window
    - `revenueRetentionRate` number, required — Retained gross revenue divided by cohort gross revenue, as a fraction. Can exceed 1 when retained fans spend more than the cohort did.
    - `cohortGrossRevenue` integer, required — Gross revenue from the cohort window. USD cents.
    - `retainedGrossRevenue` integer, required — Gross revenue retained in the reporting window. USD cents.
  - `averageFanLifetime` object, required — 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.
    - `activeAvgDays` number, required — Average lifetime in days of fans still active with one of the agency's creators
    - `activeFanCount` integer, required — Fans counted in activeAvgDays
    - `churnedAvgDays` number, required — Average lifetime in days of fans who have churned
    - `churnedFanCount` integer, required — Fans counted in churnedAvgDays

## Other responses

- `400` — Bad Request - API version not supported OR validation failed (dates, sources, cursor, pagination)
- `401` — Unauthorized Response
- `403` — Unauthorized Response
- `410` — API version no longer supported (sunset)
- `429` — Too many requests - rate limit exceeded

---

[API](https://skmtc.dev/fanvue/apis/fanvue-api.md) · [All operations](https://skmtc.dev/fanvue/apis/fanvue-api/llms.txt) · [OpenAPI document](https://skmtc.dev/fanvue/apis/fanvue-api/revisions/431868e8a264?raw)