> ## 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.
# List chatter earnings by creator (cursor-paginated)
> Returns one row per chatter and creator for the authenticated user's agency over the requested period: what each chatter earned on each creator, for payroll. The rows come from the same read as the earnings leaderboard breakdown, so the two always agree.
Earnings are attributed to the purchase date. `revenue` is `ppvRevenue` plus `tipsRevenue`, all gross USD cents. A tip is credited to the chatter who sent the last 1:1 message in that chat shortly before it was paid. Refunds and chargebacks are reported in their own fields and never subtracted. Net figures are after the Fanvue fee.
Chatters whose accounts are deleted or banned, and tips credited to no chatter, are not returned, so the rows alone do not sum to the agency's total chat earnings. `totals` does include them: it is the same for every page and equals the leaderboard's totals for the same filters and period.
Rows are ordered by `revenue` descending. Page with the opaque `nextCursor` from the previous response, keeping the same filters. Pages are re-read on every request, so a period that includes the current day can shift between pages as new sales land; request a period that has ended for a stable payroll export. Without both `startDate` and `endDate` the period is all time.
Agencies without the chatter earnings breakdown enabled get a 404.
Requires: Agency admin access
> [!NOTE]
>
> **Required scope**
>
> * `read:agency` — Read agency information, including the agency's team members.
## OpenAPI
````yaml /openapi-v1.json get /v1/agencies/insights/chatter-earnings
openapi: 3.1.0
info:
title: Fanvue API
version: '0.1'
servers:
- url: https://api.fanvue.com
security: []
paths:
/v1/agencies/insights/chatter-earnings:
get:
summary: List chatter earnings by creator (cursor-paginated)
description: >-
Returns one row per chatter and creator for the authenticated user's
agency over the requested period: what each chatter earned on each
creator, for payroll. The rows come from the same read as the earnings
leaderboard breakdown, so the two always agree.
Earnings are attributed to the purchase date. `revenue` is `ppvRevenue`
plus `tipsRevenue`, all gross USD cents. A tip is credited to the
chatter who sent the last 1:1 message in that chat shortly before it was
paid. Refunds and chargebacks are reported in their own fields and never
subtracted. Net figures are after the Fanvue fee.
Chatters whose accounts are deleted or banned, and tips credited to no
chatter, are not returned, so the rows alone do not sum to the agency's
total chat earnings. `totals` does include them: it is the same for
every page and equals the leaderboard's totals for the same filters and
period.
Rows are ordered by `revenue` descending. Page with the opaque
`nextCursor` from the previous response, keeping the same filters. Pages
are re-read on every request, so a period that includes the current day
can shift between pages as new sales land; request a period that has
ended for a stable payroll export. Without both `startDate` and
`endDate` the period is all time.
Agencies without the chatter earnings breakdown enabled get a 404.
Requires: Agency admin access
operationId: getChatterEarnings
parameters:
- $ref: '#/components/parameters/ApiVersionHeader'
- schema:
type: string
description: >-
Opaque pagination cursor from a previous response's `nextCursor`.
Omit to fetch the first page.
required: false
description: >-
Opaque pagination cursor from a previous response's `nextCursor`.
Omit to fetch the first page.
name: cursor
in: query
- schema:
type: integer
minimum: 1
maximum: 50
default: 15
description: 'Number of items to return (1-50, default: 15)'
required: false
description: 'Number of items to return (1-50, default: 15)'
name: size
in: query
- 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
- schema:
type: string
format: uuid
description: >-
UUID of one of the agency's creators to restrict rows to. A
creator outside the agency fails the request with 403. Defaults to
every creator.
required: false
description: >-
UUID of one of the agency's creators to restrict rows to. A creator
outside the agency fails the request with 403. Defaults to every
creator.
name: creatorUuid
in: query
responses:
'200':
description: Cursor-paginated chatter earnings by creator
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
isCurrentMember:
type: boolean
description: >-
False when the chatter has left the agency; their
earnings in range still count
creatorUuid:
type:
- string
- 'null'
format: uuid
description: >-
UUID of the creator the earnings were made for, or
null if it cannot be resolved
creatorName:
type:
- string
- 'null'
description: Creator's display name, or null
creatorHandle:
type:
- string
- 'null'
description: Creator's handle, or null
creatorAvatarUrl:
type:
- string
- 'null'
description: URL of the creator's avatar image, or null
revenue:
type: integer
description: >-
Gross earnings in cents, ppvRevenue plus
tipsRevenue, by purchase date
ppvRevenue:
type: integer
description: >-
Gross pay-per-view sales in cents, by purchase date.
Refunds and chargebacks are not subtracted.
ppvsSold:
type: integer
description: Pay-per-view messages sold, by purchase date
thisPeriodRevenue:
type: integer
description: >-
Of ppvRevenue, the cents from content sent within
the date range
earlierSendsRevenue:
type: integer
description: >-
Of ppvRevenue, the cents from content sent before
the date range start. 0 when no range is given.
earlierSendsCount:
type: integer
description: Sales counted in earlierSendsRevenue
tipsRevenue:
type: integer
description: >-
Gross chat tips in cents credited to the chatter, by
purchase date. Refunds and chargebacks are not
subtracted.
tipsCount:
type: integer
description: Tips counted in tipsRevenue
netRevenue:
type: integer
description: >-
Net counterpart of revenue, in cents, after the
Fanvue fee
ppvNetRevenue:
type: integer
description: Net counterpart of ppvRevenue, in cents
thisPeriodNetRevenue:
type: integer
description: Net counterpart of thisPeriodRevenue, in cents
earlierSendsNetRevenue:
type: integer
description: Net counterpart of earlierSendsRevenue, in cents
tipsNetRevenue:
type: integer
description: Net counterpart of tipsRevenue, in cents
fanvueFee:
type: integer
description: >-
Fanvue fee on the pay-per-view sales and tips, in
cents
refundAmount:
type: integer
description: >-
Gross cents of the sales and tips later refunded.
Reported, never subtracted
refundsCount:
type: integer
description: Count of the sales and tips later refunded
chargebackAmount:
type: integer
description: >-
Gross cents of the sales and tips later charged
back. Reported, never subtracted
chargebacksCount:
type: integer
description: Count of the sales and tips later charged back
required:
- chatterUuid
- chatterName
- avatarUrl
- isCurrentMember
- creatorUuid
- creatorName
- creatorHandle
- creatorAvatarUrl
- revenue
- ppvRevenue
- ppvsSold
- thisPeriodRevenue
- earlierSendsRevenue
- earlierSendsCount
- tipsRevenue
- tipsCount
- netRevenue
- ppvNetRevenue
- thisPeriodNetRevenue
- earlierSendsNetRevenue
- tipsNetRevenue
- fanvueFee
- refundAmount
- refundsCount
- chargebackAmount
- chargebacksCount
description: >-
Array of chatter × creator rows, ordered by revenue
descending
nextCursor:
type:
- string
- 'null'
description: >-
Opaque cursor for the next page, or null when there are no
more results
total:
type:
- integer
- 'null'
description: >-
Total number of items across all pages, or null when no
count is computed
totals:
type: object
properties:
revenue:
type: integer
description: >-
Gross earnings in cents, ppvRevenue plus tipsRevenue,
by purchase date
ppvRevenue:
type: integer
description: >-
Gross pay-per-view sales in cents, by purchase date.
Refunds and chargebacks are not subtracted.
ppvsSold:
type: integer
description: Pay-per-view messages sold, by purchase date
thisPeriodRevenue:
type: integer
description: >-
Of ppvRevenue, the cents from content sent within the
date range
earlierSendsRevenue:
type: integer
description: >-
Of ppvRevenue, the cents from content sent before the
date range start. 0 when no range is given.
earlierSendsCount:
type: integer
description: Sales counted in earlierSendsRevenue
tipsRevenue:
type: integer
description: >-
Gross chat tips in cents credited to the chatter, by
purchase date. Refunds and chargebacks are not
subtracted.
tipsCount:
type: integer
description: Tips counted in tipsRevenue
netRevenue:
type: integer
description: >-
Net counterpart of revenue, in cents, after the Fanvue
fee
ppvNetRevenue:
type: integer
description: Net counterpart of ppvRevenue, in cents
thisPeriodNetRevenue:
type: integer
description: Net counterpart of thisPeriodRevenue, in cents
earlierSendsNetRevenue:
type: integer
description: Net counterpart of earlierSendsRevenue, in cents
tipsNetRevenue:
type: integer
description: Net counterpart of tipsRevenue, in cents
fanvueFee:
type: integer
description: >-
Fanvue fee on the pay-per-view sales and tips, in
cents
refundAmount:
type: integer
description: >-
Gross cents of the sales and tips later refunded.
Reported, never subtracted
refundsCount:
type: integer
description: Count of the sales and tips later refunded
chargebackAmount:
type: integer
description: >-
Gross cents of the sales and tips later charged back.
Reported, never subtracted
chargebacksCount:
type: integer
description: Count of the sales and tips later charged back
required:
- revenue
- ppvRevenue
- ppvsSold
- thisPeriodRevenue
- earlierSendsRevenue
- earlierSendsCount
- tipsRevenue
- tipsCount
- netRevenue
- ppvNetRevenue
- thisPeriodNetRevenue
- earlierSendsNetRevenue
- tipsNetRevenue
- fanvueFee
- refundAmount
- refundsCount
- chargebackAmount
- chargebacksCount
description: >-
Every chatter's earnings summed for the filters, across
all pages: the rows plus deleted or banned chatters and
tips credited to no chatter. Equals the earnings
leaderboard's totals for the same agency, filters and
period.
required:
- data
- nextCursor
- total
- totals
example:
data:
- chatterUuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
chatterName: Top Performer
avatarUrl: https://cdn.example.com/avatars/a1b2c3d4.jpg
isCurrentMember: true
creatorUuid: c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8
creatorName: Sarah Jones
creatorHandle: sarah-jones
creatorAvatarUrl: null
revenue: 132500
ppvRevenue: 124500
ppvsSold: 41
thisPeriodRevenue: 110000
earlierSendsRevenue: 14500
earlierSendsCount: 5
tipsRevenue: 8000
tipsCount: 3
netRevenue: 106000
ppvNetRevenue: 99600
thisPeriodNetRevenue: 88000
earlierSendsNetRevenue: 11600
tipsNetRevenue: 6400
fanvueFee: 26500
refundAmount: 2000
refundsCount: 1
chargebackAmount: 0
chargebacksCount: 0
- chatterUuid: b2c3d4e5-f6a7-8901-bcde-f12345678901
chatterName: Rookie
avatarUrl: null
isCurrentMember: false
creatorUuid: c3d4e5f6-7g8h-9i0j-1k2l-m3n4o5p6q7r8
creatorName: Sarah Jones
creatorHandle: sarah-jones
creatorAvatarUrl: null
revenue: 6000
ppvRevenue: 6000
ppvsSold: 3
thisPeriodRevenue: 6000
earlierSendsRevenue: 0
earlierSendsCount: 0
tipsRevenue: 0
tipsCount: 0
netRevenue: 4800
ppvNetRevenue: 4800
thisPeriodNetRevenue: 4800
earlierSendsNetRevenue: 0
tipsNetRevenue: 0
fanvueFee: 1200
refundAmount: 0
refundsCount: 0
chargebackAmount: 0
chargebacksCount: 0
nextCursor: null
total: 2
totals:
revenue: 141000
ppvRevenue: 130500
ppvsSold: 44
thisPeriodRevenue: 116000
earlierSendsRevenue: 14500
earlierSendsCount: 5
tipsRevenue: 10500
tipsCount: 4
netRevenue: 112800
ppvNetRevenue: 104400
thisPeriodNetRevenue: 92800
earlierSendsNetRevenue: 11600
tipsNetRevenue: 8400
fanvueFee: 28200
refundAmount: 2000
refundsCount: 1
chargebackAmount: 0
chargebacksCount: 0
'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'
'404':
$ref: '#/components/responses/NotFoundResponse'
'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
NotFoundResponse:
description: Not Found Response
content:
application/json:
schema:
type: object
properties:
message:
type: string
required:
- message
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.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.