---
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.

Figures come from the daily warehouse export, so they lag live platform data by up to a day. All money is USD cents; rates are fractions, not percentages.

`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 with no fan behind it such as referrals. `arpu` measures what fans paid, so it drops those and subtracts reversals — the same definition the creator-level `/insights/top-spenders` uses. 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 with no fan behind it (referrals, affiliate) is excluded, and reversals are subtracted the same way the creator-level `/insights/top-spenders` does it. 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.net/fanvue/apis/fanvue-api.md) · [All operations](https://skmtc.net/fanvue/apis/fanvue-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/fanvue/fanvue-api/revisions/c5ddcd5c7e72/schema)