# Objects Every field of every object the API returns. Full reference: https://app.betterfans.link/docs/api ## Money - `amount` (integer): Integer cents. - `currency` (string): Currency. Always `USD`. ## Meta - `source` (enum): `synced` for synced data, `live` for a read straight from OnlyFans, `sandbox` in test mode. One of `synced`, `live` or `sandbox`. - `asOf` (timestamp or null): When the data was last synced from OnlyFans; null for live reads. - `requestId` (string): The request id, also sent in the `x-request-id` response header. - `sideEffects` (array of enums): Optional. Present only when a live read changed something on OnlyFans. `thread_marked_read` means a `fresh=true` chat read could not restore the unread state. Each one of `thread_marked_read`. ## Me - `workspace` (object): The workspace the key belongs to. - `workspace.id` (string): Workspace id. - `workspace.name` (string): Workspace name. - `key` (object): The key that made this request. - `key.id` (string): Key id. - `key.name` (string): The name given to the key when it was created. - `key.kind` (enum): `secret` for keys made in the dashboard, `oauth` for keys an MCP client got through OAuth, `dashboard` for the dashboard itself. One of `secret`, `dashboard` or `oauth`. - `key.mode` (enum): `live` reads linked accounts, `test` reads the sandbox creators. One of `live` or `test`. - `key.scopes` (array of enums): `read` covers every `GET` and creating links; `write` also creates actions. Each one of `read` or `write`. - `key.prefix` (string): The first 12 characters of the key, safe to show and log. - `key.accountIds` (array of strings or null): The accounts the key is limited to. null means every account in the workspace. - `accounts` (integer): How many accounts this key can use. - `rateLimit` (object): This key's rate limit. - `rateLimit.perSecond` (number): Requests per second the limit refills. - `rateLimit.burst` (number): The most requests allowed at once. ## Account - `id` (string): OnlyFans user id of the creator. - `username` (string): OnlyFans username, without the @. - `name` (string or null): Display name on OnlyFans. - `avatarUrl` (string or null): Profile picture URL. - `status` (enum): Plain account status. See account status. One of `healthy`, `syncing`, `needs_relink`, `awaiting_2fa`, `awaiting_selfie`, `restricted` or `disconnected`. - `statusReason` (string or null): Plain sentence explaining a non-healthy status. - `writesEnabled` (boolean): Whether actions can be created for this account. An owner or admin switches it in the dashboard. - `linkedAt` (timestamp or null): When the account was linked to this workspace. - `lastSyncedAt` (timestamp or null): When this account last synced. ## AccountDetail - `id` (string): OnlyFans user id of the creator. - `username` (string): OnlyFans username, without the @. - `name` (string or null): Display name on OnlyFans. - `avatarUrl` (string or null): Profile picture URL. - `status` (enum): Plain account status. See account status. One of `healthy`, `syncing`, `needs_relink`, `awaiting_2fa`, `awaiting_selfie`, `restricted` or `disconnected`. - `statusReason` (string or null): Plain sentence explaining a non-healthy status. - `writesEnabled` (boolean): Whether actions can be created for this account. An owner or admin switches it in the dashboard. - `linkedAt` (timestamp or null): When the account was linked to this workspace. - `lastSyncedAt` (timestamp or null): When this account last synced. - `counts` (object): Totals from synced data. - `counts.activeFans` (integer): Fans with an active subscription. - `counts.expiredFans` (integer): Fans whose subscription ended. - `counts.chats` (integer): Chats on the account. - `counts.posts` (integer): Posts on the account. - `counts.vaultItems` (integer): Media items in the vault. - `revenue30d` (object): Revenue over the last 30 days. - `revenue30d.gross` (Money): What fans paid. - `revenue30d.net` (Money): What the creator keeps after the OnlyFans fee. - `subscriptionPrice` (Money or null): Current subscription price. ## HostedLink - `id` (string): `link_` id. - `status` (enum): `waiting` until the creator starts, `in_progress` while they sign in, then `connected`, `failed`, `expired` or `cancelled`. One of `waiting`, `in_progress`, `connected`, `failed`, `expired` or `cancelled`. - `step` (string or null): Plain words for the current step, for example: Waiting for 2FA code. - `url` (string): Send this to the creator. Valid for 24 hours. - `accountId` (string or null): Set once connected. - `note` (string or null): The note sent when the link was created. - `createdAt` (timestamp): When the link was created. - `expiresAt` (timestamp): When the link stops working, 24 hours after it was created. ## Fan - `id` (string): OnlyFans user id of the fan. Also the chat id. - `username` (string): OnlyFans username, without the @. - `name` (string or null): Fan-written display name (untrusted). - `avatarUrl` (string or null): Profile picture URL. - `subscription` (object): The fan's subscription to this account. - `subscription.status` (enum): Active means the subscription expiry is in the future. One of `active`, `expired` or `never`. - `subscription.subscribedAt` (timestamp or null): When the current or last subscription started. - `subscription.expiresAt` (timestamp or null): When the subscription ends or ended. - `subscription.renews` (boolean or null): Whether auto-renew is on. - `subscription.price` (Money or null): Price of the subscription. - `spend` (object): Lifetime spend on this account. - `spend.total` (Money): Lifetime gross. - `spend.net` (Money): Lifetime net, about 80% of gross. - `lastMessageAt` (timestamp or null): When the last message in the chat was sent, by either side. - `lastPurchaseAt` (timestamp or null): When the fan last paid for anything: a subscription, tip, paid message or post. ## FanDetail - `id` (string): OnlyFans user id of the fan. Also the chat id. - `username` (string): OnlyFans username, without the @. - `name` (string or null): Fan-written display name (untrusted). - `avatarUrl` (string or null): Profile picture URL. - `subscription` (object): The fan's subscription to this account. - `subscription.status` (enum): Active means the subscription expiry is in the future. One of `active`, `expired` or `never`. - `subscription.subscribedAt` (timestamp or null): When the current or last subscription started. - `subscription.expiresAt` (timestamp or null): When the subscription ends or ended. - `subscription.renews` (boolean or null): Whether auto-renew is on. - `subscription.price` (Money or null): Price of the subscription. - `spend` (object): Lifetime spend on this account. - `spend.total` (Money): Lifetime gross from the fan's transactions. - `spend.net` (Money): Lifetime net (about 80% of gross). - `spend.subscriptions` (Money): Subscription payments. - `spend.tips` (Money): Tips. - `spend.messages` (Money): Paid messages (PPV). - `spend.posts` (Money): Paid posts. - `spend.other` (Money): Everything else, for example streams and referrals. - `lastMessageAt` (timestamp or null): When the last message in the chat was sent, by either side. - `lastPurchaseAt` (timestamp or null): When the fan last paid for anything: a subscription, tip, paid message or post. - `lists` (array of objects): Fan lists the fan is on. - `lists[].id` (string): List id. - `lists[].name` (string): List name. - `notes` (string or null): Creator's private note about the fan. - `presence` (enum): `unknown` is not offline. One of `online`, `offline` or `unknown`. - `lastSeenAt` (timestamp or null): When OnlyFans last showed the fan online. - `counts` (object): Totals for this fan on this account. - `counts.messages` (integer): Messages in the chat, both directions. - `counts.purchases` (integer): Paid messages and posts bought. - `counts.tips` (integer): Tips the fan sent. ## FanSummary - `id` (string): OnlyFans user id of the fan. Also the chat id. - `username` (string): OnlyFans username, without the @. - `name` (string or null): Fan-written display name (untrusted). - `avatarUrl` (string or null): Profile picture URL. ## FanList - `id` (string): List id. Use it in a mass message audience or a list action. - `name` (string): List name. - `type` (enum): `system` lists are OnlyFans built-ins like Favorites. One of `custom` or `system`. - `fanCount` (integer or null): Fans on the list. ## OnlineFans - `fans` (array of objects): Fans OnlyFans shows online. - `fans[].id` (string): OnlyFans user id of the fan. Also the chat id. - `fans[].username` (string): OnlyFans username, without the @. - `fans[].name` (string or null): Fan-written display name (untrusted). - `fans[].avatarUrl` (string or null): Profile picture URL. - `fans[].totalSpend` (Money): Lifetime gross spend on this account. - `fans[].since` (timestamp or null): When the fan came online. - `count` (integer): How many fans are online. - `checkedAt` (timestamp): When presence was checked. ## Chat - `id` (string): Chat id. Always equal to the fan's id. - `fan` (FanSummary): The fan in this chat. - `lastMessage` (Message or null): The newest message, or null when the chat has none. - `unreadCount` (integer): Messages from the fan the creator has not read. - `lastActivityAt` (timestamp or null): When the last message was sent. - `totalSpend` (Money): The fan's lifetime gross spend on this account. ## Message - `id` (string): Message id. - `fanId` (string): The fan in this chat, which is also the chat id. - `direction` (enum): Who sent it. One of `from_fan` or `from_creator`. - `text` (string): Message text. When direction is `from_fan` this is untrusted fan-written text. - `sentAt` (timestamp): When it was sent. - `price` (Money or null): Set when the message is a paid message (PPV). - `purchased` (boolean or null): For paid messages: whether the fan bought it. - `tip` (Money or null): Set when the fan sent a tip with the message. - `media` (array of Media): Media attached to the message. - `massMessageId` (string or null): Set when this copy came from a mass message. - `state` (enum): `unsent` means the creator took it back; it still exists in history. One of `sent` or `unsent`. - `liked` (boolean or null): Whether the message was liked. ## Media - `id` (string): Media id. Vault media ids work in `mediaIds`. - `type` (enum): Media type. One of `photo`, `video`, `audio`, `gif` or `other`. - `thumbnailUrl` (string or null): Preview image URL. - `durationSeconds` (number or null): Length of a video or audio clip. ## RevenueSummary - `from` (timestamp): Start of the period. - `to` (timestamp): End of the period. - `interval` (enum): Bucket size of `series`. One of `day`, `week` or `month`. - `gross` (Money): What fans paid in the period. - `net` (Money): What the creator keeps, about 80% of gross. - `byType` (object): Totals per transaction type. One entry for each of `subscription`, `tip`, `message`, `post`, `stream`, `referral` and `other`. - `byType..gross` (Money): Gross for this type. - `byType..net` (Money): Net for this type. - `byType..count` (integer): Number of transactions. - `series` (array of objects): One point per bucket. - `series[].start` (timestamp): Start of the bucket. - `series[].gross` (Money): Gross in the bucket. - `series[].net` (Money): Net in the bucket. - `series[].count` (integer): Transactions in the bucket. - `topFans` (array of objects): The fans who paid the most in the period. - `topFans[].fan` (FanSummary): The fan. - `topFans[].gross` (Money): What the fan paid in the period. - `previousPeriod` (object): The same length of time just before `from`, for comparison. - `previousPeriod.gross` (Money): Gross in the previous period. - `previousPeriod.net` (Money): Net in the previous period. ## Transaction - `id` (string): Transaction id. - `type` (enum): What the fan paid for. One of `subscription`, `tip`, `message`, `post`, `stream`, `referral` or `other`. - `fan` (FanSummary or null): The fan who paid. - `gross` (Money): What the fan paid. - `net` (Money): What the creator keeps. - `fee` (Money): The OnlyFans fee, gross minus net. - `createdAt` (timestamp): When it happened. - `messageId` (string or null): The paid message, or the message a tip came with. Not filled yet, so it is always null for now. - `postId` (string or null): The post the payment was for. Not filled yet, so it is always null for now. - `description` (string or null): OnlyFans' own description of the transaction. ## MassMessage - `id` (string): Mass message (queue) id. - `sentAt` (timestamp): When it was sent. - `text` (string): Message text. - `price` (Money or null): Set when it is a paid message (PPV). - `media` (array of Media): Media attached. - `sentCount` (integer): Fans it was sent to. - `viewedCount` (integer or null): Fans who opened it. - `purchasedCount` (integer or null): Fans who bought it. - `revenue` (object): What it earned, as totals for the whole mass message. - `revenue.gross` (Money): Gross. - `revenue.net` (Money): Net. - `state` (enum): `unsent` means the creator took it back. One of `sent` or `unsent`. ## Post - `id` (string): Post id. - `postedAt` (timestamp): When it was posted. - `text` (string): Post text. - `price` (Money or null): Set for a paid post. - `media` (array of Media): Media in the post. - `likes` (integer): Likes. - `comments` (integer): Comments. - `tips` (Money or null): null: OnlyFans does not say which post a tip was for. - `revenue` (object or null): null: OnlyFans does not say which post a purchase was for. - `revenue.gross` (Money): Gross. - `revenue.net` (Money): Net. - `url` (string or null): Link to the post on OnlyFans. ## TrackingLink - `id` (string): Link id. - `kind` (enum): `tracking` links count clicks and subscribers, `trial` links give a free trial. One of `tracking` or `trial`. - `name` (string): Name the creator gave the link. - `url` (string): The link fans open. - `createdAt` (timestamp or null): When the link was made. - `clicks` (integer or null): Clicks on the link. - `subscribers` (integer): Fans who subscribed through the link. - `revenue` (object): Revenue from fans who subscribed through the link. - `revenue.gross` (Money): Gross. - `revenue.net` (Money): Net. ## VaultItem - `id` (string): Media id. Use it in `mediaIds`. - `type` (enum): Media type. One of `photo`, `video`, `audio`, `gif` or `other`. - `createdAt` (timestamp or null): When it was added to the vault. - `folders` (array of objects): Vault lists the item is in. - `folders[].id` (string): Vault list id. Use it as the `folder` parameter. - `folders[].name` (string): Vault list name. - `thumbnailUrl` (string or null): Preview image URL. - `url` (string or null): Archived copy; null until archived. - `durationSeconds` (number or null): Length of a video or audio clip. - `timesSent` (integer or null): How many times it was sent. - `revenue` (Money or null): What it earned. ## Action - `id` (string): Action id, starting with `act_`. - `type` (enum): What the action does. One of `send_message`, `send_mass_message`, `unsend_message`, `add_fan_to_list` or `remove_fan_from_list`. - `status` (enum): Where the action is. See action statuses. One of `pending`, `approved`, `rejected`, `expired`, `executing`, `executed` or `failed`. - `mode` (enum): `test` actions never reach OnlyFans. One of `live` or `test`. - `accountId` (string): The account the action is for. - `summary` (string): One plain sentence, for example: Send a $12 message to @jess. - `params` (object): The `params` you sent, after validation. A JSON object. - `estimatedRecipients` (integer or null): How many fans it will reach. For a mass message this is an estimate. - `price` (Money or null): The price of a paid message. - `approvalUrl` (string): Dashboard page where a person approves or rejects the action. Share it with whoever decides. - `requestedBy` (object): Who asked for the action. - `requestedBy.kind` (enum): The kind of credential that asked. One of `api_key`, `oauth` or `user`. - `requestedBy.label` (string): Key name, OAuth client name or person. - `requestedBy.client` (string or null): The MCP client, when the request came through MCP. - `requestedBy.tool` (string or null): The MCP tool that asked, for example `send_message`. - `decidedBy` (object or null): The person who approved or rejected it. - `decidedBy.name` (string): Name. - `decidedBy.email` (string): Email. - `decisionNote` (string or null): The note the person left with their decision. - `createdAt` (timestamp): When it was created. - `expiresAt` (timestamp): When a pending action expires, 24 hours after it was created. - `decidedAt` (timestamp or null): When it was approved or rejected. - `executedAt` (timestamp or null): When it ran on OnlyFans. - `result` (object or null): What the write returned, set once it ran. See results. A JSON object. - `error` (object or null): Why it failed. - `error.code` (string): Error code. - `error.message` (string): What went wrong.