---
title: "Get subscriber events over time"
method: GET
path: "/insights/subscribers"
---

# Get subscriber events over time

`GET /insights/subscribers`

Returns cursor-paginated subscriber event data for the authenticated creator over a specified time period.

This endpoint is an analytics time series, not a real-time audience snapshot:
- `newSubscribersCount` = number of new subscription starts in the period bucket
- `cancelledSubscribersCount` = number of subscription chain ends in the period bucket
- `total` = cumulative net change from the beginning of the requested range (`new - cancelled`)

If you need a current audience count/list (for messaging or contact list UX), use Smart Lists endpoints (`/chats/lists/smart` and `/chats/lists/smart/{uuid}`) instead of this endpoint.

`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. Use this endpoint as the canonical daily acquisition figure.

`startDate`/`endDate` offsets are honoured when selecting the window, but events are always bucketed into **UTC calendar days** — `date` is always UTC midnight. There is no timezone parameter on this endpoint, so a creator working in a non-UTC timezone should expect their local-day totals to differ from these buckets.

<Info>
  **Polling for real-time updates? Use a webhook instead.**

  If you are calling this endpoint on a schedule to detect new activity, subscribe to the `creator.subscription.activated`, `creator.subscription.deactivated` webhook events instead — you'll get pushed updates in real time without polling. See the [webhook documentation](https://api.fanvue.com/docs/creator/subscriptions).
</Info>

## Query parameters

- `startDate` string, date-time — Start date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-20T00:00:00+01:00 or 2024-10-20T00:00:00Z). Inclusive. The offset is honoured when selecting the window (the time component is not ignored), but events are always bucketed into UTC calendar days.
- `endDate` string, date-time — End date as ISO 8601 datetime string with optional timezone offset (e.g., 2024-10-25T00:00:00+01:00 or 2024-10-25T00:00:00Z). Non-inclusive - data before this date is included. The offset is honoured when selecting the window (the time component is not ignored), but events are always bucketed into UTC calendar days.
- `cursor` string — Cursor for pagination - If given, pass `nextCursor` to get the next page.
- `size` number — Number of items to return per page (1-50, default: 20). When omitted on a cursor request, the size from the previous page (carried in the cursor) is reused.

## Headers

- `X-Fanvue-API-Version` string, required

## Response `200`

Subscribers data with cursor pagination

- object
  - `data` object[], required
    - `date` string, date-time, required — Start of the UTC calendar day the events are bucketed on, as an ISO 8601 datetime string. Always UTC midnight (e.g., '2024-01-05T00:00:00.000Z'), regardless of any offset sent on startDate/endDate.
    - `total` number, required — Cumulative net subscriber change from query start date (new - cancelled). This is not an absolute current subscriber snapshot.
    - `newSubscribersCount` number, required — Number of subscription starts in this bucket. Counts every start, so a returning fan starting a new subscription counts again. Includes free trials and starts that were later refunded, and covers profile subscriptions, checkout-link subscriptions and fan-experience subscriptions.
    - `cancelledSubscribersCount` number, required — Number of subscription chains ending (final non-renewing expiry) in this bucket. This is a lapse, not the moment auto-renew was switched off.
  - `nextCursor` string, nullable, required — Cursor for next page, null if no more data

## 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.dev/fanvue/apis/fanvue-api.md) · [All operations](https://skmtc.dev/fanvue/apis/fanvue-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/fanvue/fanvue-api/revisions/dce5621fe589/schema)