---
title: "List per-creator-per-day subscriber events across all agency creators"
method: GET
path: "/agencies/subscribers-history"
---

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

`GET /agencies/subscribers-history`

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.
<Info>Requires: Agency admin access</Info>

## Query parameters

- `page` integer — Page number to retrieve (starts from 1)
- `size` integer — Number of items to return per page (1-50, default: 15)
- `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[] — Comma-separated list of creator UUIDs (max 50)

## Headers

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

## Response `200`

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

- object
  - `data` object[], required — Array of per-creator-per-day subscriber event rows across the agency's creators
    - `creatorUuid` string, uuid, required — UUID of the agency-managed creator the row belongs to
    - `date` string, date, required — UTC calendar day the events are bucketed on (YYYY-MM-DD)
    - `total` integer, required — Cumulative net change in active subscribers for this creator from the start of the requested range (newSubscribersCount - cancelledSubscribersCount, running)
    - `newSubscribersCount` integer, required — Number of new subscription chains started on this day for this creator
    - `cancelledSubscribersCount` integer, required — Number of subscription chains ending (final non-renewing expiry) on this day for this creator
    - `renewalOnCount` integer, required — Number of auto-renewing (paid, recurring) subscriptions that started on this day for this creator. A subscription has auto-renew on when created, so this counts non-free-trial starts.
    - `renewalOffCount` integer, required — Number of subscriptions whose auto-renewal was switched off on this day for this creator. The subscription stays active until it expires.
    - `freeTrialCount` integer, required — Number of free-trial subscriptions that started on this day for this creator
    - `expiredCount` integer, required — Number of subscriptions that lapsed (expired) on this day for this creator. Derived from the subscriptions table, so it may differ slightly from cancelledSubscribersCount, which derives the same notion from the invoice chain.
  - `pagination` object, required — Pagination information
    - `page` number, required — Current page number
    - `size` number, required — Number of records returned in this response
    - `hasMore` boolean, required — Whether there are more items available on subsequent pages

## 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)