Get subscriber events over time
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. </Info>
Query parameters
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.
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.
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.
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 for pagination - If given, pass nextCursor to get the next page.
Cursor for pagination - If given, pass nextCursor to get the next page.
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.
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
API version to use for the request
Response
Subscribers data with cursor pagination
Changes
No recorded changes to this endpoint across all 2 revisions of this API.