> ## 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 per-creator-per-day subscriber events across all agency creators (cursor-paginated)
> Returns a single cursor-paginated stream of per-creator-per-day subscriber event rows across every creator the authenticated agency manages, sorted by most recent day first.
This endpoint is an analytics time series, not a real-time audience snapshot:
- `newSubscribersCount` = number of new subscription starts in the day bucket for the creator
- `cancelledSubscribersCount` = number of subscription chain ends in the day bucket for the creator
- `total` (on each row) = cumulative net change for the creator from the beginning of the requested range (`new - cancelled`)
- `renewalOnCount` = auto-renewing (paid, recurring) subscriptions that started in the day bucket
- `renewalOffCount` = subscriptions whose auto-renewal was switched off in the day bucket
- `freeTrialCount` = free-trial subscriptions that started in the day bucket
- `expiredCount` = subscriptions that lapsed (expired) in the day bucket
`newSubscribersCount`/`cancelledSubscribersCount`/`renewalOnCount`/`freeTrialCount`/`total` are derived from paid invoices (immutable, stable across resubscriptions). `renewalOffCount`/`expiredCount` are derived from the subscriptions table (`cancelled_at`/`deleted_at`) — both fields are cleared on resubscribe, so these counts may be zero for subscriptions that were later reactivated. `expiredCount` may also differ slightly from `cancelledSubscribersCount` since they measure lapse from different sources.
`newSubscribersCount` counts subscription **starts**, not distinct people: a returning fan who starts a new subscription is counted again. It also includes free trials, starts later refunded or charged back, fans who were later banned or deleted, and it spans profile subscriptions, checkout-link subscriptions and fan-experience subscriptions. Because of this it is normally higher than the "New" figure on the creator's in-app Insights dashboard, which counts first-ever profile subscribers only.
Days are **UTC calendar days**. `startDate`/`endDate` offsets are honoured when selecting the window, but there is no timezone parameter, so a creator working in a non-UTC timezone should expect their local-day totals to differ from these buckets.
`freeTrialCount` + `renewalOnCount` always equals `newSubscribersCount` — every start is classified as one or the other from the invoice's subscription type. A creator who only sells free trials will therefore see `freeTrialCount` equal to `newSubscribersCount` on every row; that is expected, not a duplicated field.
Page with the opaque `nextCursor` from the previous response. The result set is bounded by the requested date range, so the envelope's `total` is not computed and is always `null` (distinct from each row's per-creator `total` field).
If you need the current list of subscribers for messaging or CRM sync, use `GET /agencies/subscribers` instead.
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/subscribers-history
openapi: 3.1.0
info:
title: Fanvue API
version: '0.1'
servers:
- url: https://api.fanvue.com
security: []
paths:
/v1/agencies/subscribers-history:
get:
summary: >-
List per-creator-per-day subscriber events across all agency creators
(cursor-paginated)
description: >-
Returns a single cursor-paginated stream of per-creator-per-day
subscriber event rows across every creator the authenticated agency
manages, sorted by most recent day first.
This endpoint is an analytics time series, not a real-time audience
snapshot:
- `newSubscribersCount` = number of new subscription starts in the day
bucket for the creator
- `cancelledSubscribersCount` = number of subscription chain ends in the
day bucket for the creator
- `total` (on each row) = cumulative net change for the creator from the
beginning of the requested range (`new - cancelled`)
- `renewalOnCount` = auto-renewing (paid, recurring) subscriptions that
started in the day bucket
- `renewalOffCount` = subscriptions whose auto-renewal was switched off
in the day bucket
- `freeTrialCount` = free-trial subscriptions that started in the day
bucket
- `expiredCount` = subscriptions that lapsed (expired) in the day bucket
`newSubscribersCount`/`cancelledSubscribersCount`/`renewalOnCount`/`freeTrialCount`/`total`
are derived from paid invoices (immutable, stable across
resubscriptions). `renewalOffCount`/`expiredCount` are derived from the
subscriptions table (`cancelled_at`/`deleted_at`) — both fields are
cleared on resubscribe, so these counts may be zero for subscriptions
that were later reactivated. `expiredCount` may also differ slightly
from `cancelledSubscribersCount` since they measure lapse from different
sources.
`newSubscribersCount` counts subscription **starts**, not distinct
people: a returning fan who starts a new subscription is counted again.
It also includes free trials, starts later refunded or charged back,
fans who were later banned or deleted, and it spans profile
subscriptions, checkout-link subscriptions and fan-experience
subscriptions. Because of this it is normally higher than the "New"
figure on the creator's in-app Insights dashboard, which counts
first-ever profile subscribers only.
Days are **UTC calendar days**. `startDate`/`endDate` offsets are
honoured when selecting the window, but there is no timezone parameter,
so a creator working in a non-UTC timezone should expect their local-day
totals to differ from these buckets.
`freeTrialCount` + `renewalOnCount` always equals `newSubscribersCount`
— every start is classified as one or the other from the invoice's
subscription type. A creator who only sells free trials will therefore
see `freeTrialCount` equal to `newSubscribersCount` on every row; that
is expected, not a duplicated field.
Page with the opaque `nextCursor` from the previous response. The result
set is bounded by the requested date range, so the envelope's `total` is
not computed and is always `null` (distinct from each row's per-creator
`total` field).
If you need the current list of subscribers for messaging or CRM sync,
use `GET /agencies/subscribers` instead.
Requires: Agency admin access
operationId: listAgencySubscribersHistoryV1
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. Range must not exceed 365 days.
required: true
description: >-
End of the date range (exclusive). UTC ISO 8601 datetime with
offset. Range must not exceed 365 days.
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)
name: creatorUuids
in: query
style: form
explode: false
responses:
'200':
description: >-
Cursor-paginated list of per-creator-per-day subscriber events
across the agency's creators
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
creatorUuid:
type: string
format: uuid
description: >-
UUID of the agency-managed creator the row belongs
to
date:
type: string
format: date
description: >-
UTC calendar day the events are bucketed on
(YYYY-MM-DD)
total:
type: integer
description: >-
Cumulative net change in active subscribers for this
creator from the start of the requested range
(newSubscribersCount - cancelledSubscribersCount,
running)
newSubscribersCount:
type: integer
minimum: 0
description: >-
Number of new subscription chains started on this
day for this creator
cancelledSubscribersCount:
type: integer
minimum: 0
description: >-
Number of subscription chains ending (final
non-renewing expiry) on this day for this creator
renewalOnCount:
type: integer
minimum: 0
description: >-
Number of auto-renewing (paid, recurring)
subscriptions that started on this day for this
creator. A subscription has auto-renew on when
created, so this counts non-free-trial starts.
renewalOffCount:
type: integer
minimum: 0
description: >-
Number of subscriptions whose auto-renewal was
switched off on this day for this creator. The
subscription stays active until it expires.
freeTrialCount:
type: integer
minimum: 0
description: >-
Number of free-trial subscriptions that started on
this day for this creator
expiredCount:
type: integer
minimum: 0
description: >-
Number of subscriptions that lapsed (expired) on
this day for this creator. Derived from the
subscriptions table, so it may differ slightly from
cancelledSubscribersCount, which derives the same
notion from the invoice chain.
required:
- creatorUuid
- date
- total
- newSubscribersCount
- cancelledSubscribersCount
- renewalOnCount
- renewalOffCount
- freeTrialCount
- expiredCount
description: >-
Array of per-creator-per-day subscriber event rows across
the agency's creators
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:
- creatorUuid: c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8
date: '2024-01-15'
total: 5
newSubscribersCount: 6
cancelledSubscribersCount: 1
renewalOnCount: 5
renewalOffCount: 2
freeTrialCount: 1
expiredCount: 1
- creatorUuid: c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r9
date: '2024-01-14'
total: 2
newSubscribersCount: 3
cancelledSubscribersCount: 1
renewalOnCount: 2
renewalOffCount: 1
freeTrialCount: 1
expiredCount: 1
nextCursor: k0FQ1m9yZXN0aWdpb3VzLW9wYXF1ZS1jdXJzb3I
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.
````