List per-creator-per-day subscriber events across all agency creators

curl --request GET \
  --url https://api.example.com/agencies/subscribers-history \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Fanvue-API-Version: <x-fanvue-api-version>'

{
  "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
    }
  ],
  "pagination": {
    "page": 1,
    "size": 2,
    "hasMore": true
  }
}

Agency Insights

List per-creator-per-day subscriber events across all agency creators

Returns a single 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 = 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.

If you need the current list of subscribers for messaging or CRM sync, use GET /agencies/subscribers instead.

Requires: Agency admin access

GET

agencies

subscribers-history

List per-creator-per-day subscriber events across all agency creators

curl --request GET \
  --url https://api.example.com/agencies/subscribers-history \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Fanvue-API-Version: <x-fanvue-api-version>'

{
  "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
    }
  ],
  "pagination": {
    "page": 1,
    "size": 2,
    "hasMore": true
  }
}

Required scopes

read:agency — Read agency information, including the agency’s team members.
read:creator — Access creator profiles, content, and creator-specific information.

Authorizations

Authorization

string

header

required

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.

Headers

X-Fanvue-API-Version

string

default:2025-06-26

required

API version to use for the request

Example:

"2025-06-26"

Query Parameters

page

number

default:1

Page number to retrieve (starts from 1)

Required range: x >= 1

size

number

default:15

Number of items to return per page (1-50, default: 15)

Required range: 1 <= x <= 50

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. Range must not exceed 365 days.

creatorUuids

string<uuid>[]

Comma-separated list of creator UUIDs to restrict results to a subset of the agency's managed creators (max 50) Comma-separated list of creator UUIDs (max 50)

Maximum array length: 50

Response

Paginated list of per-creator-per-day subscriber events across the agency's creators

data

object[]

required

Array of per-creator-per-day subscriber event rows across the agency's creators

Show child attributes

pagination

object

required

Pagination information

Show child attributes

List per-creator-per-day earnings across all agency creators Get account view for a managed creator