---
title: "Get fan retention summary for a creator"
method: GET
path: "/creators/{creatorUserUuid}/insights/fan-retention-summary"
---

# Get fan retention summary for a creator

`GET /creators/{creatorUserUuid}/insights/fan-retention-summary`

Returns the specified creator's weekly fan-health snapshots, including paid/free active fans, churn, retention, reactivation, revenue retention, LTV, free-to-paid conversion, and engagement metrics. Snapshots are computed weekly by the data warehouse (not real-time); the most recent snapshot may be up to 7 days old.

## Path parameters

- `creatorUserUuid` string, uuid, required

## Query parameters

- `periods` integer — Number of most-recent weekly snapshots to return (1-12, default: 6)

## Headers

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

## Response `200`

Weekly fan retention snapshots

- object
  - `snapshots` object[], required — Weekly fan-health snapshots, most recent first
    - `periodStart` string, date-time, required — Start of the weekly snapshot period as a UTC ISO 8601 datetime string
    - `paidActiveFansCount` number, required — Paid (subscribed) active fans at the end of the week
    - `prevPaidActiveFansCount` number, required — Paid active fans in the previous week
    - `paidChurnedFansCount` number, required — Paid fans who churned during the week
    - `paidRetainedFansCount` number, required — Paid fans retained from the previous week
    - `paidNewFansCount` number, required — Net-new paid fans gained during the week
    - `paidReactivatedFansCount` number, required — Previously churned paid fans who returned
    - `paidFanChurnRate` number, required — Paid fan churn rate for the week (0-1)
    - `paidFanNrr` number, required — Net revenue retention for paid fans
    - `paidReactivationRate` number, required — Paid fan reactivation rate for the week
    - `revenueCurrent` number, required — Subscription revenue this week, in USD cents
    - `revenuePrevious` number, required — Subscription revenue the previous week, in USD cents
    - `revenueRetained` number, required — Revenue from retained fans, in USD cents
    - `revenueLost` number, required — Revenue lost to churn, in USD cents
    - `revenueNewFans` number, required — Revenue from new fans, in USD cents
    - `revenueReactivatedFans` number, required — Revenue from reactivated fans, in USD cents
    - `ltvSimple` number, required — Simple lifetime value estimate, in USD cents
    - `ltvWeighted` number, required — Churn-weighted lifetime value estimate, in USD cents
    - `totalUniqueFans` number, required — Total unique fans (paid + free)
    - `freeActiveFansCount` number, required — Free active fans at the end of the week
    - `freeRetainedFansCount` number, required — Free fans retained from the previous week
    - `freeNewFansCount` number, required — Net-new free fans gained during the week
    - `freeReactivatedFansCount` number, required — Previously churned free fans who returned
    - `freeChurnedFansCount` number, required — Free fans who churned during the week
    - `freeFanChurnRate` number, required — Free fan churn rate for the week (0-1)
    - `freeToPaidConversionCount` number, required — Free fans who converted to paid during the week
    - `totalActiveFansCount` number, required — Total active fans (paid + free)
    - `weeklyPostCount` number, required — Posts published during the week
    - `weeklyPostingDays` number, required — Distinct days the creator posted
    - `weeklySubscriberOnlyPosts` number, required — Subscriber-only posts published
    - `weeklyFreePosts` number, required — Free posts published
    - `weeklyPpvPosts` number, required — Pay-per-view posts published
    - `weeklyAvgMediaPerPost` number, required — Average media attachments per post
    - `weeklyPctPostsWithMedia` number, required — Share of posts containing media (0-1)
    - `weeklyAvgLikesPerPost` number, required — Average likes per post
    - `weeklyAvgCommentsPerPost` number, required — Average comments per post
    - `weeklySingleMessagesSent` number, required — One-to-one messages sent
    - `weeklyBroadcastMessagesSent` number, required — Broadcast/mass messages sent
    - `weeklyUniqueFansMessaged` number, required — Unique fans messaged
    - `weeklyAvgResponseTimeHours` number, required — Average response time to fans, in hours
    - `weeklyPctRespondedWithin1h` number, required — Share of fan messages answered within 1h (0-1)
    - `weeklyPctRespondedWithin4h` number, required — Share of fan messages answered within 4h (0-1)
    - `weeklyPctRespondedWithin12h` number, required — Share of fan messages answered within 12h (0-1)
    - `weeklyFansRespondedCount` number, required — Fans the creator responded to
    - `weeklyFanResponseRate` number, required — Share of fans responded to (0-1)

## Other responses

- `400` — Bad Request - API version not supported OR validation failed OR invalid UUID
- `401` — Unauthorized Response
- `403` — Unauthorized Response
- `404` — Not Found 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)