List per-creator-per-day subscriber events across all agency creators (cursor-paginated)

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

import requests

url = "https://api.fanvue.com/v1/agencies/subscribers-history"

headers = {
    "X-Fanvue-API-Version": "<x-fanvue-api-version>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {
    'X-Fanvue-API-Version': '<x-fanvue-api-version>',
    Authorization: 'Bearer <token>'
  }
};

fetch('https://api.fanvue.com/v1/agencies/subscribers-history', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "nextVersion": "<string>"
}

{
  "error": "<string>"
}

Agency Insights

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

GET

agencies

subscribers-history

List per-creator-per-day subscriber events across all agency creators (cursor-paginated)

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

import requests

url = "https://api.fanvue.com/v1/agencies/subscribers-history"

headers = {
    "X-Fanvue-API-Version": "<x-fanvue-api-version>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {
    'X-Fanvue-API-Version': '<x-fanvue-api-version>',
    Authorization: 'Bearer <token>'
  }
};

fetch('https://api.fanvue.com/v1/agencies/subscribers-history', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "nextVersion": "<string>"
}

{
  "error": "<string>"
}

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

cursor

string

Opaque pagination cursor from a previous response's nextCursor. Omit to fetch the first page.

size

integer

default:15

Number of items to return (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

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

nextCursor

string | null

required

Opaque cursor for the next page, or null when there are no more results

total

integer | null

required

Total number of items across all pages, or null when no count is computed

Overview

Popular endpoints

Account

Chats

Notifications

Posts

Creator Tools

Insights & Earnings

Onboarding

Experiences

Webhooks

Agency

List per-creator-per-day subscriber events across all agency creators (cursor-paginated)

Authorizations

Headers

Query Parameters

Response