> ## 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 chatter leaderboard
> Returns per-chatter performance metrics for the authenticated user's agency over a specified time period.
Each row includes message volume, PPV sends and unlocks, revenue, derived ratios (golden ratio, unlock ratio), active hours, earnings per active hour, and average response time. Rows are sorted by revenue descending.
Historical stats are precomputed daily and the current UTC day is included live at read time. Performance metrics (messages, PPV sends and unlocks, ratios, active hours, response time) are attributed to the day the content was sent. Revenue is attributed to the day of purchase, and earnings per active hour divides that purchase-date revenue by send-date active hours.
Requires: Agency admin access
**Required scope**
* `read:agency` — Read agency information, including the agency's team members.
## OpenAPI
````yaml /openapi.json get /agencies/insights/chatter-leaderboard
openapi: 3.1.0
info:
title: Fanvue API
version: '0.1'
servers: []
security: []
paths:
/agencies/insights/chatter-leaderboard:
get:
summary: Get chatter leaderboard
description: >-
Returns per-chatter performance metrics for the authenticated user's
agency over a specified time period.
Each row includes message volume, PPV sends and unlocks, revenue,
derived ratios (golden ratio, unlock ratio), active hours, earnings per
active hour, and average response time. Rows are sorted by revenue
descending.
Historical stats are precomputed daily and the current UTC day is
included live at read time. Performance metrics (messages, PPV sends and
unlocks, ratios, active hours, response time) are attributed to the day
the content was sent. Revenue is attributed to the day of purchase, and
earnings per active hour divides that purchase-date revenue by send-date
active hours.
Requires: Agency admin access
operationId: getChatterLeaderboard
parameters:
- $ref: '#/components/parameters/ApiVersionHeader'
- schema:
type: string
format: date-time
description: >-
Start date as ISO 8601 datetime string with optional timezone
offset (e.g., 2024-10-20T00:00:00+01:00 or 2024-10-20T00:00:00Z).
Stats are aggregated by UTC day.
required: false
description: >-
Start date as ISO 8601 datetime string with optional timezone offset
(e.g., 2024-10-20T00:00:00+01:00 or 2024-10-20T00:00:00Z). Stats are
aggregated by UTC day.
name: startDate
in: query
- schema:
type: string
format: date-time
description: >-
End date as ISO 8601 datetime string with optional timezone offset
(e.g., 2024-10-25T00:00:00+01:00 or 2024-10-25T00:00:00Z). Stats
are aggregated by UTC day.
required: false
description: >-
End date as ISO 8601 datetime string with optional timezone offset
(e.g., 2024-10-25T00:00:00+01:00 or 2024-10-25T00:00:00Z). Stats are
aggregated by UTC day.
name: endDate
in: query
- schema:
type: string
description: >-
Comma-separated chatter UUIDs to filter by (max 100). Defaults to
all chatters in the agency.
required: false
description: >-
Comma-separated chatter UUIDs to filter by (max 100). Defaults to
all chatters in the agency.
name: chatterUuids
in: query
responses:
'200':
description: Chatter leaderboard data
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
chatterUuid:
type: string
format: uuid
description: UUID of the chatter (agency team member)
chatterName:
type: string
description: >-
Chatter's nickname within the agency, falling back
to display name
avatarUrl:
type:
- string
- 'null'
description: URL of the chatter's avatar image, or null
messages:
type: integer
description: Total messages sent in the period
ppvsSent:
type: integer
description: Total pay-per-view messages sent in the period
ppvsUnlocked:
type: integer
description: >-
Total pay-per-view messages unlocked by fans in the
period
revenue:
type: integer
description: >-
Total revenue from PPV unlocks in the period, in
cents
goldenRatio:
type: number
description: >-
Ratio of PPVs unlocked to messages sent (0 if no
messages were sent)
unlockRatio:
type: number
description: >-
Ratio of PPVs unlocked to PPVs sent (0 if no PPVs
were sent)
activeHours:
type: number
description: Number of hours the chatter was active in the period
eph:
type: number
description: >-
Earnings per active hour, in cents (0 if no active
hours)
avgResponseMs:
type:
- number
- 'null'
description: >-
Average response time in milliseconds, or null if no
responses were tracked
required:
- chatterUuid
- chatterName
- avatarUrl
- messages
- ppvsSent
- ppvsUnlocked
- revenue
- goldenRatio
- unlockRatio
- activeHours
- eph
- avgResponseMs
required:
- data
example:
data:
- chatterUuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
chatterName: Top Performer
avatarUrl: https://cdn.example.com/avatars/a1b2c3d4.jpg
messages: 1240
ppvsSent: 86
ppvsUnlocked: 41
revenue: 124500
goldenRatio: 0.033
unlockRatio: 0.477
activeHours: 38.5
eph: 3233
avgResponseMs: 45200
- chatterUuid: b2c3d4e5-f6a7-8901-bcde-f12345678901
chatterName: Rookie
avatarUrl: null
messages: 320
ppvsSent: 12
ppvsUnlocked: 3
revenue: 6000
goldenRatio: 0.009
unlockRatio: 0.25
activeHours: 8
eph: 750
avgResponseMs: null
'400':
description: >-
Bad Request - API version not supported OR validation failed (dates,
sources, cursor, pagination)
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:agency
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.
````