---
title: "Get earnings data for a creator"
method: GET
path: "/creators/{creatorUserUuid}/insights/earnings"
---

# Get earnings data for a creator

`GET /creators/{creatorUserUuid}/insights/earnings`

Returns cursor-paginated invoice data for the specified creator over a specified time period. Each transaction includes information about the fan who made the payment. Reversals are included as `refund`/`chargeback` rows with negative gross (matching /insights/spending); filter them with `source`.

## Path parameters

- `creatorUserUuid` string, uuid, required

## 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).
- `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). Non-inclusive - data before this date is included.
- `source` EarningSource[] — Comma-separated list of earning sources
- `transactionOrderIds` string[] — Comma-separated transaction order IDs (max 100)
- `cursor` string — Cursor for pagination - If given, pass `nextCursor` to get the next page.
- `size` number — Number of items to return per page (1-50, default: 20). When omitted on a cursor request, the size from the previous page (carried in the cursor) is reused.

## Headers

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

## Response `200`

Creator earnings data with cursor pagination

- object
  - `data` object[], required
    - `date` string, required — Payment date as UTC ISO 8601 datetime string
    - `gross` number, required — Amount the fan paid, converted to USD cents
    - `net` number, required — Creator's cut after Fanvue fees, in USD cents
    - `currency` string, nullable, required — Informational only — the local currency the fan originally paid in (e.g. 'BRL'). The gross and net amounts are already converted to USD cents regardless of this value.
    - `source` 'all' | 'affiliate' | 'appStore' | 'checkoutLink' | 'fanExperience' | 'mediaLink' | 'message' | 'post' | 'referral' | 'renewal' | 'subscription' | 'tip' | 'giveaway' | 'refund' | 'chargeback', required — Earning source. Reversals are surfaced here too: `refund` and `chargeback` rows carry negative gross/net, matching /insights/spending.
    - `transactionOrderId` string, required — Transaction order ID
    - `transactionOrderStatus` 'availableForPayout' | 'pendingBalance', required — Transaction order status
    - `reversedTransactionOrderId` string — Only on `refund` and `chargeback` rows: the `transactionOrderId` of the original transaction this row reverses. A reversal never rewrites the original transaction, so use this to link the two.
    - `messageUuid` string, uuid — Message UUID when source is message (e.g. paid chat or broadcast message). Also present on tip rows, where it identifies the chat message Fanvue writes into the thread to record the tip — including for tips sent on a post. On a tip it is therefore not a signal that the tip came from a chat; use `tipContext` and `postUuid` for that.
    - `messageType` 'AUTOMATED_CANCELED' | 'AUTOMATED_NEW_FOLLOWER' | 'AUTOMATED_NEW_PURCHASE' | 'AUTOMATED_NEW_SUBSCRIBER' | 'AUTOMATED_RE_SUBSCRIBED' | 'AUTOMATED_RENEWED' | 'AUTOMATED_FIRST_MESSAGE_REPLY' | 'AUTOMATED_CHAT_MESSAGE_REPLY' | 'BROADCAST' | 'CHAT_TEXT_GENERATION' | 'CHAT_TEXT_REWRITE' | 'CHAT_TEXT_REPLY' | 'GHOST_PROMOTION' | 'MARKETING_KYC' | 'TIP' | 'LOCKED_MESSAGE_UNLOCKED' | 'VOICE_CALL' | 'SINGLE_RECIPIENT' — Underlying chat message type when source is message. Same values as the `type` field on the messages API — e.g. SINGLE_RECIPIENT (1-to-1 DM), BROADCAST / GHOST_PROMOTION (mass message), AUTOMATED_* (automated message). Use it to distinguish direct, mass, and automated message earnings.
    - `postUuid` string, uuid — Post UUID when source is post
    - `tipContext` 'post' | 'message' — Context of a tip when source is tip. `post` when the tip was sent on a post — `postUuid` identifies which. `message` for every other tip. Read `message` as 'not on a post' rather than 'in a chat': there is deliberately no `profile` value, because Fanvue does not record which surface a fan tipped from, so a tip sent in a chat thread and a tip sent from a creator profile are indistinguishable and both report `message`. Do not treat `message` as evidence of a chat origin when attributing revenue. Buckets identically to the `context` field on the tip.new webhook.
    - `user` object, nullable, required — Fan's user information (null for transactions without a fan like referrals, affiliates)
      - `uuid` string, uuid, required
      - `handle` string, required
      - `displayName` string, required
      - `nickname` string, nullable, required
      - `isTopSpender` boolean, required
  - `nextCursor` string, nullable, required — Cursor for next page, null if no more data

## Other responses

- `400` — Bad Request - API version not supported OR validation failed (dates, sources, cursor, pagination) 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.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)