---
title: "List per-creator-per-day new-follower counts across all agency creators"
method: GET
path: "/agencies/followers-history"
---

# List per-creator-per-day new-follower counts across all agency creators

`GET /agencies/followers-history`

Returns a single paginated stream of per-creator-per-day new-follower 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:
- `newFollowersCount` = number of new follows recorded in the day bucket for the creator
- `total` = cumulative new followers for the creator from the beginning of the requested range (running sum of `newFollowersCount`)

<Warning>Follows are hard-deleted on unfollow — there is no record of unfollows. As a result this series only counts follows that still exist, has no unfollow/net-loss column, and historical days are survivorship-biased (a follow that was later undone leaves no trace). `total` is therefore cumulative new follows gained within the range, **not** an absolute or net follower count. For the current follower count, use the account/audience endpoints instead.</Warning>

<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 new-follower counts across the agency's creators

- object
  - `data` object[], required — Array of per-creator-per-day new-follower 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 new follows are bucketed on (YYYY-MM-DD)
    - `total` integer, required — Cumulative new followers for this creator from the start of the requested range (running sum of newFollowersCount). Not an absolute follower count: it excludes followers gained before the range and cannot account for unfollows (see newFollowersCount).
    - `newFollowersCount` integer, required — Number of new follows recorded on this day for this creator. Survivorship-biased: follows that were later undone are hard-deleted with no trace, so historical days only count follows that still exist today.
  - `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)