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

## Request

- Base URL: `https://api.fanvue.com`
- URL: `https://api.fanvue.com/creators/{creatorUserUuid}/insights/fan-retention-summary`
- Auth: OAuth 2
  - Authorization code: `https://auth.fanvue.com/oauth2/auth`
  - Token URL: `https://auth.fanvue.com/oauth2/token` scopes: `read:creator`, `read:insights`

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.dev/fanvue/apis/fanvue-api.md) - [All operations](https://skmtc.dev/fanvue/apis/fanvue-api/llms.txt) - [OpenAPI document](https://skmtc.dev/fanvue/apis/fanvue-api/revisions/966260af2770?raw)