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

Data is aggregated daily with timezone-aware boundaries. When dates include timezone offsets, results are normalized to midnight in that timezone (expressed as UTC).

<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). Data is aggregated daily with timezone-aware boundaries. Time component is ignored for daily aggregation.
- `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. Data is aggregated daily with timezone-aware boundaries. Time component is ignored for daily aggregation.
- `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 — Date as UTC ISO 8601 datetime string representing midnight in the requested timezone (e.g., '2024-01-05T23:00:00.000Z' for midnight +01:00)
    - `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 new subscribers for this period
    - `cancelledSubscribersCount` number, required — Number of cancelled subscribers for this period
  - `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.net/fanvue/apis/fanvue-api.md) · [All operations](https://skmtc.net/fanvue/apis/fanvue-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/fanvue/fanvue-api/revisions/c5ddcd5c7e72/schema)