---
title: "List agency fan spend by country (cursor-paginated)"
method: GET
path: "/agencies/insights/demographics"
---

# List agency fan spend by country (cursor-paginated)

`GET /agencies/insights/demographics`

Returns the agency's paying fans grouped by billing country over the requested date range, ordered by fan count descending, then gross spend, then country code. Fans whose country is unknown are excluded, so shares should be computed against the returned rows rather than against the agency's total fan count.

Page with the opaque `nextCursor` from the previous response. The result set is bounded by the requested date range, so `total` is not computed and is always `null`.
<Info>Requires: Agency admin access</Info>

## Query parameters

- `cursor` string — Opaque pagination cursor from a previous response's `nextCursor`. Omit to fetch the first page.
- `size` integer — Number of items to return (1-50, default: 15)
- `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`

Cursor-paginated fan-country distribution

- object
  - `data` object[], required — Array of fan-country rows, ordered by fan count descending
    - `country` string, required — ISO 3166-1 alpha-2 country code of the fans' billing country
    - `fanCount` integer, required — Distinct fans from this country who spent in the range
    - `gross` integer, required — Gross spend from this country in the date range, net of refunds and chargebacks, so it can be negative. USD cents.
    - `net` integer, required — Net spend from this country in the date range, net of refunds and chargebacks, so it can be negative. USD cents.
  - `nextCursor` string, nullable, required — Opaque cursor for the next page, or null when there are no more results
  - `total` integer, nullable, required — Total number of items across all pages, or null when no count is computed

## 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)