> ## Documentation Index > Fetch the complete documentation index at: https://api.fanvue.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Get fan retention summary > Returns the authenticated 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. **Required scope** * `read:insights` — Access analytics, metrics, and insights data for performance tracking. ## OpenAPI ````yaml /openapi.json get /insights/fan-retention-summary openapi: 3.1.0 info: title: Fanvue API version: '0.1' servers: [] security: [] paths: /insights/fan-retention-summary: get: summary: Get fan retention summary description: >- Returns the authenticated 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. operationId: getFanRetentionSummary parameters: - $ref: '#/components/parameters/ApiVersionHeader' - schema: type: integer minimum: 1 maximum: 12 default: 6 description: >- Number of most-recent weekly snapshots to return (1-12, default: 6) required: false description: 'Number of most-recent weekly snapshots to return (1-12, default: 6)' name: periods in: query responses: '200': description: Weekly fan retention snapshots content: application/json: schema: type: object properties: snapshots: type: array items: type: object properties: periodStart: type: string format: date-time description: >- Start of the weekly snapshot period as a UTC ISO 8601 datetime string paidActiveFansCount: type: number description: Paid (subscribed) active fans at the end of the week prevPaidActiveFansCount: type: number description: Paid active fans in the previous week paidChurnedFansCount: type: number description: Paid fans who churned during the week paidRetainedFansCount: type: number description: Paid fans retained from the previous week paidNewFansCount: type: number description: Net-new paid fans gained during the week paidReactivatedFansCount: type: number description: Previously churned paid fans who returned paidFanChurnRate: type: number description: Paid fan churn rate for the week (0-1) paidFanNrr: type: number description: Net revenue retention for paid fans paidReactivationRate: type: number description: Paid fan reactivation rate for the week revenueCurrent: type: number description: Subscription revenue this week, in USD cents revenuePrevious: type: number description: Subscription revenue the previous week, in USD cents revenueRetained: type: number description: Revenue from retained fans, in USD cents revenueLost: type: number description: Revenue lost to churn, in USD cents revenueNewFans: type: number description: Revenue from new fans, in USD cents revenueReactivatedFans: type: number description: Revenue from reactivated fans, in USD cents ltvSimple: type: number description: Simple lifetime value estimate, in USD cents ltvWeighted: type: number description: Churn-weighted lifetime value estimate, in USD cents totalUniqueFans: type: number description: Total unique fans (paid + free) freeActiveFansCount: type: number description: Free active fans at the end of the week freeRetainedFansCount: type: number description: Free fans retained from the previous week freeNewFansCount: type: number description: Net-new free fans gained during the week freeReactivatedFansCount: type: number description: Previously churned free fans who returned freeChurnedFansCount: type: number description: Free fans who churned during the week freeFanChurnRate: type: number description: Free fan churn rate for the week (0-1) freeToPaidConversionCount: type: number description: Free fans who converted to paid during the week totalActiveFansCount: type: number description: Total active fans (paid + free) weeklyPostCount: type: number description: Posts published during the week weeklyPostingDays: type: number description: Distinct days the creator posted weeklySubscriberOnlyPosts: type: number description: Subscriber-only posts published weeklyFreePosts: type: number description: Free posts published weeklyPpvPosts: type: number description: Pay-per-view posts published weeklyAvgMediaPerPost: type: number description: Average media attachments per post weeklyPctPostsWithMedia: type: number description: Share of posts containing media (0-1) weeklyAvgLikesPerPost: type: number description: Average likes per post weeklyAvgCommentsPerPost: type: number description: Average comments per post weeklySingleMessagesSent: type: number description: One-to-one messages sent weeklyBroadcastMessagesSent: type: number description: Broadcast/mass messages sent weeklyUniqueFansMessaged: type: number description: Unique fans messaged weeklyAvgResponseTimeHours: type: number description: Average response time to fans, in hours weeklyPctRespondedWithin1h: type: number description: Share of fan messages answered within 1h (0-1) weeklyPctRespondedWithin4h: type: number description: Share of fan messages answered within 4h (0-1) weeklyPctRespondedWithin12h: type: number description: Share of fan messages answered within 12h (0-1) weeklyFansRespondedCount: type: number description: Fans the creator responded to weeklyFanResponseRate: type: number description: Share of fans responded to (0-1) required: - periodStart - paidActiveFansCount - prevPaidActiveFansCount - paidChurnedFansCount - paidRetainedFansCount - paidNewFansCount - paidReactivatedFansCount - paidFanChurnRate - paidFanNrr - paidReactivationRate - revenueCurrent - revenuePrevious - revenueRetained - revenueLost - revenueNewFans - revenueReactivatedFans - ltvSimple - ltvWeighted - totalUniqueFans - freeActiveFansCount - freeRetainedFansCount - freeNewFansCount - freeReactivatedFansCount - freeChurnedFansCount - freeFanChurnRate - freeToPaidConversionCount - totalActiveFansCount - weeklyPostCount - weeklyPostingDays - weeklySubscriberOnlyPosts - weeklyFreePosts - weeklyPpvPosts - weeklyAvgMediaPerPost - weeklyPctPostsWithMedia - weeklyAvgLikesPerPost - weeklyAvgCommentsPerPost - weeklySingleMessagesSent - weeklyBroadcastMessagesSent - weeklyUniqueFansMessaged - weeklyAvgResponseTimeHours - weeklyPctRespondedWithin1h - weeklyPctRespondedWithin4h - weeklyPctRespondedWithin12h - weeklyFansRespondedCount - weeklyFanResponseRate description: Weekly fan-health snapshots, most recent first required: - snapshots example: snapshots: - periodStart: '2026-03-16T00:00:00.000Z' paidActiveFansCount: 1240 prevPaidActiveFansCount: 1180 paidChurnedFansCount: 95 paidRetainedFansCount: 1085 paidNewFansCount: 120 paidReactivatedFansCount: 35 paidFanChurnRate: 0.08 paidFanNrr: 1.04 paidReactivationRate: 0.03 revenueCurrent: 1860000 revenuePrevious: 1770000 revenueRetained: 1627500 revenueLost: 142500 revenueNewFans: 180000 revenueReactivatedFans: 52500 ltvSimple: 18750 ltvWeighted: 21300 totalUniqueFans: 4820 freeActiveFansCount: 3580 freeRetainedFansCount: 3210 freeNewFansCount: 410 freeReactivatedFansCount: 60 freeChurnedFansCount: 300 freeFanChurnRate: 0.08 freeToPaidConversionCount: 48 totalActiveFansCount: 4820 weeklyPostCount: 9 weeklyPostingDays: 5 weeklySubscriberOnlyPosts: 4 weeklyFreePosts: 3 weeklyPpvPosts: 2 weeklyAvgMediaPerPost: 2.4 weeklyPctPostsWithMedia: 0.89 weeklyAvgLikesPerPost: 156 weeklyAvgCommentsPerPost: 23 weeklySingleMessagesSent: 540 weeklyBroadcastMessagesSent: 3 weeklyUniqueFansMessaged: 310 weeklyAvgResponseTimeHours: 1.6 weeklyPctRespondedWithin1h: 0.62 weeklyPctRespondedWithin4h: 0.85 weeklyPctRespondedWithin12h: 0.95 weeklyFansRespondedCount: 290 weeklyFanResponseRate: 0.94 - periodStart: '2026-03-09T00:00:00.000Z' paidActiveFansCount: 1180 prevPaidActiveFansCount: 1150 paidChurnedFansCount: 88 paidRetainedFansCount: 1062 paidNewFansCount: 90 paidReactivatedFansCount: 28 paidFanChurnRate: 0.077 paidFanNrr: 1.02 paidReactivationRate: 0.024 revenueCurrent: 1770000 revenuePrevious: 1725000 revenueRetained: 1593000 revenueLost: 132000 revenueNewFans: 135000 revenueReactivatedFans: 42000 ltvSimple: 18200 ltvWeighted: 20600 totalUniqueFans: 4710 freeActiveFansCount: 3470 freeRetainedFansCount: 3160 freeNewFansCount: 360 freeReactivatedFansCount: 50 freeChurnedFansCount: 310 freeFanChurnRate: 0.082 freeToPaidConversionCount: 41 totalActiveFansCount: 4710 weeklyPostCount: 7 weeklyPostingDays: 4 weeklySubscriberOnlyPosts: 3 weeklyFreePosts: 3 weeklyPpvPosts: 1 weeklyAvgMediaPerPost: 2.1 weeklyPctPostsWithMedia: 0.86 weeklyAvgLikesPerPost: 142 weeklyAvgCommentsPerPost: 19 weeklySingleMessagesSent: 505 weeklyBroadcastMessagesSent: 2 weeklyUniqueFansMessaged: 295 weeklyAvgResponseTimeHours: 1.9 weeklyPctRespondedWithin1h: 0.58 weeklyPctRespondedWithin4h: 0.82 weeklyPctRespondedWithin12h: 0.93 weeklyFansRespondedCount: 276 weeklyFanResponseRate: 0.92 '400': description: Bad Request - API version not supported OR validation failed content: application/json: schema: oneOf: - $ref: '#/components/schemas/UnsupportedVersionError' - $ref: '#/components/schemas/ValidationError' '401': $ref: '#/components/responses/UnauthorizedResponse' '403': $ref: '#/components/responses/UnauthorizedResponse' '410': $ref: '#/components/responses/SunsetVersionResponse' '429': $ref: '#/components/responses/RateLimitResponse' security: - BearerAuth: - read:insights components: parameters: ApiVersionHeader: name: X-Fanvue-API-Version in: header required: true schema: type: string default: '2025-06-26' example: '2025-06-26' description: API version to use for the request schemas: UnsupportedVersionError: type: object properties: error: type: string message: type: string required: - error - message description: API version not supported ValidationError: type: object properties: errors: type: array items: type: string required: - errors description: Request validation failed responses: UnauthorizedResponse: description: Unauthorized Response content: application/json: schema: type: object properties: error: type: string required: - error SunsetVersionResponse: description: API version no longer supported (sunset) content: application/json: schema: type: object properties: error: type: string message: type: string nextVersion: type: string required: - error - message RateLimitResponse: description: Too many requests - rate limit exceeded headers: Retry-After: description: Number of seconds to wait before retrying the request schema: type: integer X-RateLimit-Limit: description: The maximum number of requests allowed in the current window schema: type: integer X-RateLimit-Remaining: description: The number of requests remaining in the current window schema: type: integer X-RateLimit-Reset: description: The Unix timestamp (seconds) when the rate limit window resets schema: type: integer content: application/json: schema: type: object properties: error: type: string required: - error securitySchemes: BearerAuth: type: oauth2 description: >- OAuth 2.0 access token, presented as a JWT bearer token in the `Authorization` header. Obtain a token via the authorization-code flow; the scopes granted to the token determine which operations it may call. flows: authorizationCode: authorizationUrl: https://auth.fanvue.com/oauth2/auth tokenUrl: https://auth.fanvue.com/oauth2/token refreshUrl: https://auth.fanvue.com/oauth2/token scopes: read:self: >- Access your own user profile information, including basic account details and settings. read:chat: >- Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history. write:chat: >- Create new chats and send messages. This scope is required for any chat-related actions that modify data. read:experience: >- Exchange a fan's experience token for the resolved experience and the fan's identity, so an embedded fan-facing experience can render the right content. write:experience: >- Request that the creator publish or unpublish a fan-facing experience. The app mints a request token; the creator confirms and Fanvue performs the change. read:fan: Access fan-related data and information within the platform. read:post: Read posts, including post details, comments, likes, and tips. write:post: Create, edit, and manage posts and content on behalf of users. read:media: Access media files, images, videos, and other content assets. write:media: >- Upload, modify, and manage media files and content assets. Also required for vault folder management. read:creator: >- Access creator profiles, content, and creator-specific information. write:creator: Modify creator profiles, settings, and creator-specific data. read:insights: >- Access analytics, metrics, and insights data for performance tracking. read:tracking_links: >- Read tracking links and the users associated with them, including per-user tracking metadata. write:tracking_links: Create and delete tracking links. read:agency: Read agency information, including the agency's team members. write:agency: >- Manage agency team members and invites, including inviting new team members and creators. ````