---
title: "Get chatter leaderboard"
method: GET
path: "/agencies/insights/chatter-leaderboard"
---

# Get chatter leaderboard

`GET /agencies/insights/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.
<Info>Requires: Agency admin access</Info>

## Query parameters

- `startDate` string, date-time — 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.
- `endDate` string, date-time — 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.
- `chatterUuids` string — Comma-separated chatter UUIDs to filter by (max 100). Defaults to all chatters in the agency.

## Headers

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

## Response `200`

Chatter leaderboard data

- object
  - `data` object[], required
    - `chatterUuid` string, uuid, required — UUID of the chatter (agency team member)
    - `chatterName` string, required — Chatter's nickname within the agency, falling back to display name
    - `avatarUrl` string, nullable, required — URL of the chatter's avatar image, or null
    - `messages` integer, required — Total messages sent in the period
    - `ppvsSent` integer, required — Total pay-per-view messages sent in the period
    - `ppvsUnlocked` integer, required — Total pay-per-view messages unlocked by fans in the period
    - `revenue` integer, required — Total revenue from PPV unlocks in the period, in cents
    - `goldenRatio` number, required — Ratio of PPVs unlocked to messages sent (0 if no messages were sent)
    - `unlockRatio` number, required — Ratio of PPVs unlocked to PPVs sent (0 if no PPVs were sent)
    - `activeHours` number, required — Number of hours the chatter was active in the period
    - `eph` number, required — Earnings per active hour, in cents (0 if no active hours)
    - `avgResponseMs` number, nullable, required — Average response time in milliseconds, or null if no responses were tracked

## 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)