> ## Documentation Index
> Fetch the complete documentation index at: https://api.fanvue.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# List agency fan spend by country (cursor-paginated)
> 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.
Every row carries both figures: `gross` is what payers from that country paid, `net` is the creators' cut after platform fees. Both are already net of refunds and chargebacks, so either can be negative for a country whose only activity in the range was a reversal.
The payer is not always a fan: an App Store invoice records a creator buying an app from its developer, and the live branch that serves the current day and either partial edge day counts it, so a country's figures can include creator-to-developer spend.
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`.
Requires: Agency admin access
**Required scopes**
* `read:agency` — Read agency information, including the agency's team members.
* `read:creator` — Access creator profiles, content, and creator-specific information.
## OpenAPI
````yaml /openapi-v1.json get /v1/agencies/insights/demographics
openapi: 3.1.0
info:
title: Fanvue API
version: '0.1'
servers:
- url: https://api.fanvue.com
security: []
paths:
/v1/agencies/insights/demographics:
get:
summary: List agency fan spend by country (cursor-paginated)
description: >-
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.
Every row carries both figures: `gross` is what payers from that country
paid, `net` is the creators' cut after platform fees. Both are already
net of refunds and chargebacks, so either can be negative for a country
whose only activity in the range was a reversal.
The payer is not always a fan: an App Store invoice records a creator
buying an app from its developer, and the live branch that serves the
current day and either partial edge day counts it, so a country's
figures can include creator-to-developer spend.
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`.
Requires: Agency admin access
operationId: getAgencyDemographics
parameters:
- $ref: '#/components/parameters/ApiVersionHeader'
- schema:
type: string
description: >-
Opaque pagination cursor from a previous response's `nextCursor`.
Omit to fetch the first page.
required: false
description: >-
Opaque pagination cursor from a previous response's `nextCursor`.
Omit to fetch the first page.
name: cursor
in: query
- schema:
type: integer
minimum: 1
maximum: 50
default: 15
description: 'Number of items to return (1-50, default: 15)'
required: false
description: 'Number of items to return (1-50, default: 15)'
name: size
in: query
- schema:
type: string
format: date-time
description: >-
Start of the date range (inclusive). UTC ISO 8601 datetime with
offset.
required: true
description: >-
Start of the date range (inclusive). UTC ISO 8601 datetime with
offset.
name: startDate
in: query
- schema:
type: string
format: date-time
description: >-
End of the date range (exclusive). UTC ISO 8601 datetime with
offset.
required: true
description: >-
End of the date range (exclusive). UTC ISO 8601 datetime with
offset.
name: endDate
in: query
- schema:
type: array
items:
type: string
format: uuid
maxItems: 50
description: Comma-separated list of creator UUIDs (max 50)
required: false
description: >-
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.
name: creatorUuids
in: query
style: form
explode: false
responses:
'200':
description: Cursor-paginated fan-country distribution
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
country:
type: string
description: >-
ISO 3166-1 alpha-2 country code of the fans' billing
country
fanCount:
type: integer
description: >-
Distinct payers from this country who spent in the
range. Usually fans; an App Store purchase counts
its buyer, who is a creator.
gross:
type: integer
description: >-
Gross spend from this country in the date range, net
of refunds and chargebacks, so it can be negative.
USD cents.
net:
type: integer
description: >-
Net spend from this country in the date range, net
of refunds and chargebacks, so it can be negative.
USD cents.
required:
- country
- fanCount
- gross
- net
description: Array of fan-country rows, ordered by fan count descending
nextCursor:
type:
- string
- 'null'
description: >-
Opaque cursor for the next page, or null when there are no
more results
total:
type:
- integer
- 'null'
description: >-
Total number of items across all pages, or null when no
count is computed
required:
- data
- nextCursor
- total
example:
data:
- country: US
fanCount: 842
gross: 2410000
net: 2048500
- country: GB
fanCount: 311
gross: 890000
net: 756500
- country: DE
fanCount: 146
gross: 412000
net: 350200
nextCursor: null
total: null
'400':
description: >-
Bad Request - API version not supported OR validation failed (dates,
sources, cursor, pagination)
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/UnsupportedVersionError'
- $ref: '#/components/schemas/ValidationError'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/UnauthorizedResponse'
'410':
$ref: '#/components/responses/SunsetVersionResponse'
'429':
$ref: '#/components/responses/RateLimitResponse'
security:
- BearerAuth:
- read:agency
- read:creator
components:
parameters:
ApiVersionHeader:
name: X-Fanvue-API-Version
in: header
required: true
schema:
type: string
default: '2025-06-26'
example: '2025-06-26'
description: API version to use for the request
schemas:
UnsupportedVersionError:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
- message
description: API version not supported
ValidationError:
type: object
properties:
errors:
type: array
items:
type: string
required:
- errors
description: Request validation failed
responses:
UnauthorizedResponse:
description: Unauthorized Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
SunsetVersionResponse:
description: API version no longer supported (sunset)
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
nextVersion:
type: string
required:
- error
- message
RateLimitResponse:
description: Too many requests - rate limit exceeded
headers:
Retry-After:
description: Number of seconds to wait before retrying the request
schema:
type: integer
X-RateLimit-Limit:
description: The maximum number of requests allowed in the current window
schema:
type: integer
X-RateLimit-Remaining:
description: The number of requests remaining in the current window
schema:
type: integer
X-RateLimit-Reset:
description: The Unix timestamp (seconds) when the rate limit window resets
schema:
type: integer
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
securitySchemes:
BearerAuth:
type: oauth2
description: >-
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.
flows:
authorizationCode:
authorizationUrl: https://auth.fanvue.com/oauth2/auth
tokenUrl: https://auth.fanvue.com/oauth2/token
refreshUrl: https://auth.fanvue.com/oauth2/token
scopes:
read:self: >-
Access your own user profile information, including basic account
details and settings.
read:chat: >-
Read chat conversations, messages, and chat-related data. This
includes viewing chat lists and message history.
write:chat: >-
Create new chats and send messages. This scope is required for any
chat-related actions that modify data.
read:experience: >-
Exchange a fan's experience token for the resolved experience and
the fan's identity, so an embedded fan-facing experience can
render the right content.
write:experience: >-
Request that the creator publish or unpublish a fan-facing
experience. The app mints a request token; the creator confirms
and Fanvue performs the change.
read:fan: Access fan-related data and information within the platform.
read:post: Read posts, including post details, comments, likes, and tips.
write:post: Create, edit, and manage posts and content on behalf of users.
read:media: Access media files, images, videos, and other content assets.
write:media: >-
Upload, modify, and manage media files and content assets. Also
required for vault folder management.
read:creator: >-
Access creator profiles, content, and creator-specific
information.
write:creator: Modify creator profiles, settings, and creator-specific data.
read:insights: >-
Access analytics, metrics, and insights data for performance
tracking.
read:tracking_links: >-
Read tracking links and the users associated with them, including
per-user tracking metadata.
write:tracking_links: Create and delete tracking links.
read:agency: Read agency information, including the agency's team members.
write:agency: >-
Manage agency team members and invites, including inviting new
team members and creators.
````