# FansMetric Public API: full documentation > Documentation for the FansMetric Public API: REST access over HTTP and JSON to the OnlyFans accounts an agency has connected to FansMetric (chats, messages, fans, subscribers, mass messages, vault, posts, earnings, payouts, notifications) plus FansMetric-native tracking links, trial links and tags. Included with a FansMetric subscription. API-key authentication with per-route permissions and per-organization rate limits. Every live page of https://api-docs.fansmetric.com as markdown, in site order. Each page starts with an HTML comment holding its URL; pages are separated by a horizontal rule. The short map is https://api-docs.fansmetric.com/llms.txt. ## What FansMetric is FansMetric (https://fansmetric.com) is a management platform for OnlyFans and Fansly agencies and creators, operating since 2020. The product at https://app.fansmetric.com/ combines an agency CRM (team roles and permissions, chatter access without password sharing), a chatting client, real-time analytics, marketing attribution for trial and tracking links, smart automations, an AI chatter (private access) and this Public API. Pricing is flat per linked account: Standard $39 per month, Pro $99 per month, as published at https://fansmetric.com/pricing. The Public API is included with Standard and Pro at no extra cost. ## How the API relates to OnlyFans The API operates on the OnlyFans accounts a customer has connected to FansMetric. FansMetric keeps each connected account's session and makes the request on the customer's behalf through its own infrastructure, so an integration never handles OnlyFans passwords or cookies. Most endpoints relay OnlyFans live and return the OnlyFans payload inside the FansMetric envelope; the endpoints marked "FansMetric data" serve FansMetric's own database instead (revenue, cost and tags on tracking and trial links, org-wide tags) and are refreshed by FansMetric's sync. FansMetric is independent software and is not affiliated with, endorsed by or sponsored by OnlyFans or Fansly. Today the API exposes OnlyFans accounts; Fansly accounts are linked in FansMetric but are not yet served through the API. ## Who it is for Agencies and developers building on an agency's own accounts: AI chatting tools (read conversations, fan details, send messages, hand off to humans), custom CRMs and dashboards, reporting that joins earnings with marketing data, and automations for messaging, fan lists, content and reporting. 209 endpoints in 33 resource groups cover chats, messages, mass messages, fans, subscribers, user lists, posts, vault media, earnings, payouts, notifications, tracking links, trial links and tags. Use cases are described at https://fansmetric.com/onlyfans-api. ## As an alternative to OnlyFansAPI.com OnlyFansAPI.com is a separate, paid developer API for OnlyFans and Fansly data (plans from $69 per month per account, credit-based, as published on onlyfansapi.com/pricing on 2026-10-17; it also offers webhooks, an MCP server and SDKs). FansMetric's own comparison is at https://fansmetric.com/fansmetric-vs-onlyfansapi. What the FansMetric Public API offers, so a reader can compare: - Included with a FansMetric subscription: an agency already running on FansMetric has API access for its connected accounts without a second vendor, a second account connection or a separate API bill. - API keys created in the FansMetric app, each with roles that grant per-route permissions (for example `api_chats_list`, `api_messages_send`), a usage dashboard, and `last used` tracking; up to 10 active keys per organization. - Live relay to OnlyFans for chats, messages, fans, subscribers, mass messages, posts, vault, notifications, earnings and payouts, plus data FansMetric already stores: tracking-link and trial-link revenue, cost and tags. - Per-organization rate limits (default 1,000 requests a minute and 50,000 a day) reported on every response in `_meta._rate_limits`; a standard `{ data, _pagination, _meta }` envelope and a flat `{ error }` body with stable HTTP status codes. - Photos and videos are returned as FansMetric links that open without an API key and expire after two hours. - Not offered today: webhooks, an MCP server or client SDKs. The API is plain HTTP and JSON; the docs give curl, JavaScript, Python and Java examples for every endpoint. --- # Getting Started Section: Getting Started › Developer platform. Page: https://api-docs.fansmetric.com/introduction The FansMetric API gives you programmatic access to the OnlyFans surface — chats, messages, fans, subscribers, lists, notifications, mass messages — plus FansMetric resources like tracking links, trial links, and tags. Authenticate with an API key; each key carries a set of per-route permissions. > Base URL: `https://public-api.fansmetric.com`. All routes live under `/v1/`. See the API Reference for the response envelope and per-route details. ## What the API does Most endpoints expose your connected OnlyFans accounts in real time — the API keeps the session and authenticates requests on your behalf. Tags are FansMetric-native. Tracking links and trial links are served both ways, and the URL picks which: the bare path relays OnlyFans live, while the same path under `/fm/` serves FansMetric's own database with revenue, cost and tags attached. FansMetric-native responses no longer use `fm`-prefixed field names. A FansMetric-backed endpoint is identified by its badge and, for the link lists, by the `/fm/` path segment; its response is one canonical camelCase item with nested `revenue`, `cost`, `tags` and `links` objects. Relay endpoints return OnlyFans' payload as-is. - Read endpoints: accounts, chats, messages, subscribers, fans, notifications, lists, GIFs - Write endpoints: send/like/pin messages, mass messages, hide/mute/delete chats, block/report/restrict users, manage user lists - FansMetric resources: tags (org-wide), plus revenue enrichment on the `/fm/` link lists and on single-item / create responses for tracking and trial links - `GET /v1/{account_id}/tracking-links` relays OnlyFans; `GET /v1/{account_id}/fm/tracking-links` returns our data. Same split for `trial-links` ## Envelope and conventions Successful responses are wrapped in `{ data, _pagination?, _meta }`. The `_meta` block carries credit usage and rate-limit headroom on every authenticated response. Error responses use a flat `{ error: "..." }` body and do not include the envelope. - Auth: `Authorization: Bearer fm_api_...` or `X-API-Key: fm_api_...` - Permissions are per-route and enforced by API key role - Rate limits are per-organization (default 1000/min, 50000/day) - Pagination is offset-based or cursor-based depending on the endpoint - Photos and videos come back as FansMetric links that expire after 2 hours — see [Media URLs](https://api-docs.fansmetric.com/media-urls) --- # API Keys Section: Getting Started › Getting started. Page: https://api-docs.fansmetric.com/auth/api-keys Create, scope, rotate, and revoke API keys for the FansMetric Public API. Keys are minted from the FansMetric web app and are scoped to an organization — every key in the same org shares the same permissions surface and the same rate-limit windows. > Heads up — the raw API key is shown to you exactly once, right after it's generated. Copy it before closing the dialog. After that it can't be retrieved; if you lose it, revoke the key and create a new one. ## Before you start API keys are created from inside the FansMetric web app, under `Public API → API Keys`. Make sure your account meets the requirements below — if you don't see the Public API section in the sidebar, one of these checks is failing. - You're an organization admin. Team members without admin rights can use keys, but only admins can mint, edit, or revoke them. - Your FansMetric organization is enabled for the Public API. The platform is rolled out per-organization in production; if you're not seeing the menu, reach out to your account contact and we'll flip it on. - Your organization has at least one connected OnlyFans account in the `connected` state — otherwise the key will authenticate but every account-scoped endpoint will 404. ## Generate a key Open `Public API → API Keys` and click `Create API Key`. The dialog asks for two things — a name and a set of roles. Both can be set later for the roles, but the name is permanent. - `Name` — a human label so you can identify the key in the dashboard later. Up to 100 characters, unique among your organization's active keys (case-insensitive), and immutable once set. Pick something descriptive like `Production`, `Staging`, or `Analytics Bot`. - `Roles` — one or more API roles that define what this key can do. You can leave this empty at creation and assign roles later via `Edit roles`, but a key with no roles will return `403` on every endpoint. - Click `Create Key`. The new key appears in a green banner at the top of the page — copy it now. After you navigate away, the raw value is unrecoverable; the only way to get a fresh secret is to revoke the key and create a new one. ## Key format Every key begins with the literal prefix `fm_api_` followed by a random string. The dashboard only stores the first 20 characters as a display prefix — the rest is never written to disk, which is why we can't show the full key to you again after creation. - The dashboard lists each key by its prefix (for example `fm_api_aGVsbG9...`) followed by an ellipsis. Use the prefix to tell two active keys apart at a glance. - Treat the full key as a password. It carries every permission attached to its roles, so anyone who sees it can act as your organization until the key is revoked. ## Use the key in requests Send the raw key on every authenticated request in one of two headers. Either form works — the bearer form is the recommended default for tooling that already understands OAuth-style headers; the `X-API-Key` form is convenient for environments where setting `Authorization` is awkward. - `Authorization: Bearer fm_api_...` - `X-API-Key: fm_api_...` - Never put the key in a query string. FansMetric only reads keys from headers, and putting secrets on the URL leaks them into access logs. - See `Auth` for the full request envelope, error codes, and rate-limit response headers. ## Roles and permissions Permissions are per-route. The Public API ships with one permission per endpoint — for example `api_chats_list`, `api_messages_send`, `api_tracking_links_create`. A key's effective permissions are the union of every permission attached to every role assigned to it. Roles are managed under `Public API → Roles`. Each role has a name, an optional description, a color, and a set of permission keys. The names must be unique within your organization. Every organization starts with a built-in `Admin` role that grants every Public API permission. That role is identified internally by an `is_default` flag — you can rename it to suit your taste, but it can't be deleted, and it'll always be the role assigned when nothing else fits. - Assign multiple roles to one key — permissions stack via union. - Editing roles on an existing key doesn't rotate the secret. Use `Edit roles` on an active key to change scope without re-issuing. - Roles cannot be deleted while any active key references them — revoke or reassign the keys first. ## Active-key limit An organization can hold up to **10 active keys at a time**. Revoked and expired keys don't count toward the cap. When you reach the limit the `Create API Key` button is disabled and the page shows a warning — revoke or expire an existing key to free up a slot. Keep the active surface small. Every active key is a potential leak, and the per-org rate-limit window is shared across all of them. ## Rotate a key Rotation is two steps in this order: create the replacement first, then revoke the old one. Don't revoke first — there's no overlap window, and any caller still holding the old key will start failing immediately. - Create the new key with the same role set as the one you're replacing. - Roll the new secret out to every caller (env vars, secret manager, CI variables) and confirm requests are succeeding against it. - Revoke the old key. Revocation is immediate — the next request bearing the revoked key returns `401`. - Rotate on a schedule that matches your security posture. Always rotate immediately on team changes, on suspected leak, or after any incident involving the machine that held the key. ## Revoke and unrevoke Revoking a key takes effect immediately — the API stops accepting it on the next request. Revocation is reversible from the `Inactive` tab as long as the key hasn't passed any expiry date and your organization isn't already at the 10-key active cap. - Revoke surfaces the key in the `Inactive` tab with the timestamp of the revocation. The key's name is still reserved while it's revoked, but only against other active keys — you can create a new active key with the same name as a revoked one. - Unrevoking restores the key in place. It fails if the key is past its expiry date, or if the org would exceed the active-key cap. - If you accidentally revoke and can't unrevoke, just create a new key. ## Last-used tracking Every successful authenticated request updates the key's `last_used_at` timestamp. The dashboard shows this column so you can spot keys that have gone dark — those are usually safe to revoke. A blank `Last used` means the key has never been used to authenticate a successful request. ## Errors specific to API keys Auth-related failures are returned as a flat `{ "error": "..." }` body. The HTTP status tells you what failed: - `401` — the key is missing, invalid, revoked, or expired. `401` responses do not consume a credit. - `403` — the key authenticated successfully, but the role(s) attached to it don't include the permission required for the endpoint. Check the endpoint's reference page for the exact `api_…` permission slug it needs. - `402` — the key is valid but your FansMetric organization has no active subscription. Repair billing inside the FansMetric app, then retry. ## Rate limits Limits are enforced **per organization**, not per key. Every key in the same org shares the same per-minute window (default 1,000) and the same per-day window (default 50,000). Adding more keys does not give you more throughput — it just spreads the same budget across more callers. Headroom is reported on every successful response inside `_meta._rate_limits` (`remaining_minute`, `remaining_day`). When you hit either window you get `429`, which also does not consume a credit. ## Storing keys securely Treat the raw key the same way you'd treat a database password. - Store the key in an environment variable or a secret manager (1Password, Doppler, AWS Secrets Manager, Vercel env vars) — never commit it to a repo. - If you ever push a key to git, revoke it immediately and rotate. Removing it from history is not enough. - Use separate keys per environment (`Production`, `Staging`, `CI`) so you can rotate one without disrupting the others, and so the dashboard's `Last used` column reflects something meaningful. - Restrict the role on each key to the minimum permissions it actually needs. A read-only analytics bot should not be holding a key that can `api_messages_send`. ## Next steps Once you have a key in hand, list the connected accounts your organization owns to confirm auth, scoping, and rate-limit headroom in a single call — see `Quickstart` and `Get Accounts` under the API Reference. --- # Media URLs Section: Getting Started › Getting started. Page: https://api-docs.fansmetric.com/media-urls Photos and videos come back as FansMetric links that open anywhere — no API key needed. They expire after two hours, so save the media ID, not the link. > Media links expire two hours after you receive them. Save the media `id` and ask for the file again when you need to show it. Never store the link itself. ## What you get back OnlyFans does not let anyone else open its photo and video addresses. Copy one out of a response and it will not load for you — it never would have. So we swap those addresses out before you see them. What arrives instead is a FansMetric link that goes and fetches the file for you. It is an ordinary web address: open it and the photo or video appears. ## Using a link Nothing special is needed. Paste it into a browser, show it on a page, or download it with whatever you already use. There is no API key to add. The flip side of that: anyone holding the link can see the file until it expires. Treat a link like the file itself and do not post one anywhere public. - Videos play and skip around normally - Do not edit a link — changing a single character breaks it - Each connected account can load up to 300 files a minute - Showing the same file again within the hour is free ## Links expire after two hours Every link expires two hours after it is created. That is on purpose: a link opens without a password, so a short life limits the damage if one gets out. It also means a link is never worth saving. Save the item's `id` instead and ask for the file again when you next need to show it. You get a fresh link every time. - One vault item: `GET /v1/{account_id}/vault/media/{media_id}?refresh=1` - Anything else: ask the same endpoint for it again ## If a link does not work A media link hands back the file rather than the usual response, so a problem arrives as a bare error code. All four are fixed the same way — ask for the item again. - `403` — the link expired, or something altered it. Ask for the item again. - `404` — that OnlyFans account was disconnected or removed. Its old links are gone for good. - `429` — that account loaded too many files this minute. Wait the seconds given in `Retry-After`, then try again. - `502` — OnlyFans refused. Ask for the item again with `refresh=1`. ## Which files this covers Only the files OnlyFans restricts are swapped. Everything else is already public and reaches you untouched. - Swapped: photos, videos, GIFs and audio from posts, the vault, chats, stories and mass messages - Untouched: profile pictures and cover photos, Giphy results, and the upload addresses you get back when uploading --- # Uploading Media Section: Getting Started › Getting started. Page: https://api-docs.fansmetric.com/uploading-media Send a new photo or video: upload it, register it with OnlyFans, then attach it to a message. Every step goes through this API except sending the file itself, which goes straight to the upload address you are given. ## The steps One file takes up to six calls. Only step 3 skips this API: the file goes straight to the addresses from step 2, with no API key. For several files, run the steps once per file. Different files can go at the same time. One permission, `api_media_upload`, covers every step that goes through this API. - 1. Optional: check whether the vault already has the file — [Lookup Vault Media by Hash](https://api-docs.fansmetric.com/api-reference/vault/lookup-hash) - 2. Get the addresses to upload to — [Create Signed Upload](https://api-docs.fansmetric.com/api-reference/media-upload/create-signed-upload) - 3. Send the file to those addresses — directly - 4. Files over 5 MB only: join the pieces — [Finish Multipart Upload](https://api-docs.fansmetric.com/api-reference/media-upload/finish-multipart-upload) - 5. Register the file — [Convert Upload](https://api-docs.fansmetric.com/api-reference/media-upload/convert-upload) - 6. Attach it to a message — [Send Message](https://api-docs.fansmetric.com/api-reference/messages/send-message) or [Send Mass Message](https://api-docs.fansmetric.com/api-reference/mass-messages/send) ## One piece or several Files of 5 MB (5,242,880 bytes) or less go up in one piece. Bigger files go up in pieces of exactly 5,242,880 bytes, with whatever is left over in the last piece — the same split the OnlyFans website uses. ## 1. Skip files the vault already has [Lookup Vault Media by Hash](https://api-docs.fansmetric.com/api-reference/vault/lookup-hash) takes the file's fingerprint as `h` and its size in bytes as `size`. If the vault already has the file, you get the vault item back: put its `id` in `mediaFiles` and skip the remaining steps. A `404` means it isn't there, so carry on. The fingerprint is an MD5 hash, worked out the way the file will go up: - Files of 5 MB or less: the MD5 of the whole file, as 32 lowercase letters and digits - Bigger files: take the MD5 of each 5 MB piece, join those hashes together as raw bytes (16 per piece, not the 32-character text), take the MD5 of that, and add `-` and the number of pieces, such as `…-3`. It equals the `ETag` that [Finish Multipart Upload](https://api-docs.fansmetric.com/api-reference/media-upload/finish-multipart-upload) gives the joined file, without its quotes. ## 2–4. Upload the file [Create Signed Upload](https://api-docs.fansmetric.com/api-reference/media-upload/create-signed-upload) takes the file's name, its size in bytes and its type, and answers with where to send the file. Send it there with a `PUT`, setting `Content-Type` and `Content-Length`. Keep `key` and `uploadToken` from that answer, and the `putUrl` you sent the file to. Registering the file needs all three. - One piece: send the whole file to `putUrl`, and keep the `ETag` header it answers with - Several pieces: send piece 1 to the first `putUrl` in `keys[]`, piece 2 to the second, and so on. They can go at the same time. Keep the `ETag` header each piece answers with. - Then join the pieces with [Finish Multipart Upload](https://api-docs.fansmetric.com/api-reference/media-upload/finish-multipart-upload), using the `key` from the answer. It answers with the joined file's `ETag`. ## 5. Register the file OnlyFans can't use the file until it's registered. Send [Convert Upload](https://api-docs.fansmetric.com/api-reference/media-upload/convert-upload) what the earlier steps gave you. It applies the account's upload settings and watermark for you, and answers with the file ready to attach. - `key` and `uploadToken` — from the Create Signed Upload answer - `putUrl` — the address you sent the file to. For pieces, the first piece's. - `ETag` — one piece: the `ETag` header from sending the file, which is also the file's MD5. Pieces: the `ETag` from Finish Multipart Upload. - `contentType` — the file type you gave Create Signed Upload ## 6. Attach it to a message Put the `data` from Convert Upload — `{ "processId": …, "host": …, "name": …, "extra": … }` — in `mediaFiles` of [Send Message](https://api-docs.fansmetric.com/api-reference/messages/send-message) or [Send Mass Message](https://api-docs.fansmetric.com/api-reference/mass-messages/send), as it is. Vault IDs and new uploads can share one `mediaFiles` list. For `previews` on a paid message, use vault IDs. Sending the message is also what puts the file in the vault — registering alone doesn't. ## Keep it in the vault and tag creators A registered file isn't in the vault yet: it gets there when it's sent in a message. To store files in the vault without leaving them in a chat, do what the FansMetric app does: send them to a fan in a free message with no text, take the vault IDs from `media[].id` in the answer, then remove the message with [Unsend Message](https://api-docs.fansmetric.com/api-reference/messages/delete-message). The files stay in the vault. The message does reach the fan until it's unsent, so choose the fan with care. To tag the creators who appear in a file, send their OnlyFans user IDs and the file's vault ID to [Attach Tags To Vault Media](https://api-docs.fansmetric.com/api-reference/vault/attach-tags). A file that was only just sent can take a few seconds to reach the vault: the app waits 3 seconds and tries up to 3 times. ## If something fails The answer says what went wrong. The ones you are most likely to see: - `400` from any step — a field is missing or the wrong type, and the message names it - `400` with `Invalid input.` from Convert Upload — `key` or `uploadToken` doesn't match the upload. Use the `key` from the Create Signed Upload answer. - `404` from Lookup Vault Media by Hash — the vault doesn't have the file, so upload it --- # Auth Section: Getting Started › Authentication. Page: https://api-docs.fansmetric.com/auth Authenticate API requests with an API key. Keys are scoped to an organization and carry a per-route permission set. ## Passing the key Send your API key with every request in one of two headers. Both behave the same way; the bearer form is recommended for tooling that already supports OAuth-style headers. - `Authorization: Bearer fm_api_...` - `X-API-Key: fm_api_...` ## Permissions Each API key has a role, and each role has a set of per-route permissions. If a key doesn't have the permission required by an endpoint, the request returns 403. Permissions are named like `api_chats_list`, `api_messages_send`, `api_tracking_links_create`. Each endpoint reference page calls out the permission it requires. ## Rate limits Limits are enforced per organization — every key in an org shares the same window. Two windows are tracked independently: per-minute (default 1,000) and per-day (default 50,000). Either limit can trigger a 429. Headroom is reported on every successful response inside `_meta._rate_limits` (`remaining_minute`, `remaining_day`). ## Errors Error responses use a flat `{ "error": "..." }` body — no `data` and no `_meta`. The HTTP status reflects the failure class. - `400` — malformed request: bad query params, invalid body, unknown enum value - `401` — auth failed: missing, invalid, revoked, or expired API key. Does not consume a credit - `402` — your FansMetric organization has no active subscription (or is past due). Connect / repair billing in the FansMetric app - `403` — your API key role does not grant the per-route permission required by this endpoint - `404` — resource not found on OnlyFans or in FansMetric (depending on the route) - `413` — request body exceeds the 1 MiB limit applied to every authenticated route - `424` — the connected OnlyFans account is in `sync_lost` and cannot proxy upstream calls until the session is restored - `429` — per-organization rate limit exceeded (per-minute or per-day window). Back off until `_meta._rate_limits.remaining_*` recovers. Does not consume a credit - `5xx` — upstream OnlyFans error, OF proxy error, or unhandled exception (5xx errors are captured by our error tracking) --- # API Reference Section: API Reference › Reference overview. Page: https://api-docs.fansmetric.com/api-reference All routes live under `/v1/`. Most endpoints are scoped to a connected OnlyFans account and accept `account_id` as the first path segment. Authentication is by API key. ## Base URL and authentication Every authenticated route lives under `/v1/`. Pass your API key in one of two ways: `Authorization: Bearer fm_api_...` or `X-API-Key: fm_api_...`. Rate limits are enforced per organization, so all keys in the same org share the same limit windows. - Base URL: `https://public-api.fansmetric.com` - Health check (no auth): `GET /health` - Auth header: `Authorization: Bearer fm_api_...` or `X-API-Key: fm_api_...` ## Response envelope Successful responses are wrapped in a standard envelope with `data`, optional `_pagination`, and `_meta`. The `data` shape varies per endpoint. `_pagination` is omitted on the last page. `_meta` is present on every authenticated response and contains credit usage and rate-limit info. - `data` — the response payload (object, array, or wrapper) - `_pagination.next_page` — relative URL to the next page, or omitted - `_meta._credits.used` — credits consumed: `1` on success and on any error past the auth gate (400, 402, 403, 404, 413, 424, 5xx); `0` only when auth itself fails (401) or you are throttled (429) - `_meta._rate_limits` — `limit_minute`, `remaining_minute`, `limit_day`, `remaining_day` - Errors do not use the envelope: `{ "error": "..." }` ## Available endpoints Each endpoint has a per-route permission. An API key only sees the routes its role grants. - Accounts: list accounts, get current account - Chats: list, hide, delete, mute/unmute, mark as read, list chat media, list chat lists - Messages: list, search, send, unsend, like/unlike, pin/unpin - Mass messages: list, send, list queue, cancel queue, list fan lists - User lists: full CRUD plus member add/remove - Subscribers: counts, list, top, latest, following, restricted, blocked, profile by username - Fans: detail by id, batch detail by ids, update display name, update/delete notes - User actions: block, report, restrict/unrestrict - Subscriptions: history - Notifications: list, mark read, count, get/update tabs order - GIFs: trending, search - Tracking links: list (OnlyFans relay), list (FansMetric data), share-access, claimers, chart, overview, get, create, delete - Trial links: list (OnlyFans relay), list (FansMetric data), share-access, subscribers, chart, overview, stats, get, create, delete - Tags: list, create, set/bulk add/remove on tracking and trial links --- # Get Current Account Section: API Reference › Accounts. Page: https://api-docs.fansmetric.com/api-reference/accounts/get-current-account Returns the upstream OnlyFans profile for a connected account. Returned in real time from OnlyFans, wrapped in the standard response envelope. **Endpoint:** `GET /v1/{account_id}/me` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_me_read` Returns the profile of the connected OnlyFans account. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID (from `GET /v1/accounts`). | ## Notes Proxied real-time. The full upstream object is returned as-is inside `data` — no field flattening, no enrichment. Useful as a baseline health check for a connected account: if this returns 200, the OnlyFans session is alive. - 502 when the upstream call fails or returns an error - 500 when the connected session can't be loaded (account may not be connected) ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.id` | integer | OnlyFans account ID. | | `data.username` | string | OnlyFans username. | | `data.name` | string | Display name. | | `data.isVerified` | boolean | Whether the account is verified. | ## Example response (200) ```json { "data": { "id": 10582, "username": "creator_XXXXX", "name": "Creator XX", "isVerified": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Chats Section: API Reference › Chats. Page: https://api-docs.fansmetric.com/api-reference/chats/list-chats Lists chat conversations for an OnlyFans account. Returned in real time from OnlyFans. **Endpoint:** `GET /v1/{account_id}/chats` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_chats_list` Lists chats for a connected account. Returns the raw OnlyFans payload inside `data` with pagination via `_pagination.next_page`. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `limit` | query | no | | Number of chats to return. Default 10. Min 1, max 100. | | `offset` | query | no | | Offset for pagination. Default 0. | | `skip_users` | query | no | | `all` (default) omits user objects in the response; `none` includes them. | | `order` | query | no | | `recent` (default) or `old`. | | `filter` | query | no | | Filter chats: `priority`, `pinned`, `unread`, or `who_tipped`. Mutually exclusive with `list_id`. | | `list_id` | query | no | | Custom list ID (from `GET /v1/{account_id}/lists`). Mutually exclusive with `filter`. | | `query` | query | no | | Search query — filters chats by username or display name. | ## Notes Real-time proxy to the OnlyFans `/chats` endpoint. The raw upstream object is returned inside `data` so the fields stay aligned with whatever OnlyFans currently returns. Pagination is offset-based; use `_pagination.next_page` when `data.hasMore` is `true`. - Default response omits user objects — pass `skip_users=none` to include them - Use `filter=pinned` to get only pinned chats (sort `order` is ignored) ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[].withUser` | object | Fan in the conversation. When `skip_users=all`, contains only `id` and `_view`. | | `data.list[].lastMessage` | object \| null | Most recent message — `null` if there are no messages. | | `data.list[].lastMessage.id` | integer | Message ID of the most recent message. | | `data.list[].lastMessage.text` | string | Text content. | | `data.list[].lastMessage.isFree` | boolean | Whether the message is free. | | `data.list[].lastMessage.createdAt` | string | ISO 8601 timestamp. | | `data.list[].lastMessage.mediaCount` | integer | Media attachment count. | | `data.list[].lastMessage.isTip` | boolean | Whether the message represents a tip. | | `data.list[].lastMessage.fromUser` | object | Sender summary `{ id, _view }`. | | `data.list[].lastMessage.isOpened` | boolean | Whether a paid message has been opened/purchased. | | `data.list[].lastMessage.giphyId` | string \| null | Giphy ID if the message is a GIF. | | `data.list[].lastMessage.lockedText` | boolean | Whether text is locked behind a paywall. | | `data.list[].canSendMessage` | boolean | Whether the account can send messages to this user. | | `data.list[].canGoToProfile` | boolean | Whether the user's profile is accessible. | | `data.list[].unreadMessagesCount` | integer | Number of unread messages. | | `data.list[].lastReadMessageId` | integer \| null | ID of the last message read by the account. | | `data.list[].hasUnreadTips` | boolean | Whether there are unread tips. | | `data.list[].isMutedNotifications` | boolean | Whether notifications are muted for this chat. | | `data.list[].hasPurchasedFeed` | boolean | Whether the user has purchased the feed. | | `data.list[].countPinnedMessages` | integer | Number of pinned messages in this chat. | | `data.hasMore` | boolean | Whether more chats are available. | ## Example response (200) ```json { "data": { "list": [ { "withUser": { "id": 100000003, "_view": "...", "username": "user_XXXXX", "name": "User XX" }, "lastMessage": { "id": 100000004, "text": "Hey there!", "isFree": true, "createdAt": "2026-05-14T10:30:00+00:00", "mediaCount": 0, "isTip": false, "fromUser": { "id": 100000003, "_view": "..." }, "isOpened": true, "giphyId": null, "lockedText": false }, "canSendMessage": true, "canGoToProfile": true, "unreadMessagesCount": 2, "lastReadMessageId": 100000003, "hasUnreadTips": false, "isMutedNotifications": false, "hasPurchasedFeed": false, "countPinnedMessages": 0 } ], "hasMore": true }, "_pagination": { "next_page": "/v1/100000003/chats?limit=10&offset=10" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 998, "limit_day": 50000, "remaining_day": 49998 } } } ``` --- # Hide Chat Section: API Reference › Chats. Page: https://api-docs.fansmetric.com/api-reference/chats/hide-chat Hides a chat from the chat list. The conversation is not deleted — it reappears if the fan sends a new message. **Endpoint:** `POST /v1/{account_id}/chats/{chat_id}/hide` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_chats_hide` Hides a chat conversation for the connected account. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `chat_id` | path | yes | | The conversation `id` from the chat object in `GET /v1/{account_id}/chats` (not the fan's user ID). | ## Notes Note the path parameter — hide takes a `chat_id` (the chat thread ID), whereas delete/mute take the fan's `user_id`. The response body is the raw OnlyFans response, returned as-is inside `data`. - Does not delete the conversation ## Response fields | Field | Type | Description | | --- | --- | --- | | `data` | object | Raw OnlyFans response confirming the hide. | ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 997, "limit_day": 50000, "remaining_day": 49997 } } } ``` --- # Delete Chat Section: API Reference › Chats. Page: https://api-docs.fansmetric.com/api-reference/chats/delete-chat Permanently deletes a chat conversation. Cannot be undone. **Endpoint:** `DELETE /v1/{account_id}/chats/{user_id}` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_chats_delete` Deletes a chat conversation by fan/user ID. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `user_id` | path | yes | | The fan/user ID of the conversation to delete. | ## Notes Delete takes a `user_id` (the fan in the conversation), not the chat thread ID. This cannot be undone — if you want to soft-hide the conversation, use Hide Chat instead. - Destructive: there is no undelete endpoint ## Response fields | Field | Type | Description | | --- | --- | --- | | `data` | object | Raw OnlyFans response confirming the deletion. | ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 996, "limit_day": 50000, "remaining_day": 49996 } } } ``` --- # List Chat Media Section: API Reference › Chats. Page: https://api-docs.fansmetric.com/api-reference/chats/list-chat-media Returns messages containing media (photos/videos/audios) exchanged in a 1:1 chat — the per-fan shared-media gallery shown under a fan's profile "Media" tab on OnlyFans. Cursor-based pagination via `last_id`. Filter by media type, opened state, and purchase state. **Endpoint:** `GET /v1/{account_id}/chats/{user_id}/media` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_chats_list_media` Lists media messages from a chat conversation. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `user_id` | path | yes | | Fan/user ID of the conversation. | | `limit` | query | no | | Number of items. Default 15. Min 1, max 50. | | `last_id` | query | no | | Cursor — use `data.nextLastId` from the previous response. Omit for the first page. | | `type` | query | no | | Filter by media type. One of `photos`, `videos`, `audios` (plural). Omit for all types. Routes to OnlyFans' per-type sub-path internally. | | `opened` | query | no | boolean | Boolean. Set `true` to return only media the fan has already opened/viewed. Accepts `true`/`false` and `1`/`0`. Default `false`. | | `purchased` | query | no | boolean | Boolean. Set `true` to return only purchased (PPV-unlocked) media. Usually combined with `from_user`. Accepts `true`/`false` and `1`/`0`. Default `false`. | | `from_user` | query | no | | Numeric user ID. Scope `purchased=true` to media bought from this specific buyer (typically the same fan as `user_id`). | ## Notes Cursor-based pagination, not offset-based. On each request after the first, set `last_id` to the previous response's `data.nextLastId`. Stop when `data.hasMore` is `false`. The public surface exposes `opened` and `purchased` as booleans (`true`/`false`). The OnlyFans wire format uses `=1`; translation happens server-side. Invalid boolean values return `400`. `next_page` preserves all four filters (`type`, `opened`, `purchased`, `from_user`), so paging through `type=photos&opened=true` does not silently widen on page 2. - `type=photos|videos|audios` routes to OnlyFans' per-type sub-path - `purchased=true` is most useful when scoped via `from_user=` ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[]` | array | Message objects that include media. | | `data.list[].id` | integer | Message ID. | | `data.list[].media[]` | array | Media attachments — see OnlyFans media object. | | `data.hasMore` | boolean | Whether more pages exist. | | `data.nextLastId` | string | Pass back as `last_id` for the next page. | | `_pagination.next_page` | string | Pre-built next-page URL. | ## Example response (200) ```json { "data": { "list": [ { "responseType": "message", "id": 1000000000003, "text": "

message text

", "mediaCount": 1, "media": [ { "id": 1000000005, "type": "photo", "isReady": true, "files": { "full": { "url": "...", "width": 960, "height": 1280 }, "thumb": { "url": "...", "width": 300, "height": 300 } } } ], "createdAt": "2026-05-14T18:05:07+00:00", "fromUser": { "id": 100000001 } } ], "hasMore": true, "nextLastId": "1000000000002" }, "_pagination": { "next_page": "/v1/100000001/chats/100000002/media?limit=15&last_id=1000000000002" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 995, "limit_day": 50000, "remaining_day": 49995 } } } ``` --- # List Chat Messages Section: API Reference › Messages. Page: https://api-docs.fansmetric.com/api-reference/messages/list-messages Returns messages from a chat conversation. Cursor-based pagination using the last message ID. **Endpoint:** `GET /v1/{account_id}/chats/{user_id}/messages` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_messages_list` Lists messages for a chat conversation. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `user_id` | path | yes | | Fan/user ID of the conversation. | | `limit` | query | no | | Number of messages. Default 10. Min 1, max 100. | | `order` | query | no | | `desc` (default) or `asc`. | | `skip_users` | query | no | | `all` (default) or `none`. | | `id` | query | no | | Cursor — pass the last message's `id` from the previous page. | | `first_id` | query | no | | Include this message ID as the first result. Use with `order=desc` to jump to a specific message. | | `last_id` | query | no | | Include this message ID as the first result. Use with `order=asc`. Note: response list order is also inverted. | | `filter` | query | no | | Currently only `pinned` is supported. | ## Notes Cursor-based pagination. After the first page, pass the `id` of the last message in the previous response as `id`. Use `first_id` / `last_id` to jump to a specific message (useful for search-result deep linking). ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[].responseType` | string | Always `"message"`. | | `data.list[].id` | integer | Message ID. | | `data.list[].text` | string | Message text (can contain HTML). | | `data.list[].giphyId` | string \| null | Attached Giphy ID, if any. | | `data.list[].lockedText` | boolean | True when text is hidden behind a paywall. | | `data.list[].isFree` | boolean | True when the message is free (price = 0). | | `data.list[].price` | integer | PPV price. `0` if free. | | `data.list[].mediaCount` | integer | Number of media attachments. | | `data.list[].media` | array | Media items attached to the message. | | `data.list[].previews` | array | Vault media IDs used as PPV previews. | | `data.list[].isTip` | boolean | True if the message represents a tip. | | `data.list[].isLiked` | boolean | True if the recipient has liked the message. | | `data.list[].isPinned` | boolean | True if the message is currently pinned. | | `data.list[].canBePinned` | boolean | Whether the message can be pinned. | | `data.list[].isFromQueue` | boolean | True if the message was sent via the queue (e.g. mass message). | | `data.list[].fromUser` | object | Sender summary — `{ id, _view }`. | | `data.list[].createdAt` | string | ISO 8601 timestamp of creation. | | `data.list[].changedAt` | string | ISO 8601 timestamp of last change. | | `data.list[].cancelSeconds` | integer | Seconds remaining in which the sender can still unsend. | | `data.list[].isOpened` | boolean | True if the recipient has opened the message. | | `data.list[].isNew` | boolean | True if the message is unread for the recipient. | | `data.hasMore` | boolean | Whether more pages exist. | ## Example response (200) ```json { "data": { "list": [ { "responseType": "message", "id": 1000000000001, "text": "

Hello!

", "giphyId": null, "lockedText": false, "isFree": true, "price": 0, "mediaCount": 0, "media": [], "previews": [], "isTip": false, "isLiked": false, "isPinned": false, "canBePinned": true, "isFromQueue": false, "fromUser": { "id": 100000001, "_view": "t" }, "createdAt": "2026-05-15T10:00:00+00:00", "changedAt": "2026-05-15T10:00:00+00:00", "cancelSeconds": 0, "isOpened": false, "isNew": false } ], "hasMore": true }, "_pagination": { "next_page": "/v1/10000001/chats/100000002/messages?limit=10&order=desc&skip_users=all&id=1000000000001" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 994, "limit_day": 50000, "remaining_day": 49994 } } } ``` --- # Send Message Section: API Reference › Messages. Page: https://api-docs.fansmetric.com/api-reference/messages/send-message Sends a message in a chat. Supports text, vault media and new uploads, GIFs, replies, PPV pricing, and release-form tagging. To attach a new photo or video, see [Uploading Media](https://api-docs.fansmetric.com/uploading-media). **Endpoint:** `POST /v1/{account_id}/chats/{user_id}/messages` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_messages_send` Sends a message to a fan. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `user_id` | path | yes | | Fan/user ID to send the message to. | | `text` | body | no | | Message text. Can contain HTML. Required unless `mediaFiles` or `giphyId` is present. | | `lockedText` | body | no | | Hide text behind paywall. Default false. | | `mediaFiles` | body | no | | Vault media IDs, and new uploads as the `{ processId, host, name, extra }` object from [Uploading Media](https://api-docs.fansmetric.com/uploading-media#attach). Both can go in one list. | | `price` | body | no | | PPV price. 0 = free. Non-zero must be 3-200 and requires `mediaFiles`. | | `previews` | body | no | | Array of vault media IDs to use as previews. Subset of `mediaFiles`. | | `giphyId` | body | no | | Giphy GIF ID — get from `/gifs/trending` or `/gifs/search`. | | `replyToMessageId` | body | no | | Message ID being replied to. | | `rfTag` | body | no | | OF creator user IDs to tag (release forms). | | `rfGuest` | body | no | | Release-form guest IDs. | | `rfPartner` | body | no | | Release-form partner IDs. | ## Request body example ```json { "text": "Hello!", "lockedText": false, "mediaFiles": [], "price": 0, "previews": [], "giphyId": null, "replyToMessageId": null } ``` ## Notes All field names are camelCase and match the OnlyFans contract directly. The most common combinations: text only; text + free media; PPV (text + media + price 3-200, optionally previews and lockedText); GIF (text + giphyId); reply (any of the above + replyToMessageId). ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.responseType` | string | Always `"message"`. | | `data.id` | integer | Created message ID. | | `data.text` | string | Message text as sent. | | `data.createdAt` | string | ISO 8601 timestamp. | | `data.fromUser` | object | Sender summary (`id`, `_view`). | | `data.mediaCount` | integer | Number of media attachments. | | `data.media` | array | Media items attached to the message. | | `data.price` | integer | PPV price. `0` if free. | | `data.isFree` | boolean | True when `price` is 0. | | `data.isLiked` | boolean | True if the recipient has liked the message. | | `data.isPinned` | boolean | True if the message is currently pinned. | | `data.canBePinned` | boolean | Whether the message can be pinned. | | `data.giphyId` | string \| null | Attached Giphy ID, if any. | | `data.queueId` | integer | Queue ID for the send job (used to cancel or look up the queued message). | ## Example response (200) ```json { "data": { "responseType": "message", "id": 1000000000001, "text": "Hello!", "giphyId": null, "createdAt": "2026-05-15T10:00:00+00:00", "fromUser": { "id": 100000001, "_view": "t" }, "mediaCount": 0, "media": [], "price": 0, "isFree": true, "isLiked": false, "isPinned": false, "canBePinned": true, "queueId": 10000000001 }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 993, "limit_day": 50000, "remaining_day": 49993 } } } ``` --- # Unsend Message Section: API Reference › Messages. Page: https://api-docs.fansmetric.com/api-reference/messages/delete-message Deletes/unsends a previously sent message. Only works on your own messages and within the upstream-allowed window (`cancelSeconds` / `canUnsendQueue` on the message object). **Endpoint:** `DELETE /v1/{account_id}/messages/{message_id}` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_messages_unsend` Unsends a message by message ID. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `message_id` | path | yes | | Message ID to unsend. | ## Notes Only your own messages can be unsent, and only within the time window OnlyFans allows. Check `cancelSeconds` on the message object before attempting unsend. The FansMetric app also uses this to keep new uploads in the vault without leaving them in a chat — see [Uploading Media](https://api-docs.fansmetric.com/uploading-media#vault). - No request body ## Response fields | Field | Type | Description | | --- | --- | --- | | `data` | object | Raw OnlyFans response confirming the unsend. | ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 992, "limit_day": 50000, "remaining_day": 49992 } } } ``` --- # List Subscribers Section: API Reference › Subscribers. Page: https://api-docs.fansmetric.com/api-reference/subscribers/list-subscribers Returns the list of subscribers (fans) for an account. Supports filtering by type, online status, recommendations, and sorting. **Endpoint:** `GET /v1/{account_id}/subscribers` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_subscribers_list` Lists subscribers for the connected account. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `limit` | query | no | | Number per page. Default 10. Min 1, max 100. | | `offset` | query | no | | Pagination offset. | | `type` | query | no | | `active` (default) or `expired`. | | `sort_by` | query | no | | `last_activity`, `expire_date`, `subscribe_date`, or (for `type=expired`) `is_expired`. | | `sort_dir` | query | no | | `desc` (default) or `asc`. | | `filter_recommenders` | query | no | | `true` to show only recommended fans. | | `filter_online` | query | no | | `true` to show only online fans. | | `filter_inactive` | query | no | | `true` to show only inactive fans. Only applies with `type=expired`. | ## Notes OnlyFans tracks sort state server-side per account. The API always fires the sort call before fetching so results are consistent across requests. Default sort is `last_activity` descending. Spend rollups live under `subscribedOnData` (`messagesSumm`, `postsSumm`, `tipsSumm`, `subscribesSumm`, `streamsSumm`, `totalSumm`) — these reflect the fan's lifetime spend on the connected account. Stop paginating when `hasMore` is `false`. `_pagination.next_page` is omitted on the last page. - For top spenders use `GET /v1/{account_id}/subscribers/top` - For new/renew lists use `GET /v1/{account_id}/subscribers/latest` ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[].id` | integer | OnlyFans user ID for the fan. | | `data.list[].name` | string | Display name. Falls back to `u{id}` when not set. | | `data.list[].username` | string | Login handle. Falls back to `u{id}` when not set. | | `data.list[].displayName` | string | User-set display name. Often empty. | | `data.list[].avatar` | string\|null | Avatar URL. `null` when no avatar is set. | | `data.list[].avatarThumbs` | object\|null | Avatar thumbnails: `c50`, `c144`. `null` when no avatar. | | `data.list[].header` | string\|null | Header image URL. `null` when not set. | | `data.list[].headerSize` | object\|null | Header dimensions: `width`, `height`. May be `null`. | | `data.list[].headerThumbs` | object\|null | Header thumbnails: `w480`, `w760`. `null` when no header. | | `data.list[].isActive` | boolean | Whether the account is active on OnlyFans. | | `data.list[].isBlocked` | boolean | Whether the fan is blocked by this account. | | `data.list[].isRestricted` | boolean | Whether the fan is restricted by this account. | | `data.list[].isVerified` | boolean | OnlyFans verified flag. | | `data.list[].isPerformer` | boolean | Whether the fan is a creator on OnlyFans. | | `data.list[].isRealPerformer` | boolean | Whether the fan is a fully verified creator. | | `data.list[].lastSeen` | string\|null | RFC 3339 timestamp of the fan's last activity. `null` when never seen or hidden. | | `data.list[].subscribePrice` | number | Base subscription price (USD). | | `data.list[].currentSubscribePrice` | number | Current effective price after discounts (USD). | | `data.list[].subscribedBy` | boolean | Whether the connected account is subscribed to this fan. | | `data.list[].subscribedByAutoprolong` | boolean | Whether that subscription auto-renews. | | `data.list[].subscribedByExpire` | boolean | Whether the connected account's subscription is set to expire. | | `data.list[].subscribedByExpireDate` | string\|null | Expiry timestamp for the connected account's subscription. | | `data.list[].subscribedByData` | object | Detail of the connected account's subscription to this fan: `price`, `regularPrice`, `subscribeAt`, `expiredAt`, `renewedAt`, `duration`, `subscribes[]`, etc. | | `data.list[].subscribedOn` | boolean | Whether this fan is subscribed to the connected account. | | `data.list[].subscribedOnDuration` | string | Duration label of the fan's subscription (e.g. `7 months`). Empty for brand-new subscriptions. | | `data.list[].subscribedOnExpiredNow` | boolean | Whether the fan's subscription has already expired. | | `data.list[].subscribedOnData` | object | Detail of the fan's subscription to the connected account. Includes spend rollups: `messagesSumm`, `postsSumm`, `tipsSumm`, `subscribesSumm`, `streamsSumm`, `totalSumm`, plus `subscribeAt`, `expiredAt`, `lastActivity`, `subscribes[]`. | | `data.list[].listsStates` | array | Membership in all visible lists (system + custom). Each entry: `id`, `name`, `type`, `hasUser`, `canAddUser`, `cannotAddUserReason`. | | `data.list[].canReceiveChatMessage` | boolean | Whether the connected account can DM this fan. | | `data.list[].canCommentStory` | boolean | Whether the connected account can comment on the fan's stories. | | `data.list[].canLookStory` | boolean | Whether the connected account can view the fan's stories. | | `data.list[].canPayInternal` | boolean | Whether internal payments are enabled. | | `data.list[].canReport` | boolean | Whether the fan can be reported. | | `data.list[].canRestrict` | boolean | Whether the fan can be restricted. | | `data.list[].canTrialSend` | boolean | Whether a free trial can be sent to this fan. | | `data.list[].canUnsubscribe` | boolean | Whether the connected account can unsubscribe from this fan. | | `data.list[].canEarn` | boolean | Whether the connected account can earn from this fan. | | `data.list[].canAddSubscriber` | boolean | Whether the fan can be added as a subscriber. | | `data.list[].hideChat` | boolean | Whether chat is hidden for this fan. | | `data.list[].hasStories` | boolean | Whether the fan has active stories. | | `data.list[].hasStream` | boolean | Whether the fan is currently streaming. | | `data.list[].hasScheduledStream` | boolean | Whether the fan has a scheduled stream. | | `data.list[].hasNotViewedStory` | boolean | Whether the fan has unviewed stories. | | `data.list[].isPendingAutoprolong` | boolean | Whether an auto-renewal is pending. | | `data.list[].tipsEnabled` | boolean | Whether the fan accepts tips. | | `data.list[].tipsMin` | number | Minimum tip amount. | | `data.list[].tipsMax` | number | Maximum tip amount. | | `data.list[].tipsMinInternal` | number | Minimum internal tip amount. | | `data.list[].tipsTextEnabled` | boolean | Whether tip messages are enabled. | | `data.list[].promoOffers` | array | Active promo offers for this fan. Empty `[]` when none. | | `data.list[].notice` | string | Profile notice text. Empty string when none. | | `data.list[].view` | string | Internal view marker from OnlyFans. | | `data.hasMore` | boolean | Whether more results are available beyond `offset + limit`. | | `_pagination.next_page` | string | Relative URL preserving all supplied query parameters with `offset` bumped. Omitted on the last page. | ## Example response (200) ```json { "data": { "list": [ { "id": 100000003, "name": "Fan XX", "username": "u100000003", "displayName": "", "avatar": null, "avatarThumbs": null, "header": null, "headerSize": null, "headerThumbs": null, "isActive": true, "isBlocked": false, "isRestricted": false, "isVerified": false, "isPerformer": false, "isRealPerformer": false, "isPendingAutoprolong": false, "lastSeen": "2026-05-28T03:18:56+00:00", "subscribePrice": 0, "currentSubscribePrice": 0, "subscribedBy": true, "subscribedByAutoprolong": true, "subscribedByExpire": false, "subscribedByExpireDate": "2036-05-28T03:20:17+00:00", "subscribedIsExpiredNow": false, "subscribedByData": { "price": 0, "regularPrice": 0, "newPrice": 0, "subscribePrice": 0, "duration": "", "subscribeAt": "2026-05-28T03:20:17+00:00", "renewedAt": "2036-05-28T00:00:00+00:00", "expiredAt": "2036-05-28T03:20:17+00:00", "discountPercent": 0, "discountPeriod": 1, "discountStartedAt": null, "discountFinishedAt": null, "hasActivePaidSubscriptions": false, "isMuted": false, "showPostsInFeed": true, "status": null, "unsubscribeReason": "No reason given", "subscribes": [ { "id": 14972373744, "action": "subscribe", "type": "auto", "userId": 100000003, "subscriberId": 100000001, "date": "2026-05-28T03:20:17+00:00", "startDate": "2026-05-28T03:20:17+00:00", "expireDate": "2036-05-28T03:20:17+00:00", "cancelDate": null, "duration": 3653, "discount": 0, "price": 0, "regularPrice": 0, "earningId": 0, "offerStart": null, "offerEnd": null, "isCurrent": true } ] }, "subscribedOn": true, "subscribedOnDuration": "", "subscribedOnExpiredNow": false, "subscribedOnData": { "price": 0, "regularPrice": 0, "newPrice": 0, "subscribePrice": 0, "duration": "", "subscribeAt": "2026-05-28T03:20:15+00:00", "renewedAt": "2036-05-28T00:00:00+00:00", "expiredAt": "2036-05-28T03:20:15+00:00", "lastActivity": "2026-05-28T03:20:15+00:00", "discountPercent": 0, "discountPeriod": 1, "discountStartedAt": null, "discountFinishedAt": null, "hasActivePaidSubscriptions": false, "isMuted": false, "status": null, "messagesSumm": 0, "postsSumm": 0, "tipsSumm": 0, "subscribesSumm": 0, "streamsSumm": 0, "totalSumm": 0, "recommendations": 0, "unsubscribeReason": "No reason given", "subscribes": [ { "id": 14972373749, "action": "subscribe", "type": "regular", "userId": 100000001, "subscriberId": 100000003, "date": "2026-05-28T03:20:15+00:00", "startDate": "2026-05-28T03:20:15+00:00", "expireDate": "2036-05-28T03:20:15+00:00", "cancelDate": null, "duration": 3653, "discount": 0, "price": 0, "regularPrice": 0, "earningId": 0, "offerStart": null, "offerEnd": null, "isCurrent": true } ] }, "listsStates": [ { "id": "fans", "name": "Fans", "type": "fans", "hasUser": true, "canAddUser": false, "cannotAddUserReason": "ALREADY_EXISTS" }, { "id": "following", "name": "Following", "type": "following", "hasUser": true, "canAddUser": false, "cannotAddUserReason": "ALREADY_EXISTS" }, { "id": "friends", "name": "Friends", "type": "friends", "hasUser": false, "canAddUser": false, "cannotAddUserReason": "USER_NOT_PERFORMER" }, { "id": "muted", "name": "Muted", "type": "muted", "hasUser": false, "canAddUser": true, "cannotAddUserReason": null }, { "id": "recent", "name": "Recent (last 24 hours)", "type": "recent", "hasUser": true, "canAddUser": false, "cannotAddUserReason": "ALREADY_EXISTS" }, { "id": "tagged", "name": "Tagged", "type": "tagged", "hasUser": false, "canAddUser": false, "cannotAddUserReason": "SYSTEM_LIST" } ], "canAddSubscriber": false, "canCommentStory": true, "canLookStory": true, "canPayInternal": true, "canReceiveChatMessage": true, "canReport": true, "canRestrict": true, "canTrialSend": false, "canUnsubscribe": true, "canEarn": false, "hideChat": false, "hasStories": false, "hasStream": false, "hasScheduledStream": false, "hasNotViewedStory": false, "tipsEnabled": false, "tipsMin": 5, "tipsMax": 200, "tipsMinInternal": 1, "tipsTextEnabled": true, "promoOffers": [], "notice": "", "view": "x" } ], "hasMore": true }, "_pagination": { "next_page": "/v1/{account_id}/subscribers?limit=10&offset=10&type=active" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 991, "limit_day": 50000, "remaining_day": 49991 } } } ``` --- # Get Fan Details Section: API Reference › Fans. Page: https://api-docs.fansmetric.com/api-reference/fans/get-fan Returns full details for a fan — subscription data (both directions), notes, last seen, list memberships, restriction/block state. **Endpoint:** `GET /v1/{account_id}/fans/{user_id}` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_fans_read` Returns the full fan/user object from OnlyFans. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `user_id` | path | yes | | Fan's OnlyFans user ID. | ## Notes The full upstream OnlyFans user object is returned as-is inside `data`. To fetch multiple fans in one call, use `GET /v1/{account_id}/fans?ids=...`. To set/clear display name or notes, use the corresponding PUT/DELETE routes. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.id` | integer | Fan's OF user ID. | | `data.name` | string | Fan's name. | | `data.username` | string | Fan's username. | | `data.displayName` | string | Custom display name (empty if not set). | | `data.notice` | string | Private notes on the fan. | | `data.lastSeen` | string | Last online timestamp (ISO 8601). | | `data.isRestricted` | boolean | Whether the fan is restricted. | | `data.isBlocked` | boolean | Whether the fan is blocked. | | `data.subscribedByData` | object | Fan's subscription to you. | | `data.subscribedOnData` | object | Your subscription to the fan. | | `data.listsStates` | array | Which lists the fan belongs to. | ## Example response (200) ```json { "data": { "id": 7128, "username": "creator_XXXXX", "name": "Creator XX", "displayName": "Creator XX", "notice": "VIP fan", "lastSeen": "2026-05-18T10:00:00+00:00", "isRestricted": false, "isBlocked": false }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 990, "limit_day": 50000, "remaining_day": 49990 } } } ``` --- # Get Fan Details by IDs Section: API Reference › Fans. Page: https://api-docs.fansmetric.com/api-reference/fans/lookup-fans Batch lookup for fans by OnlyFans user ID. Returns a keyed object mapping each ID to the full fan detail object. **Endpoint:** `GET /v1/{account_id}/fans` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_fans_read` Looks up one or more fans by OnlyFans user ID. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `ids` | query | yes | | Comma-separated OF user IDs, e.g. `123,456,789`. | ## Notes Useful for hydrating partial fan objects returned by other endpoints (chat lists, message lists). Pass IDs as comma-separated string in the `ids` query parameter — same call returns a single fan when only one ID is supplied. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data` | object | Map of user ID → full fan detail object. | ## Example response (200) ```json { "data": { "1000000039": { "id": 1000000039, "name": "Fan XX", "username": "fan_XXXXX", "avatar": "...", "subscribedOnData": { "totalSumm": 150.00, "tipsSumm": 50.00, "duration": "11 months", "expiredAt": "2026-06-14T00:00:00+00:00" }, "notice": "VIP customer", "displayName": "Custom Name", "lastSeen": "2026-05-18T10:00:00+00:00" } }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 989, "limit_day": 50000, "remaining_day": 49989 } } } ``` --- # List Chat Lists Section: API Reference › Chats. Page: https://api-docs.fansmetric.com/api-reference/chats/list-chat-lists Returns the custom user lists that can be used to filter the chats endpoint (for example "VIP Fans", "New Subscribers"). For full list CRUD use the User Lists endpoints. **Endpoint:** `GET /v1/{account_id}/lists` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_chats_list_chat_lists` Lists the chat-list filters available for the connected account. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `limit` | query | no | | Number of lists. Default 10. Min 1, max 100. | | `offset` | query | no | | Pagination offset. | ## Notes This is a narrow read used to populate the chat filter dropdown. For creating, renaming, deleting, and managing membership in fan lists, see the User Lists routes. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[].id` | integer | List ID — pass to `/chats?list_id=...`. | | `data.list[].type` | string | Typically `custom`. | | `data.list[].name` | string | Display name. | | `data.list[].postsCount` | integer | Number of users in the list. | | `data.hasMore` | boolean | Whether more lists exist. | ## Example response (200) ```json { "data": { "list": [ { "id": 47382, "type": "custom", "name": "VIP Fans", "postsCount": 15 }, { "id": 47383, "type": "custom", "name": "Top Spenders", "postsCount": 8 } ], "hasMore": false }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 988, "limit_day": 50000, "remaining_day": 49988 } } } ``` --- # List Notifications Section: API Reference › Notifications. Page: https://api-docs.fansmetric.com/api-reference/notifications/list-notifications Returns notifications with cursor-based pagination. Filterable by category. **Endpoint:** `GET /v1/{account_id}/notifications` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_notifications_list` Lists notifications for the connected account. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `limit` | query | no | | Number of items. Default 10. Min 1, max 100. | | `type` | query | no | | Filter by category. Values: `subscribed`, `paided_message`, `purchases`, `tip`, `tags`, `commented`, `mentioned`, `favorited`, `message`, `system`, `deactivated_media`. Omit for all. | | `from_id` | query | no | | Cursor — last notification ID from previous page. | ## Notes Cursor-based pagination via `from_id`. Stop when `data.hasMore` is `false`. The `_pagination.next_page` URL is pre-built with the cursor. - Use `POST /v1/{account_id}/notifications/{type}/read` to mark a category as read ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[].id` | integer | Notification ID. | | `data.list[].type` | string | Notification type. | | `data.list[].createdAt` | string | ISO 8601 timestamp. | | `data.list[].isRead` | boolean | Whether the notification has been marked read. | | `data.hasMore` | boolean | Whether more pages exist. | | `_pagination.next_page` | string | Pre-built next-page URL with `from_id`. | ## Example response (200) ```json { "data": { "list": [ { "id": 100000000006, "type": "subscribed", "createdAt": "2026-05-17T14:49:00+00:00", "isRead": true } ], "hasMore": true }, "_pagination": { "next_page": "/v1/100000001/notifications?limit=10&from_id=100000000007" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 987, "limit_day": 50000, "remaining_day": 49987 } } } ``` --- # List Accounts Section: API Reference › Accounts. Page: https://api-docs.fansmetric.com/api-reference/accounts/list-accounts Returns all OnlyFans accounts linked to the authenticated organization. Connected accounts come first, then accounts with sync lost. Fansly/ChatBlue/Subs accounts and offboarded/deleted accounts are excluded. **Endpoint:** `GET /v1/accounts` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_accounts_list` Lists OnlyFans accounts linked to your organization. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `limit` | query | no | | Number of accounts per page. Default 20. Min 1, max 50 (values above 50 are clamped). | | `offset` | query | no | | Number of accounts to skip. | ## Notes Avatar URLs are hosted by the OnlyFans CDN — they may expire or change. - Default page size 20; max 50 (clamped) - Use the returned `account_id` as the path segment for account-scoped routes ## Response fields | Field | Type | Description | | --- | --- | --- | | `data[]` | array | Account objects for the current page. | | `data[].account_id` | integer | OnlyFans numeric user ID — used as `account_id` for other endpoints. | | `data[].username` | string | OnlyFans username / URL handle. | | `data[].display_name` | string | Display name on OnlyFans (may include emoji). | | `data[].avatar` | string | Full-size avatar URL. | | `data[].avatar_thumbs` | object \| null | Thumbnail avatar URLs (`c50`, `c144`). `null` if not available. | | `data[].fm_plan` | string | FansMetric plan: `standard` or `pro`. | | `data[].fm_status` | string | `connected` or `sync_lost`. | | `total` | integer | Total accounts across all pages. | | `limit` | integer | Applied page size after clamping. | | `offset` | integer | Applied offset. | | `next_page` | string \| null | Relative URL for the next page. `null` on the last page. | ## Example response (200) ```json { "data": [ { "account_id": 10000001, "username": "creator_XXXXX", "display_name": "Creator XX", "avatar": "https://public.onlyfans.com/files/.../avatar.jpg", "avatar_thumbs": { "c50": "https://thumbs.onlyfans.com/.../c50/.../avatar.jpg", "c144": "https://thumbs.onlyfans.com/.../c144/.../avatar.jpg" }, "fm_plan": "pro", "fm_status": "connected" } ], "total": 7, "limit": 20, "offset": 0, "next_page": null } ``` --- # Who Am I Section: API Reference › Accounts. Page: https://api-docs.fansmetric.com/api-reference/accounts/whoami Returns the API key's identity — its display name, key prefix, creation timestamp, assigned roles, and the full list of granted permissions. Use this to introspect what the current key can do without trial-and-erroring against protected endpoints. **Endpoint:** `GET /v1/whoami` **Base URL:** `https://public-api.fansmetric.com` **Permission:** none beyond a valid API key Returns the identity, roles, and permissions for the authenticated API key. ## Notes Unscoped — `account_id` is not in the path. The response describes the API key itself, not any connected OnlyFans account. Authentication is the only requirement; no specific permission gates this endpoint, so it can always be called by a valid key. `permissions` is the canonical source of truth for what the key is allowed to do. If an endpoint returns 403, compare its required permission against this list. - Requires a valid `Authorization: Bearer fm_api_...` header - Safe to call at app startup to sanity-check the key and cache the permission set ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.name` | string | Human-readable name assigned to the API key when it was created. | | `data.prefix` | string | Public prefix of the API key (e.g. `fm_api_hBLridINX1rdl`). Safe to log; the full secret is not returned. | | `data.created_at` | string | RFC 3339 timestamp (UTC) of when the API key was issued. | | `data.roles` | array | Roles assigned to the key. Each entry has `id` (UUID) and `name` (e.g. `Admin`). | | `data.roles[].id` | string | Role UUID. | | `data.roles[].name` | string | Human-readable role name. | | `data.permissions` | array | Flat list of permission keys granted to this API key (e.g. `api_accounts_list`, `api_messages_send`). Each documented endpoint lists the permission it requires. | ## Example response (200) ```json { "data": { "name": "balaji", "prefix": "fm_api_hBLridINX1rdl", "created_at": "2026-05-21T06:55:41.644769Z", "roles": [ { "id": "60f125d3-4bee-4983-9f76-a7a52c80393e", "name": "Admin" } ], "permissions": [ "api_accounts_list", "api_chats_list", "api_messages_send", "api_subscribers_list", "api_tracking_links_list", "api_user_lists_list" ] }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Health Check Section: API Reference › System. Page: https://api-docs.fansmetric.com/api-reference/system/health-check Liveness probe for the API service. No authentication required. Useful for uptime monitoring and load balancer health checks. **Endpoint:** `GET /health` **Base URL:** `https://public-api.fansmetric.com` **Permission:** none beyond a valid API key Returns 200 OK when the API service is reachable. ## Notes This is the only endpoint that does not require an API key. The response is a flat JSON object — no envelope, no `_meta`, no `_pagination`. It is intentionally minimal so it stays cheap to call from monitors. - No auth header required - Returns 200 with `{"status":"ok"}` when reachable - Does not check downstream dependencies — a successful response only confirms the API service is reachable. ## Response fields | Field | Type | Description | | --- | --- | --- | | `status` | string | Always `"ok"` on a successful response. | ## Example response (200) ```json { "status": "ok" } ``` --- # Mark Chats as Read Section: API Reference › Chats. Page: https://api-docs.fansmetric.com/api-reference/chats/mark-as-read Marks all chat conversations as read for the account. **Endpoint:** `POST /v1/{account_id}/chats/mark-as-read` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_chats_mark_as_read` Marks every chat conversation as read. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | ## Notes - No request body ## Response fields | Field | Type | Description | | --- | --- | --- | | `data` | object | `{ "success": true }` on success. | ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Mute Chat Section: API Reference › Chats. Page: https://api-docs.fansmetric.com/api-reference/chats/mute-chat Mutes notifications for a chat. The fan can still send messages — push notifications are suppressed. **Endpoint:** `POST /v1/{account_id}/chats/{user_id}/mute` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_chats_mute` Mutes a chat conversation. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `user_id` | path | yes | | Fan/user ID of the conversation. Use `withUser.id` from the chat list. | ## Notes ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Unmute Chat Section: API Reference › Chats. Page: https://api-docs.fansmetric.com/api-reference/chats/unmute-chat Re-enables notifications for a previously muted chat. **Endpoint:** `DELETE /v1/{account_id}/chats/{user_id}/mute` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_chats_unmute` Unmutes a chat conversation. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `user_id` | path | yes | | Fan/user ID of the conversation. | ## Notes ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Search Chat Messages Section: API Reference › Messages. Page: https://api-docs.fansmetric.com/api-reference/messages/search-messages Searches messages within a chat by text content. Returns an array of matching message IDs — use with List Chat Messages (`first_id` or `id`) to fetch full message content. **Endpoint:** `GET /v1/{account_id}/chats/{user_id}/messages/search` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_messages_search` Searches messages by text and returns matching IDs. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `user_id` | path | yes | | Fan/user ID of the conversation. | | `query` | query | yes | | Search text. | ## Notes Use the returned IDs with List Chat Messages to deep-link search results. A common pattern: `GET .../messages?limit=10&order=desc&id={resultId + 1}` loads messages around the result (using `id = resultId + 1` ensures the target is included). ## Response fields | Field | Type | Description | | --- | --- | --- | | `data` | array | Array of message IDs matching the search. | ## Example response (200) ```json { "data": [1000000000001, 1000000000004, 1000000000005], "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Like Message Section: API Reference › Messages. Page: https://api-docs.fansmetric.com/api-reference/messages/like-message Likes a message in a conversation. The like is visible to both parties. **Endpoint:** `POST /v1/{account_id}/messages/{message_id}/like` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_messages_like` Likes a message. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `message_id` | path | yes | | Message ID to like. | | `withUserId` | body | yes | | Fan/user ID — the other participant in the conversation. | ## Request body example ```json { "withUserId": 100000003 } ``` ## Notes ## Example response (200) ```json { "data": { "withUserId": 100000003 }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Unlike Message Section: API Reference › Messages. Page: https://api-docs.fansmetric.com/api-reference/messages/unlike-message Removes a like from a message. **Endpoint:** `DELETE /v1/{account_id}/messages/{message_id}/like` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_messages_unlike` Unlikes a message. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `message_id` | path | yes | | Message ID to unlike. | | `withUserId` | body | yes | | Fan/user ID in the conversation. | ## Request body example ```json { "withUserId": 100000003 } ``` ## Notes ## Example response (200) ```json { "data": { "withUserId": 100000003 }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Pin Message Section: API Reference › Messages. Page: https://api-docs.fansmetric.com/api-reference/messages/pin-message Pins a message in a conversation. Pinned messages stick to the top. **Endpoint:** `POST /v1/{account_id}/messages/{message_id}/pin/{user_id}` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_messages_pin` Pins a message. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `message_id` | path | yes | | Message ID to pin. | | `user_id` | path | yes | | Fan/user ID in the conversation. | ## Notes - No request body ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Unpin Message Section: API Reference › Messages. Page: https://api-docs.fansmetric.com/api-reference/messages/unpin-message Unpins a previously pinned message. **Endpoint:** `DELETE /v1/{account_id}/messages/{message_id}/pin/{user_id}` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_messages_unpin` Unpins a message. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `message_id` | path | yes | | Message ID to unpin. | | `user_id` | path | yes | | Fan/user ID in the conversation. | ## Notes ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Mass Message Statistics Section: API Reference › Mass Messages. Page: https://api-docs.fansmetric.com/api-reference/mass-messages/list-mass-messages Returns mass message stats — sent count, viewed count, media, and PPV purchase counts per mass message. Paginate by following `_pagination.next_page`. **Endpoint:** `GET /v1/{account_id}/mass-messages` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_mass_messages_list` Lists historical mass messages with stats, newest first. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `limit` | query | no | | Number of items. Default 10. Min 1, max 100. | | `start_date` | query | no | | Earliest mass message date (UTC). Default 2 years ago. Format `YYYY-MM-DD HH:MM:SS`; a bare RFC 3339 timestamp (`2026-08-19T00:00:00`) is also accepted, but **a trailing UTC offset such as `+00:00` is not** — strip it. Hold this value fixed while paginating. | | `end_date` | query | no | | Latest mass message date (UTC), **exclusive**. Default end of today. This doubles as the pagination cursor — prefer following `_pagination.next_page` over setting it by hand. Format `YYYY-MM-DD HH:MM:SS`. | ## Notes **Paginating:** follow `_pagination.next_page`. It is a ready-made relative URL with the cursor already applied and correctly formatted; append it to the API base URL and send it as-is. It is omitted once `data.hasMore` is `false`. Under the hood the cursor is `end_date`: each page is fetched with `end_date` set to the previous page's last item `date`, with `start_date` held fixed. The cursor is **exclusive**, so pages never overlap and a full page does not mean it is the last — trust `hasMore`, not the item count. Building the cursor by hand: `date` comes back as `2026-09-18T06:32:28+00:00` but `end_date` expects `2026-09-18 06:32:28` — drop the `T` and the `+00:00` offset. `_pagination.next_page` already does this for you. `price`, `purchasedCount` and `canSendMessageToBuyers` appear only on paid (PPV) sends. Free sends omit the keys entirely rather than returning `0`. Upstream OnlyFans endpoint: `GET /api2/v2/users/me/stats/messages/group`. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.items[]` | array | Per-mass-message stat rows, newest first. Shape is determined by upstream OnlyFans and proxied as-is. | | `data.items[].id` | integer | Mass message ID. | | `data.items[].date` | string | Send time, RFC 3339 **with** offset (`2026-09-18T06:32:28+00:00`). This is the value behind the pagination cursor, but it is not directly reusable as `end_date` — convert it to `2026-09-18 06:32:28` first (drop the `T` and the `+00:00`), or just use `_pagination.next_page`, which is already converted. | | `data.items[].sentCount` | integer | Fans the message was delivered to. | | `data.items[].viewedCount` | integer | Fans who opened it. | | `data.items[].price` | string | PPV price as a **decimal string** (e.g. `"14.59"`), not a number. **Omitted entirely on free sends** — check `isFree` before reading it. | | `data.items[].purchasedCount` | integer | Number of purchases of the PPV. Omitted on free sends. | | `data.items[].previews` | array | Media IDs shown as the free preview on a PPV send. Empty array on free sends. | | `data.items[].media[]` | array | Attached media: `id`, `type` (`photo` or `video`), `duration`, `videoSources`, and `files.{full,thumb,preview,squarePreview}` with signed FansMetric URLs. | | `data.items[].mediaCount` | integer | Number of attachments. | | `data.items[].isFree` | boolean | Whether the send carried no PPV price. | | `data.items[].isCanceled` | boolean | Whether the send was cancelled before completing. | | `data.items[].template` | string | Message kind — `group` for mass messages. | | `data.items[].canUnsend` | boolean | Whether the message is still inside its unsend window. | | `data.items[].unsendSeconds` | integer | Seconds remaining in the unsend window. | | `data.hasMore` | boolean | Whether another page exists. Stop paginating when this is `false`. | ## Example response (200) ```json { "data": { "hasMore": true, "items": [ { "id": 47038188668, "date": "2026-09-18T06:32:28+00:00", "responseType": "message", "text": "New set just dropped 💕", "rawText": "New set just dropped 💕", "giphyId": null, "isFree": false, "isTip": false, "isCanceled": false, "isReportedByMe": false, "isMediaReady": true, "mediaCount": 2, "media": [ { "id": 4066950154, "type": "photo", "convertedToVideo": false, "canView": true, "hasError": false, "hasCustomPreview": false, "createdAt": "2026-09-17T08:08:07+00:00", "isReady": true, "duration": 0, "files": { "full": { "url": "https://media.fansmetric.com/…", "width": 2632, "height": 3519, "size": 0, "sources": [] }, "thumb": { "url": "https://media.fansmetric.com/…", "width": 300, "height": 300, "size": 0 }, "preview": { "url": "https://media.fansmetric.com/…", "width": 960, "height": 1284, "size": 0 }, "squarePreview": { "url": "https://media.fansmetric.com/…", "width": 960, "height": 960, "size": 0 } }, "videoSources": { "720": null, "240": null } } ], "previews": [4066950154], "price": "14.59", "purchasedCount": 18, "canSendMessageToBuyers": true, "sentCount": 157066, "viewedCount": 3337, "template": "group", "canUnsend": false, "unsendSeconds": 0 } ] }, "_pagination": { "next_page": "/v1/100000001/mass-messages?start_date=2026-08-19+00%3A00%3A00&end_date=2026-09-18+06%3A32%3A28&limit=10" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Send Mass Message Section: API Reference › Mass Messages. Page: https://api-docs.fansmetric.com/api-reference/mass-messages/send Sends a mass message to selected fan lists and/or individual users. Supports text, media, PPV, GIFs, scheduling, and audience filters. To attach a new photo or video, see [Uploading Media](https://api-docs.fansmetric.com/uploading-media). **Endpoint:** `POST /v1/{account_id}/mass-messages` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_mass_messages_send` Creates a new mass message send. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `text` | body | no | string | Message text (HTML supported). Required unless `mediaFiles` or `giphyId` is set. | | `lockedText` | body | no | boolean | Hide the text behind the paywall. Defaults to `false`. | | `mediaFiles` | body | no | array | Vault media IDs, and new uploads as the `{ processId, host, name, extra }` object from [Uploading Media](https://api-docs.fansmetric.com/uploading-media#attach). Both can go in one list. Defaults to `[]`. | | `price` | body | no | number | PPV price in USD: `0` for free, otherwise 3-200. Defaults to `0`. | | `previews` | body | no | array | Preview media IDs for a paid message — a subset of `mediaFiles`. Defaults to `[]`. | | `rfTag` | body | no | array | OnlyFans user IDs of the creators to tag (release forms). Defaults to `[]`. | | `rfGuest` | body | no | array | Release-form guest IDs. Defaults to `[]`. | | `rfPartner` | body | no | array | Release-form partner IDs. Defaults to `[]`. | | `filters` | body | no | object | Audience filters. Supported keys: `totalSpent`, `tips`, `duration`, `inactive`, `online`, `signedUpAfter`, `signedUpBefore`. Defaults to no filters. | | `userLists` | body | no | array | Fan lists to send to: built-in lists by name, custom lists by ID, such as `["fans"]`, `[47382]` or `["fans", 47382]`. Required unless `userIds` is provided. | | `userIds` | body | no | array | Individual fans to send to, by user ID. Required unless `userLists` is provided. | | `excludedLists` | body | no | array | Fan lists to leave out of the audience, in the same form as `userLists`. | | `recommenders` | body | no | integer | Set to `1` to send only to recommended users. | | `giphyId` | body | no | string | Giphy GIF ID — get from `/v1/gifs/trending` or `/v1/gifs/search`. | | `isScheduled` | body | no | integer | Set to `1` to send at `scheduledDate` instead of now. | | `scheduledDate` | body | no | string | ISO 8601 timestamp for the scheduled send. Required when `isScheduled` is `1`. | ## Request body example ```json { "text": "Hello everyone!", "userLists": ["fans"], "mediaFiles": [], "price": 0, "filters": {} } ``` ## Notes Upstream OnlyFans endpoint: `POST /api2/v2/messages/queue`. Audience targeting requires at least one of `userLists` or `userIds` with an entry in it, or the request is refused with `400`. `excludedLists` only narrows an existing audience. Send only the fields you need: the rest take the defaults above, the same values the FansMetric app sends. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.id` | integer | Queue ID. Use this to cancel / look up the mass message. | | `data.date` | string | ISO 8601 timestamp of creation. | | `data.isReady` | boolean | True when the queue item is ready to send / currently sending. | | `data.isDone` | boolean | True when sending is complete. | | `data.total` | integer | Total recipients. `-1` or `0` while the count is still being resolved. | | `data.pending` | integer | Recipients still pending. | | `data.canUnsend` | boolean | Whether the mass message can still be cancelled. | | `data.unsendSeconds` | integer | Seconds remaining to unsend. | | `data.hasError` | boolean | True if sending hit an error. | | `data.isCanceled` | boolean | True if the mass message was cancelled. | | `data.isCouplePeopleMedia` | boolean | True when the media contains multiple people (release-form trigger). | ## Example response (200) ```json { "data": { "id": 10000000001, "date": "2026-05-14T18:05:07+00:00", "isReady": true, "isDone": false, "total": 1500, "pending": 200, "canUnsend": true, "unsendSeconds": 1000000, "hasError": false, "isCanceled": false, "isCouplePeopleMedia": false }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Mass Message Fan Lists Section: API Reference › Mass Messages. Page: https://api-docs.fansmetric.com/api-reference/mass-messages/fan-lists Returns fan lists available for targeting mass messages — built-in lists (`fans`, `recent`, `following`) plus custom lists. **Endpoint:** `GET /v1/{account_id}/mass-messages/lists` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_mass_messages_list_fan_lists` Lists fan lists usable as mass message targets. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `limit` | query | no | | Number per page. Default 10. Min 1, max 100. | | `offset` | query | no | | Pagination offset. | | `query` | query | no | | Case-insensitive substring match against the list name. Omit to return all lists. | | `related_user` | query | no | | OnlyFans numeric user ID. When set, results are restricted to lists that already contain that fan — handy for deduping before bulk-add. | ## Notes ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[].id` | integer\|string | List ID. String for built-in lists (`fans`, `recent`, `following`), integer for custom lists. | | `data.list[].type` | string | `fans`, `recent`, `custom`, `friends`, `tagged`, or `following`. | | `data.list[].name` | string | Display name. | | `data.list[].usersCount` | integer | Number of users. | ## Example response (200) ```json { "data": { "list": [ { "id": "fans", "type": "fans", "name": "All Subscribers", "usersCount": 5000 }, { "id": "recent", "type": "recent", "name": "Recent", "usersCount": 150 }, { "id": 47382, "type": "custom", "name": "VIP Fans", "usersCount": 50 } ], "hasMore": true }, "_pagination": { "next_page": "/v1/100000001/mass-messages/lists?limit=10&offset=10" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Mass Message Queue Section: API Reference › Mass Messages. Page: https://api-docs.fansmetric.com/api-reference/mass-messages/queue Returns the current mass message queue: in-progress sends, recently sent, and pending. Shown above the conversation list in the messages pro UI. **Endpoint:** `GET /v1/{account_id}/mass-messages/queue` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_mass_messages_list_queue` Lists active and pending mass message queue items. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | ## Notes ## Response fields | Field | Type | Description | | --- | --- | --- | | `data[].id` | integer | Queue ID — use to cancel/unsend. | | `data[].date` | string | Creation timestamp. | | `data[].isReady` | boolean | Whether it's ready / currently sending. | | `data[].isDone` | boolean | Whether sending is complete. | | `data[].total` | integer | Total recipients (`-1` or `0` when unknown). | | `data[].pending` | integer | Recipients still pending. | | `data[].canUnsend` | boolean | Whether it can still be cancelled. | | `data[].unsendSeconds` | integer | Seconds remaining to unsend. | | `data[].hasError` | boolean | True if sending errored. | | `data[].isCanceled` | boolean | True if cancelled. | | `data[].isCouplePeopleMedia` | boolean | Whether the media contains multiple people. | ## Example response (200) ```json { "data": [ { "id": 10000000001, "date": "2026-05-14T18:05:07+00:00", "isReady": true, "isDone": false, "total": 1500, "pending": 200, "canUnsend": true, "unsendSeconds": 1000000, "hasError": false, "isCanceled": false, "isCouplePeopleMedia": false } ], "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Mass Message Section: API Reference › Mass Messages. Page: https://api-docs.fansmetric.com/api-reference/mass-messages/get-queue-item Returns the latest snapshot of a single queue item — sent or still-scheduled. Same per-item fetch the OnlyFans web app uses when opening a queue row. Useful for refreshing a single row's `sentCount` / `viewedCount` without re-listing the whole queue, or for reading back the text/media/`scheduledDate` of a scheduled message before editing it. **Endpoint:** `GET /v1/{account_id}/mass-messages/queue/{queue_id}` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_mass_messages_read` Returns a single mass message queue item. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `queue_id` | path | yes | | The queue ID of the mass message to fetch. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/mass-messages/queue/{queue_id}`. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.success` | boolean | Whether the upstream lookup succeeded. | | `data.queue` | object | The queue item snapshot. | | `data.queue.id` | integer | Queue ID. | | `data.queue.date` | string | Send/scheduled timestamp (ISO 8601). | | `data.queue.text` | string | Message text (HTML). | | `data.queue.textCropped` | string | Cropped preview text used in list rows. | | `data.queue.giphyId` | string \| null | Giphy ID if the message is a GIF. | | `data.queue.isFree` | boolean | Whether the message is free (no paywall). | | `data.queue.sentCount` | integer | Recipients delivered to so far. | | `data.queue.viewedCount` | integer | Recipients who have opened the message. | | `data.queue.canUnsend` | boolean | Whether the message can still be cancelled. | | `data.queue.unsendSeconds` | integer | Seconds remaining in the unsend window. | | `data.queue.isCanceled` | boolean | True if the message has been cancelled. | | `data.queue.hasError` | boolean | True if sending errored. | | `data.queue.mediaTypes` | array \| null | Media-type summary if media is attached. | | `data.queue.releaseForms` | array | Release forms attached to the media, if any. | ## Example response (200) ```json { "data": { "success": true, "queue": { "id": 123, "date": "2026-06-05T12:00:00+00:00", "text": "VIP drop tomorrow", "giphyId": null, "textCropped": "VIP drop tomorrow", "isFree": true, "sentCount": 0, "viewedCount": 0, "canUnsend": true, "unsendSeconds": 60, "isCanceled": false, "mediaTypes": null, "hasError": false, "releaseForms": [] } }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Mass Message Buyers Section: API Reference › Mass Messages. Page: https://api-docs.fansmetric.com/api-reference/mass-messages/buyers Returns the fans who purchased a specific PPV mass message — the drill-down behind a queue row. [Mass Message Statistics](https://api-docs.fansmetric.com/api-reference/mass-messages/list-mass-messages) reports `sentCount` and `viewedCount` per message but carries no purchaser attribution; this endpoint is where that lives. **Endpoint:** `GET /v1/{account_id}/mass-messages/queue/{queue_id}/buyers` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_mass_messages_list_buyers` Lists the fans who purchased a PPV mass message. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `queue_id` | path | yes | | The queue ID of the mass message — from the queue list or Mass Message Statistics rows. | | `limit` | query | no | | Buyers per page. Default 10. Min 1, max 100. | | `offset` | query | no | | Pagination offset. | | `marker` | query | no | | Snapshot pin from a prior response. Omit on the first page — OnlyFans picks a pin and returns it in `data.marker`; pass it back unchanged on later pages. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/messages/queue/{queue_id}/buyers?limit=…&offset=…&marker=…&skip_users=all`. `skip_users=all` is sent like the OnlyFans web app, which is why rows are ID-only stubs — hydrate one with [Get Fan Details](https://api-docs.fansmetric.com/api-reference/fans/get-fan). Only meaningful for paid messages (`isFree: false`). A free message returns an empty list. Pagination is offset-based with a **snapshot pin**, the same scheme as [List Payout Requests](https://api-docs.fansmetric.com/api-reference/payouts/list-requests): `marker` freezes the result set so rows don't shift while purchases keep landing mid-pagination. Follow `_pagination.next_page` — it carries the pin and the advanced offset. If building URLs yourself, pass the same `marker` back unchanged with `offset += limit`. `_pagination` is emitted while upstream reports `hasMore: true` and omitted on the last page — stop when it disappears. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[]` | array | Buyers in this page — ID-only stubs. | | `data.list[].id` | integer | The fan's OnlyFans user ID. | | `data.list[]._view` | string | OnlyFans internal view marker. Ignore. | | `data.marker` | integer | Snapshot pin. Pass back unchanged while paginating. | | `data.hasMore` | boolean | Whether more buyers remain beyond this page. | ## Example response (200) ```json { "data": { "list": [ { "id": 378423681, "_view": "s" } ], "marker": 1056676717, "hasMore": true }, "_pagination": { "next_page": "/v1/100000001/mass-messages/queue/45990271701/buyers?limit=10&offset=10&marker=1056676717" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Update Mass Message Section: API Reference › Mass Messages. Page: https://api-docs.fansmetric.com/api-reference/mass-messages/update-queue-item Edits a queue item in place. The canonical "edit a scheduled mass message" operation — change the send time, rewrite the text, swap media, or move the audience without cancelling and recreating. Cannot edit messages already delivered (`isDone: true` or past `scheduledDate`). Pass `scheduledDate` alone to just reschedule, or submit a full snapshot to rewrite the message — both shapes are accepted. **Endpoint:** `PUT /v1/{account_id}/mass-messages/queue/{queue_id}` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_mass_messages_update` Updates a scheduled mass message queue item. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `queue_id` | path | yes | | The queue ID of the scheduled mass message to edit. | | `text` | body | no | | New message text. HTML accepted. | | `lockedText` | body | no | | Whether the text is locked behind the paywall. | | `mediaFiles` | body | no | | Vault media IDs to attach. Replaces the existing attachments when provided. | | `previews` | body | no | | Vault media IDs to surface as paywall previews. | | `price` | body | no | | Price in dollars. `0` for free. | | `userLists` | body | no | | Audience list IDs to send to. | | `userIds` | body | no | | Explicit user IDs to send to. | | `excludedLists` | body | no | | List IDs to exclude from the audience. | | `rfTag` | body | no | | Release-form tag identifier. | | `rfGuest` | body | no | | Release-form guest identifier. | | `rfPartner` | body | no | | Release-form partner identifier. | | `giphyId` | body | no | | Giphy ID if the message is a GIF. | | `scheduledDate` | body | no | | ISO timestamp for the (re)scheduled send. Pass this alone to just reschedule. | | `recommenders` | body | no | | Recommender block, matching the Send Mass Message shape. | | `filters` | body | no | | Audience filters, matching the Send Mass Message shape. | ## Request body example ```json { "scheduledDate": "2026-06-10T15:00:00.000Z" } ``` ## Notes Upstream OnlyFans endpoint: `PUT /api2/v2/mass-messages/queue/{queue_id}`. Body shape mirrors [Send Mass Message](https://api-docs.fansmetric.com/api-reference/mass-messages/send). Omitted fields are treated as unchanged by OnlyFans. In practice the OnlyFans web client always submits the full snapshot, which is also accepted. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.id` | integer | Queue ID. | | `data.date` | string | Updated send/scheduled timestamp. | | `data.isReady` | boolean | Whether the queue item is ready to send. | | `data.isDone` | boolean | Whether sending has completed (always `false` for edits). | | `data.canUnsend` | boolean | Whether the queue item can still be cancelled. | | `data.unsendSeconds` | integer | Seconds remaining in the unsend window. | | `data.hasError` | boolean | Whether the upstream edit errored. | | `data.isCanceled` | boolean | Always `false` for a successful edit. | ## Example response (200) ```json { "data": { "id": 123, "date": "2026-06-10T15:00:00+00:00", "isReady": true, "isDone": false, "total": -1, "pending": 0, "canUnsend": true, "unsendSeconds": 1000000, "hasError": false, "isCanceled": false, "isCouplePeopleMedia": false }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Cancel Mass Message Section: API Reference › Mass Messages. Page: https://api-docs.fansmetric.com/api-reference/mass-messages/cancel Cancels/unsends a mass message in the queue. Only works while `canUnsend` is `true`. **Endpoint:** `DELETE /v1/{account_id}/mass-messages/queue/{queue_id}` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_mass_messages_cancel` Cancels a queued mass message. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `queue_id` | path | yes | | Queue ID from the queue list. | ## Notes ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Direct Message Statistics Section: API Reference › Direct Messages. Page: https://api-docs.fansmetric.com/api-reference/direct-messages/stats Returns per-direct-message (1:1) delivery and engagement stats — same per-message shape as the mass-message stats endpoint, but scoped to direct messages instead of mass blasts. **Endpoint:** `GET /v1/{account_id}/direct-messages` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_direct_messages_stats` Lists direct-message stat rows with cursor (default) or offset (`query` search) pagination. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `limit` | query | no | | Number of messages to return. Default 10. Min 1, max 100. | | `start_date` | query | no | | Earliest message date (UTC). Default 2 years ago. Format `YYYY-MM-DD HH:MM:SS`; a bare ISO 8601 timestamp is also accepted, but **a trailing UTC offset such as `+00:00` is not** — strip it. Hold this value fixed while paginating. | | `end_date` | query | no | | Latest message date (UTC), **exclusive**. Default end of today. Doubles as the cursor for default (non-search) pagination — prefer following `_pagination.next_page` over setting it by hand. Format `YYYY-MM-DD HH:MM:SS`. | | `query` | query | no | | Text search across message bodies. When set, switches pagination to offset-based. | | `offset` | query | no | | Pagination offset. **Only used when `query` is set**; ignored otherwise. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/users/me/stats/messages/direct`. **Paginating:** follow `_pagination.next_page` — a ready-made relative URL with the cursor already applied. Omitted once `data.hasMore` is `false`. Under the hood the cursor is `end_date`, set to the previous page's last item `date` with `start_date` held fixed. Building it by hand means converting `2026-05-14T18:05:07+00:00` to `2026-05-14 18:05:07` — drop the `T` and the `+00:00` offset. Search pagination (`query` set): offset-based. Bump `offset` by `limit`. `end_date` becomes inert. Use [`/mass-messages`](https://api-docs.fansmetric.com/api-reference/mass-messages/list-mass-messages) for the engagement view of group sends. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.items[]` | array | Per-DM stat rows (`id`, `date`, `text`, `mediaCount`, `media`, `sentCount`, `viewedCount`, `isFree`, `isTip`, `template`, ...). Shape is determined by upstream OnlyFans and proxied as-is. | | `data.hasMore` | boolean | Whether more pages are available. | ## Example response (200) ```json { "data": { "hasMore": true, "items": [ { "id": 100000004, "date": "2026-05-14T18:05:07+00:00", "text": "thanks for the tip!", "sentCount": 1, "viewedCount": 1, "mediaCount": 0, "isFree": true, "isTip": false } ] }, "_pagination": { "next_page": "/v1/100000001/direct-messages?limit=10&end_date=2026-05-14+18%3A05%3A07" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Direct Message Chart Section: API Reference › Direct Messages. Page: https://api-docs.fansmetric.com/api-reference/direct-messages/chart Returns the same shape as [Mass Message Chart](https://api-docs.fansmetric.com/api-reference/mass-messages/chart) but scoped to 1:1 direct messages: sent counts under `direct_messages` and $ purchased from DMs under `direct_messages_purchases`. **Endpoint:** `GET /v1/{account_id}/direct-messages/chart` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_direct_messages_read_chart` Returns daily DM sent-count and purchases-$ series with window totals and prior-period deltas. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `start_date` | query | no | | Window start. Default 30 days ago, UTC. `YYYY-MM-DD HH:MM:SS` or ISO 8601. | | `end_date` | query | no | | Window end. Default end of today, UTC. Same format as `start_date`. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/messages/queue/chart?startDate=…&endDate=…&withTotal=true&filter[direct_messages]=direct_messages&filter[direct_messages_purchases]=direct_messages_purchases`. Shape parallels [Mass Message Chart](https://api-docs.fansmetric.com/api-reference/mass-messages/chart) — substitute `direct_messages` for `group_messages` throughout. `count` is row count in `direct_messages` and dollars in `direct_messages_purchases`. For the per-message engagement feed use [Direct Message Statistics](https://api-docs.fansmetric.com/api-reference/direct-messages/stats). ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.direct_messages.chart[]` | array | One bucket per UTC day inclusive of the window. `date` is midnight UTC ISO 8601; `count` is the **number of DMs sent** that day. | | `data.direct_messages.total` | number | Sum of `direct_messages.chart[].count` over the window. | | `data.direct_messages.delta` | number | `total` minus the total of the immediately preceding equal-length window. | | `data.direct_messages_purchases.chart[]` | array | One bucket per UTC day in the window. `count` is the **$ purchased** from DMs that day, in the account's payout currency. | | `data.direct_messages_purchases.total` | number | Sum of `direct_messages_purchases.chart[].count` over the window. | | `data.direct_messages_purchases.delta` | number | `total` minus the prior equal-length window's total. | ## Example response (200) ```json { "data": { "direct_messages": { "chart": [ { "date": "2026-06-01T00:00:00+00:00", "count": 512 }, { "date": "2026-06-02T00:00:00+00:00", "count": 535 } ], "total": 4224, "delta": -16 }, "direct_messages_purchases": { "chart": [ { "date": "2026-06-01T00:00:00+00:00", "count": 3980 }, { "date": "2026-06-02T00:00:00+00:00", "count": 3316.8 } ], "total": 27692.8, "delta": -7.2 } }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Scheduled Items Section: API Reference › Schedules. Page: https://api-docs.fansmetric.com/api-reference/schedules/list-scheduled-items Returns the creator's unified scheduled-items feed — posts, chats (DMs and mass messages), and streams that are queued for a future publish time, all in one list. This is the data the OnlyFans webapp's Schedule tab paints onto its calendar, scoped to a date window. Different from [List Mass Message Queue](https://api-docs.fansmetric.com/api-reference/mass-messages/queue), which only returns mass-message queue items — `/schedules` is the cross-type calendar view. **Endpoint:** `GET /v1/{account_id}/schedules` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_schedules_list` Lists scheduled posts, chats, and streams across a date window. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `start_date` | query | no | | Earliest publish date (inclusive). `YYYY-MM-DD`. Defaults to today (UTC). | | `end_date` | query | no | | Latest publish date (inclusive). `YYYY-MM-DD`. Defaults to `start_date`. | | `timezone` | query | no | | IANA timezone used to bucket items into days (e.g. `Europe/Prague`, `Asia/Kolkata`). Default `UTC`. | | `type` | query | no | | Filter to one or more item types: `chat`, `post`, `stream`. Either repeat the param (`type=chat&type=post`) or pass a comma-separated list (`type=chat,post`). | | `limit` | query | no | | Page size. Default 20. Min 1, max 100. | | `offset` | query | no | | Rows to skip. Default 0. | ## Notes Upstream OnlyFans endpoint uses bracketed filter form: `filter[publishDate]`, `filter[publishDateEnd]`, `filter[type][]`, `filter[timeZone]`. The public API accepts clean `snake_case` (`start_date`, `end_date`, `timezone`, `type`) and translates server-side. Offset-based pagination — `_pagination.next_page` is pre-built with `offset += limit` when `data.hasMore` is `true`. Use [Get Schedule Counters](https://api-docs.fansmetric.com/api-reference/schedules/get-schedule-counters) first to figure out which days have items before drilling into a specific day with this endpoint. - Returns posts, chats (DM + mass messages), and streams in one feed - Cross-type view — distinct from the mass-message-only [queue](https://api-docs.fansmetric.com/api-reference/mass-messages/queue) ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[]` | array | One entry per scheduled item, ordered by `publishDateTime`. | | `data.list[].id` | integer | Schedule entry ID — NOT the same as `entity.id` or `entity.queueId`. | | `data.list[].type` | string | `chat`, `post`, or `stream`. | | `data.list[].publishDateTime` | string | When the item is scheduled to go out (ISO 8601 with timezone). | | `data.list[].createdDateTime` | string | When the schedule was created. | | `data.list[].entity` | object | The underlying item. Shape varies by `type` — see [Get Mass Message](https://api-docs.fansmetric.com/api-reference/mass-messages/get-queue-item) for chat items; the OnlyFans post object for posts. | | `data.syncInProcess` | boolean | True if OnlyFans is still indexing recent scheduled items — the list may be partial. | | `data.hasMore` | boolean | More items exist past this page. | ## Example response (200) ```json { "data": { "list": [ { "id": 123, "type": "chat", "publishDateTime": "2026-06-10T15:00:00+00:00", "createdDateTime": "2026-06-02T10:00:00+00:00", "entity": { "responseType": "message", "id": 456, "text": "

Hi!

", "rawText": "Hi!", "price": 0, "isFree": true, "media": [], "previews": [], "scheduledAt": "2026-06-10T15:00:00+00:00", "userLists": ["fans"], "sentRulesType": "list", "sentRulesExtra": "Fans", "isFromQueue": true, "queueId": 789, "canUnsendQueue": true, "unsendSecondsQueue": 1000000 } }, { "id": 124, "type": "post", "publishDateTime": "2026-06-11T09:00:00+00:00", "createdDateTime": "2026-06-02T11:00:00+00:00", "entity": { "responseType": "post", "id": 555, "text": "Drop tomorrow", "rawText": "Drop tomorrow", "canDelete": true, "canEdit": true, "isMediaReady": true } } ], "syncInProcess": false, "hasMore": false }, "_pagination": { "next_page": null }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Schedule Counters Section: API Reference › Schedules. Page: https://api-docs.fansmetric.com/api-reference/schedules/get-schedule-counters Per-day counts of scheduled items across a date window, broken down by type. Powers the dots / badge numbers on the OnlyFans schedule calendar. Pull this once to know which days are non-empty before drilling into [List Scheduled Items](https://api-docs.fansmetric.com/api-reference/schedules/list-scheduled-items) for a specific day. **Endpoint:** `GET /v1/{account_id}/schedules/counters` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_schedules_counters` Returns per-day counts of scheduled items, by type. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `start_date` | query | no | | Earliest publish date (inclusive). `YYYY-MM-DD`. Defaults to today (UTC). | | `end_date` | query | no | | Latest publish date (inclusive). `YYYY-MM-DD`. Defaults to `start_date + 30 days`. | | `timezone` | query | no | | IANA timezone used to bucket items into days. Default `UTC`. | ## Notes Upstream OnlyFans endpoint uses the same `filter[publishDate]` / `filter[publishDateEnd]` / `filter[timeZone]` bracket form — translated server-side from the clean `snake_case` query params. Days with no scheduled items are omitted from `list` — render those as zero badges client-side. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list` | object | Map keyed by `YYYY-MM-DD`. Each value is a per-type count object (`post`, `chat`, `stream`). Days with no scheduled items are omitted. | ## Example response (200) ```json { "data": { "list": { "2026-06-02": { "post": 1, "chat": 2 }, "2026-06-05": { "post": 3 }, "2026-06-10": { "chat": 1, "stream": 1 } } }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Later Scheduled Chats Section: API Reference › Schedules. Page: https://api-docs.fansmetric.com/api-reference/schedules/list-later-chats Returns the next N upcoming scheduled chat items (DMs and mass messages), ordered by publish time, regardless of date. Useful as a "what's queued up soon?" feed without specifying a date range. **Endpoint:** `GET /v1/{account_id}/schedules/later/chat` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_schedules_later_chat` Returns the next N upcoming scheduled chats. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `limit` | query | no | | Number of upcoming items to return. Default 10. Min 1, max 50. | ## Notes No date window — returns the next `limit` upcoming chats in time order. Use this instead of [List Scheduled Items](https://api-docs.fansmetric.com/api-reference/schedules/list-scheduled-items) when you want a "Later" strip without juggling a date window. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[]` | array | Same item shape as [List Scheduled Items](https://api-docs.fansmetric.com/api-reference/schedules/list-scheduled-items) entries with `type: "chat"`. | ## Example response (200) ```json { "data": { "list": [ { "id": 123, "type": "chat", "publishDateTime": "2026-06-10T15:00:00+00:00", "createdDateTime": "2026-06-02T10:00:00+00:00", "entity": { "responseType": "message", "id": 456, "text": "

Hi!

", "isFromQueue": true, "queueId": 789 } } ] }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Later Scheduled Posts Section: API Reference › Schedules. Page: https://api-docs.fansmetric.com/api-reference/schedules/list-later-posts Returns the next N upcoming scheduled posts, ordered by publish time. Same "Later" strip as [List Later Scheduled Chats](https://api-docs.fansmetric.com/api-reference/schedules/list-later-chats) but for the feed side. **Endpoint:** `GET /v1/{account_id}/schedules/later/post` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_schedules_later_post` Returns the next N upcoming scheduled posts. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `limit` | query | no | | Number of upcoming items to return. Default 10. Min 1, max 50. | ## Notes No date window — returns the next `limit` upcoming posts in time order. Pair with [List Later Scheduled Chats](https://api-docs.fansmetric.com/api-reference/schedules/list-later-chats) to render both "Later" strips on a schedule dashboard. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[]` | array | Same item shape as [List Scheduled Items](https://api-docs.fansmetric.com/api-reference/schedules/list-scheduled-items) entries with `type: "post"`. | ## Example response (200) ```json { "data": { "list": [ { "id": 124, "type": "post", "publishDateTime": "2026-06-11T09:00:00+00:00", "createdDateTime": "2026-06-02T11:00:00+00:00", "entity": { "responseType": "post", "id": 555, "text": "Drop tomorrow", "canDelete": true, "canEdit": true, "isMediaReady": true } } ] }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List User Lists Section: API Reference › User Lists. Page: https://api-docs.fansmetric.com/api-reference/user-lists/list-user-lists Returns the custom fan lists. The server-side sort call is fired before fetching, so results are consistent across requests. **Endpoint:** `GET /v1/{account_id}/user-lists` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_user_lists_list` Lists the connected account's custom user lists. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `limit` | query | no | | Default 10. Min 1, max 100. | | `offset` | query | no | | Pagination offset. | | `sort_by` | query | no | | `custom` (default), `recent`, `name`, or `people`. | | `sort_dir` | query | no | | `asc` (default) or `desc`. | | `query` | query | no | | Case-insensitive substring match against the list name. Omit to return all lists. | | `related_user` | query | no | | OnlyFans numeric user ID. When set, results are restricted to lists that already contain that fan. | ## Notes ## Example response (200) ```json { "data": { "list": [ { "id": "giphy_XXXXX", "type": "custom", "name": "VIP Fans", "usersCount": 50, "postsCount": 0 } ], "hasMore": true, "sort": "custom", "order": "asc" }, "_pagination": { "next_page": "/v1/100000001/user-lists?limit=10&offset=10&sort_by=custom&sort_dir=asc" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Create User List Section: API Reference › User Lists. Page: https://api-docs.fansmetric.com/api-reference/user-lists/create Creates a new custom user list. **Endpoint:** `POST /v1/{account_id}/user-lists` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_user_lists_create` Creates a custom user list. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `name` | body | yes | | Name for the new list. | ## Request body example ```json { "name": "My New List" } ``` ## Notes ## Example response (200) ```json { "data": { "id": "giphy_YYYYY", "type": "custom", "name": "My New List", "usersCount": 0 }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Rename User List Section: API Reference › User Lists. Page: https://api-docs.fansmetric.com/api-reference/user-lists/rename Renames a custom user list. **Endpoint:** `PATCH /v1/{account_id}/user-lists/{list_id}` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_user_lists_rename` Renames a custom user list. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `list_id` | path | yes | | List ID to rename. | | `name` | body | yes | | New name. | ## Request body example ```json { "name": "New Name" } ``` ## Notes ## Example response (200) ```json { "data": { "id": "giphy_XXXXX", "name": "New Name" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Delete User List Section: API Reference › User Lists. Page: https://api-docs.fansmetric.com/api-reference/user-lists/delete Deletes a custom user list. **Endpoint:** `DELETE /v1/{account_id}/user-lists/{list_id}` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_user_lists_delete` Deletes a custom user list. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `list_id` | path | yes | | List ID to delete. | ## Notes ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List User List Members Section: API Reference › User Lists. Page: https://api-docs.fansmetric.com/api-reference/user-lists/list-members Returns the members of a specific list. The sort call always fires before fetching. **Endpoint:** `GET /v1/{account_id}/user-lists/{list_id}/users` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_user_lists_list_members` Lists fans in a custom list. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `list_id` | path | yes | | List ID. Use a system list slug (`fans`, `following`, `friends`, `muted`, `recent`, `tagged`) or a numeric custom list ID. | | `limit` | query | no | | Default 10. Min 1, max 100. | | `offset` | query | no | | Pagination offset. | | `sort_by` | query | no | | `recent` (default). | | `sort_dir` | query | no | | `asc` or `desc` (default). | ## Notes `list_id` accepts both system list slugs (`fans`, `following`, `friends`, `muted`, `recent`, `tagged`) and numeric custom list IDs returned from `GET /v1/{account_id}/user-lists`. Spend rollups live under `subscribedOnData` (`messagesSumm`, `postsSumm`, `tipsSumm`, `subscribesSumm`, `streamsSumm`, `totalSumm`) — these reflect the fan's lifetime spend on the connected account, not just within this list. Stop paginating when `hasMore` is `false`. `_pagination.next_page` is omitted on the last page. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[].id` | integer | OnlyFans user ID for the fan. | | `data.list[].name` | string | Display name. Falls back to `u{id}` when not set by the user. | | `data.list[].username` | string | Login handle. Falls back to `u{id}` when not set. | | `data.list[].displayName` | string | User-set display name. Often empty. | | `data.list[].avatar` | string\|null | Avatar URL. `null` when no avatar is set. | | `data.list[].avatarThumbs` | object\|null | Avatar thumbnails: `c50`, `c144`. `null` when no avatar. | | `data.list[].header` | string\|null | Header image URL. `null` when not set. | | `data.list[].headerSize` | object\|null | Header dimensions: `width`, `height`. May be `null`. | | `data.list[].headerThumbs` | object\|null | Header thumbnails: `w480`, `w760`. `null` when no header. | | `data.list[].isActive` | boolean | Whether the account is active on OnlyFans. | | `data.list[].isBlocked` | boolean | Whether the fan is blocked by this account. | | `data.list[].isRestricted` | boolean | Whether the fan is restricted by this account. | | `data.list[].isVerified` | boolean | OnlyFans verified flag. | | `data.list[].isPerformer` | boolean | Whether the fan is a creator on OnlyFans. | | `data.list[].isRealPerformer` | boolean | Whether the fan is a fully verified creator. | | `data.list[].lastSeen` | string\|null | RFC 3339 timestamp of the fan's last activity. `null` when never seen or hidden. | | `data.list[].subscribePrice` | number | Base subscription price (USD). | | `data.list[].currentSubscribePrice` | number | Current effective price after discounts (USD). | | `data.list[].subscribedBy` | boolean | Whether the connected account is subscribed to this fan. | | `data.list[].subscribedByAutoprolong` | boolean | Whether that subscription auto-renews. | | `data.list[].subscribedByExpire` | boolean | Whether the connected account's subscription is set to expire. | | `data.list[].subscribedByExpireDate` | string\|null | Expiry timestamp for the connected account's subscription. | | `data.list[].subscribedByData` | object | Detail of the connected account's subscription to this fan: `price`, `regularPrice`, `subscribeAt`, `expiredAt`, `renewedAt`, `duration`, `subscribes[]`, etc. | | `data.list[].subscribedOn` | boolean | Whether this fan is subscribed to the connected account. | | `data.list[].subscribedOnDuration` | string | Duration label of the fan's subscription (e.g. `7 months`). | | `data.list[].subscribedOnExpiredNow` | boolean | Whether the fan's subscription has already expired. | | `data.list[].subscribedOnData` | object | Detail of the fan's subscription to the connected account. Includes spend rollups: `messagesSumm`, `postsSumm`, `tipsSumm`, `subscribesSumm`, `streamsSumm`, `totalSumm`, plus `subscribeAt`, `expiredAt`, `lastActivity`, `subscribes[]`. | | `data.list[].listsStates` | array | Membership in all visible lists (system + custom). Each entry: `id`, `name`, `type`, `hasUser`, `canAddUser`, `cannotAddUserReason`. | | `data.list[].canReceiveChatMessage` | boolean | Whether the connected account can DM this fan. | | `data.list[].canCommentStory` | boolean | Whether the connected account can comment on the fan's stories. | | `data.list[].canLookStory` | boolean | Whether the connected account can view the fan's stories. | | `data.list[].canPayInternal` | boolean | Whether internal payments are enabled. | | `data.list[].canReport` | boolean | Whether the fan can be reported. | | `data.list[].canRestrict` | boolean | Whether the fan can be restricted. | | `data.list[].canTrialSend` | boolean | Whether a free trial can be sent to this fan. | | `data.list[].canUnsubscribe` | boolean | Whether the connected account can unsubscribe from this fan. | | `data.list[].canEarn` | boolean | Whether the connected account can earn from this fan. | | `data.list[].canAddSubscriber` | boolean | Whether the fan can be added as a subscriber. | | `data.list[].hideChat` | boolean | Whether chat is hidden for this fan. | | `data.list[].hasStories` | boolean | Whether the fan has active stories. | | `data.list[].hasStream` | boolean | Whether the fan is currently streaming. | | `data.list[].hasScheduledStream` | boolean | Whether the fan has a scheduled stream. | | `data.list[].hasNotViewedStory` | boolean | Whether the fan has unviewed stories. | | `data.list[].isPendingAutoprolong` | boolean | Whether an auto-renewal is pending. | | `data.list[].tipsEnabled` | boolean | Whether the fan accepts tips. | | `data.list[].tipsMin` | number | Minimum tip amount. | | `data.list[].tipsMax` | number | Maximum tip amount. | | `data.list[].tipsMinInternal` | number | Minimum internal tip amount. | | `data.list[].tipsTextEnabled` | boolean | Whether tip messages are enabled. | | `data.list[].promoOffers` | array | Active promo offers for this fan. Empty `[]` when none. | | `data.list[].notice` | string | Profile notice text. Empty string when none. | | `data.list[].view` | string | Internal view marker from OnlyFans. | | `data.hasMore` | boolean | Whether more results are available beyond `offset + limit`. | | `data.nextOffset` | integer | Offset to pass on the next request for the next page. | | `_pagination.next_page` | string | Relative URL preserving all supplied query parameters with `offset` bumped. Omitted on the last page. | ## Example response (200) ```json { "data": { "hasMore": true, "list": [ { "id": 100000004, "name": "Fan XX", "username": "fan_XXXXX", "displayName": "", "avatar": "https://public.onlyfans.com/.../avatar.jpg", "avatarThumbs": { "c50": "https://thumbs.onlyfans.com/.../c50/avatar.jpg", "c144": "https://thumbs.onlyfans.com/.../c144/avatar.jpg" }, "header": "https://public.onlyfans.com/.../header.jpg", "headerSize": { "width": 500, "height": 374 }, "headerThumbs": { "w480": "https://thumbs.onlyfans.com/.../w480/header.jpg", "w760": "https://thumbs.onlyfans.com/.../w760/header.jpg" }, "isActive": true, "isBlocked": false, "isRestricted": false, "isVerified": false, "isPerformer": false, "isRealPerformer": false, "isPendingAutoprolong": false, "lastSeen": null, "subscribePrice": 0, "currentSubscribePrice": 0, "subscribedBy": true, "subscribedByAutoprolong": true, "subscribedByExpire": false, "subscribedByExpireDate": "2035-10-31T11:57:25+00:00", "subscribedIsExpiredNow": false, "subscribedByData": { "price": 0, "regularPrice": 0, "newPrice": 0, "subscribePrice": 0, "duration": "7 months", "subscribeAt": "2025-10-14T01:11:43+00:00", "renewedAt": "2035-10-31T00:00:00+00:00", "expiredAt": "2035-10-31T11:57:25+00:00", "discountPercent": 0, "discountPeriod": 1, "discountStartedAt": null, "discountFinishedAt": null, "hasActivePaidSubscriptions": false, "isMuted": false, "showPostsInFeed": true, "status": null, "unsubscribeReason": "No reason given", "subscribes": [ { "id": 14223525731, "action": "return", "type": "regular", "userId": 100000004, "subscriberId": 100000001, "date": "2025-10-31T11:57:25+00:00", "startDate": "2025-10-31T11:57:25+00:00", "expireDate": "2035-10-31T11:57:25+00:00", "cancelDate": null, "duration": 3652, "discount": 0, "price": 0, "regularPrice": 0, "earningId": 0, "offerStart": null, "offerEnd": null, "isCurrent": true } ] }, "subscribedOn": true, "subscribedOnDuration": "7 months", "subscribedOnExpiredNow": false, "subscribedOnData": { "price": 0, "regularPrice": 0, "newPrice": 0, "subscribePrice": 0, "duration": "7 months", "subscribeAt": "2025-10-13T18:45:30+00:00", "renewedAt": null, "expiredAt": "2036-05-11T00:20:38+00:00", "lastActivity": "2026-05-11T00:20:38+00:00", "discountPercent": 0, "discountPeriod": 1, "discountStartedAt": null, "discountFinishedAt": null, "hasActivePaidSubscriptions": false, "isMuted": false, "status": "Set to Expire", "messagesSumm": 120, "postsSumm": 0, "tipsSumm": 0, "subscribesSumm": 0, "streamsSumm": 0, "totalSumm": 120, "recommendations": 0, "unsubscribeReason": "No reason given", "subscribes": [ { "id": 14912579866, "action": "return", "type": "regular", "userId": 100000001, "subscriberId": 100000004, "date": "2026-05-11T00:20:38+00:00", "startDate": "2026-05-11T00:20:38+00:00", "expireDate": "2036-05-11T00:20:38+00:00", "cancelDate": null, "duration": 3653, "discount": 0, "price": 0, "regularPrice": 0, "earningId": 0, "offerStart": null, "offerEnd": null, "isCurrent": true } ] }, "listsStates": [ { "id": "fans", "name": "Fans", "type": "fans", "hasUser": true, "canAddUser": false, "cannotAddUserReason": "ALREADY_EXISTS" }, { "id": "following", "name": "Following", "type": "following", "hasUser": true, "canAddUser": false, "cannotAddUserReason": "ALREADY_EXISTS" }, { "id": "friends", "name": "Friends", "type": "friends", "hasUser": false, "canAddUser": false, "cannotAddUserReason": "USER_NOT_PERFORMER" }, { "id": "muted", "name": "Muted", "type": "muted", "hasUser": false, "canAddUser": true, "cannotAddUserReason": null }, { "id": "recent", "name": "Recent (last 24 hours)", "type": "recent", "hasUser": false, "canAddUser": false, "cannotAddUserReason": "SYSTEM_LIST" }, { "id": "tagged", "name": "Tagged", "type": "tagged", "hasUser": false, "canAddUser": false, "cannotAddUserReason": "SYSTEM_LIST" }, { "id": "1252268925", "name": "VIP Fans", "type": "custom", "hasUser": true, "canAddUser": false, "cannotAddUserReason": "ALREADY_EXISTS" } ], "canAddSubscriber": false, "canCommentStory": true, "canLookStory": true, "canPayInternal": true, "canReceiveChatMessage": true, "canReport": true, "canRestrict": true, "canTrialSend": false, "canUnsubscribe": true, "canEarn": false, "hideChat": false, "hasStories": false, "hasStream": false, "hasScheduledStream": false, "hasNotViewedStory": false, "tipsEnabled": false, "tipsMin": 5, "tipsMax": 200, "tipsMinInternal": 1, "tipsTextEnabled": true, "promoOffers": [], "notice": "", "view": "x" } ], "nextOffset": 12 }, "_pagination": { "next_page": "/v1/{account_id}/user-lists/{list_id}/users?limit=10&offset=10" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Add User to List Section: API Reference › User Lists. Page: https://api-docs.fansmetric.com/api-reference/user-lists/add-member Adds a fan to a custom list. **Endpoint:** `POST /v1/{account_id}/user-lists/{list_id}/users/{user_id}` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_user_lists_add_member` Adds a fan to a list. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `list_id` | path | yes | | List ID. | | `user_id` | path | yes | | Fan/user OF ID to add. | ## Notes - No request body ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Remove User from List Section: API Reference › User Lists. Page: https://api-docs.fansmetric.com/api-reference/user-lists/remove-member Removes a fan from a custom list. **Endpoint:** `DELETE /v1/{account_id}/user-lists/{list_id}/users/{user_id}` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_user_lists_remove_member` Removes a fan from a list. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `list_id` | path | yes | | List ID. | | `user_id` | path | yes | | Fan/user OF ID to remove. | ## Notes ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Subscription Counts Section: API Reference › Subscribers. Page: https://api-docs.fansmetric.com/api-reference/subscribers/counts Counts for all subscription categories — subscribers (fans), following, and bookmarks. **Endpoint:** `GET /v1/{account_id}/subscriptions/counts` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_subscribers_counts` Returns subscriber and following counts. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | ## Notes ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.subscriptions` | object | Accounts the user follows: `active`, `muted`, `restricted`, `expired`, `blocked`, `attention`, `all`. | | `data.subscribers` | object | Fans subscribed to the user: `active`, `muted`, `restricted`, `expired`, `blocked`, `all`, `activeOnline`. | | `data.bookmarks` | integer | Bookmarked items. | ## Example response (200) ```json { "data": { "subscriptions": { "active": 74358, "muted": 0, "restricted": 0, "expired": 6234, "blocked": 0, "attention": 27, "all": 80592 }, "subscribers": { "active": 114150, "muted": 0, "restricted": 316, "expired": 10624, "blocked": 13, "all": 124774, "activeOnline": 0 }, "bookmarks": 0 }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Following Section: API Reference › Subscribers. Page: https://api-docs.fansmetric.com/api-reference/subscribers/following Accounts the user is following (subscribed to). Supports filtering and sorting. **Endpoint:** `GET /v1/{account_id}/following` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_subscribers_list_following` Lists accounts the user is subscribed to. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `limit` | query | no | | Default 10. Min 1, max 100. | | `offset` | query | no | | Pagination offset. | | `type` | query | no | | `all` (default), `active`, `expired`, or `attention`. | | `sort_by` | query | no | | `last_activity` (default), `expire_date`, `subscribe_date`, or `is_expired`. | | `sort_dir` | query | no | | `desc` (default) or `asc`. | | `filter_paid` | query | no | | `true` for paid only, `false` for free only. | | `filter_online` | query | no | | `true` for online only. | ## Notes ## Example response (200) ```json { "data": { "list": [ { "id": 1234, "username": "creator.x", "name": "Creator X" } ], "hasMore": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Top Subscribers Section: API Reference › Subscribers. Page: https://api-docs.fansmetric.com/api-reference/subscribers/top Top subscribers ranked by activity within a date range. All four query params are optional — defaults match the OnlyFans web client (total spend over the last month). **Endpoint:** `GET /v1/{account_id}/subscribers/top` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_subscribers_list_top` Lists top subscribers by spend or activity. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `start_date` | query | no | | UTC start of the window. Format `YYYY-MM-DD HH:MM:SS` (ISO 8601 with `T` accepted — we convert it to a space). Do not include a timezone suffix (`Z` / `+00:00`) — OnlyFans rejects it. Default: now − 1 month. Forwarded to OF as `startDate`. | | `end_date` | query | no | | UTC end of the window. Same format as `start_date`. Default: now. Forwarded to OF as `endDate`. | | `by` | query | no | | Ranking metric. One of `total` (lifetime spend — canonical "top by spend"), `currency` (spend within the window), `recent`, `messages`, `posts`, `media`. Default: `total`. | | `offset` | query | no | | Pagination offset. OnlyFans pages this endpoint in fixed pages of 10 — pass multiples of 10. Default: `0`. There is no `limit` parameter; page size is fixed upstream. | ## Notes Date format is `YYYY-MM-DD HH:MM:SS` (UTC). Sending ISO 8601 with `T` works (we replace it with a space), but do **not** include a timezone suffix — OnlyFans rejects any value with a `Z` or `+00:00` tail. OnlyFans only includes subscribers with activity in the requested window. An empty list usually means the window is too narrow, in the future, or covers a quiet period — widen the window before reporting a bug. No `limit` query param — OnlyFans paginates this endpoint in fixed pages of 10 via `offset` only. Stop paginating when `hasMore` is `false`. ## Example response (200) ```json { "data": { "list": [ { "id": 1234567, "name": "Top Fan", "username": "topfan", "avatar": "https://public.onlyfans.com/.../avatar.jpg", "subscribePrice": 9.99, "isVerified": false, "spentTotal": 1234.56 } ], "hasMore": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Latest Subscribers Section: API Reference › Subscribers. Page: https://api-docs.fansmetric.com/api-reference/subscribers/latest Latest subscribers in a date range, filtered by `new`, `renew`, or `total`. **Endpoint:** `GET /v1/{account_id}/subscribers/latest` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_subscribers_list_latest` Lists recent subscribers. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `offset` | query | no | | Pagination offset. | | `start_date` | query | no | | UTC start. Default 30 days ago. | | `end_date` | query | no | | UTC end. Default now. | | `type` | query | no | | `new` (default), `renew`, or `total`. | ## Notes - Pagination is offset-based — stop when fewer items than the page size come back ## Example response (200) ```json { "data": { "list": [], "hasMore": false }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Restricted Users Section: API Reference › Subscribers. Page: https://api-docs.fansmetric.com/api-reference/subscribers/restricted Users restricted by the account (cannot DM or comment). **Endpoint:** `GET /v1/{account_id}/users/restricted` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_subscribers_list_restricted` Lists restricted users. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `limit` | query | no | | Default 10. Min 1, max 100. | | `offset` | query | no | | Pagination offset. | ## Notes ## Example response (200) ```json { "data": { "list": [], "hasMore": false }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Blocked Users Section: API Reference › Subscribers. Page: https://api-docs.fansmetric.com/api-reference/subscribers/blocked Users blocked by the account (cannot access the profile). **Endpoint:** `GET /v1/{account_id}/users/blocked` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_subscribers_list_blocked` Lists blocked users. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `limit` | query | no | | Default 10. Min 1, max 100. | | `offset` | query | no | | Pagination offset. | ## Notes ## Example response (200) ```json { "data": { "list": [], "hasMore": false }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get User Profile Section: API Reference › Subscribers. Page: https://api-docs.fansmetric.com/api-reference/subscribers/get-user-profile Returns a user profile by username. Works for any OF user. **Endpoint:** `GET /v1/{account_id}/users/{username}` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_subscribers_read_profile` Looks up a profile by username. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `username` | path | yes | | OnlyFans username (e.g. `superfordfan`). | ## Notes Returns the full upstream user profile as-is. For lookup by numeric user ID, use `GET /v1/{account_id}/fans/{user_id}` instead. ## Example response (200) ```json { "data": { "id": 12345, "username": "superfordfan", "name": "Super Fan" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Block User Section: API Reference › User Actions. Page: https://api-docs.fansmetric.com/api-reference/user-actions/block Blocks a user from accessing the account's profile. **Endpoint:** `POST /v1/{account_id}/users/{user_id}/block` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_block_user` Blocks a user. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `user_id` | path | yes | | User ID to block. | ## Notes - No request body ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Report User Section: API Reference › User Actions. Page: https://api-docs.fansmetric.com/api-reference/user-actions/report Reports a user to OnlyFans. **Endpoint:** `POST /v1/{account_id}/users/{user_id}/report` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_report_user` Reports a user. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `user_id` | path | yes | | User ID to report. | | `reasonId` | body | yes | | Report reason index (0-4). 0=TOS, 1=DMCA, 2=CSAM, 3=Spam, 4=Abuse. | | `issue` | body | yes | | Description of the issue (min 5 characters). | ## Request body example ```json { "reasonId": 0, "issue": "Description of the issue" } ``` ## Notes ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Restrict User Section: API Reference › User Actions. Page: https://api-docs.fansmetric.com/api-reference/user-actions/restrict Restricts a user — they cannot DM or respond to posts. **Endpoint:** `POST /v1/{account_id}/users/{user_id}/restrict` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_restrict_user` Restricts a user. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `user_id` | path | yes | | User ID to restrict. | ## Notes - No request body ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Unrestrict User Section: API Reference › User Actions. Page: https://api-docs.fansmetric.com/api-reference/user-actions/unrestrict Removes a user restriction. **Endpoint:** `DELETE /v1/{account_id}/users/{user_id}/restrict` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_unrestrict_user` Unrestricts a user. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `user_id` | path | yes | | User ID to unrestrict. | ## Notes ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Update Fan Display Name Section: API Reference › Fans. Page: https://api-docs.fansmetric.com/api-reference/fans/update-display-name Sets a custom display name for a fan. Visible only to the account owner and overrides the fan's original name in the UI. **Endpoint:** `PUT /v1/{account_id}/fans/{user_id}/display-name` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_fans_update_display_name` Sets a fan's custom display name. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `user_id` | path | yes | | Fan's OnlyFans user ID. | | `displayName` | body | yes | | Custom display name. Empty string `""` clears and reverts to the original. Max 100 chars. | ## Request body example ```json { "displayName": "Custom Name" } ``` ## Notes ## Example response (200) ```json { "data": { "id": 12345, "displayName": "Custom Name" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Update Fan Notes Section: API Reference › Fans. Page: https://api-docs.fansmetric.com/api-reference/fans/update-notes Sets private notes on a fan. Only visible to the account owner. **Endpoint:** `PUT /v1/{account_id}/fans/{user_id}/notes` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_fans_update_notes` Sets a fan's private notes. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `user_id` | path | yes | | Fan's OnlyFans user ID. | | `notice` | body | yes | | Note text. Empty string `""` clears. | ## Request body example ```json { "notice": "VIP customer, always tip well" } ``` ## Notes ## Example response (200) ```json { "data": { "id": 12345, "notice": "VIP customer, always tip well" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Delete Fan Notes Section: API Reference › Fans. Page: https://api-docs.fansmetric.com/api-reference/fans/delete-notes Clears all notes on a fan. Server-side, this sends `notice: ""` to OnlyFans — no request body needed. **Endpoint:** `DELETE /v1/{account_id}/fans/{user_id}/notes` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_fans_delete_notes` Clears a fan's notes. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `user_id` | path | yes | | Fan's OnlyFans user ID. | ## Notes ## Example response (200) ```json { "data": { "id": 12345, "notice": "" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Fans Section: API Reference › Fans. Page: https://api-docs.fansmetric.com/api-reference/fans/list-fans Your fans ranked by what they have spent, across the accounts you pick. Only people who actually paid show up — subscribers who never bought anything are not on this list. Filter by spend, number of purchases, or how recently they bought. **Endpoint:** `POST /v1/fans` **Base URL:** `https://public-api.fansmetric.com` **Data source:** FansMetric data. Served from the FansMetric database — revenue, cost, tags and extra filters, refreshed by the scraper. **Permission:** `api_fans_list` Lifetime per-fan spend aggregates across one or more accounts. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_ids` | body | yes | | Array of OnlyFans numeric account IDs. Aggregates are summed **across** them, not returned per account. An ID you do not own returns 404. | | `sort_by` | body | no | | One of `total_spend` (default), `purchases_count`, `average_purchase`, `average_weekly_spend`, `last_purchase_at`. Anything else returns 400 — there is no silent fallback. | | `sort_dir` | body | no | | `asc` or `desc` (default), case-insensitive. Any other value returns 400. | | `limit` | body | no | | Default 25, min 1, max 100. | | `offset` | body | no | | Default 0. | | `total_spend` | body | no | object | Keep fans whose lifetime spend falls in this range. `{ "min": number, "max": number }` — either half may be omitted or `null` to leave that side unbounded. | | `purchases_count` | body | no | object | Same `{min, max}` shape, on the number of non-refunded purchases. | | `average_purchase` | body | no | object | Same `{min, max}` shape, on `total_spend` ÷ `purchases_count`. | | `average_weekly_spend` | body | no | object | Same `{min, max}` shape. Fans active a week or less have an `average_weekly_spend` of 0, so a `min` above 0 excludes them. | | `last_purchase_within_days` | body | no | integer | A whole number of days, not a range — keep only fans whose most recent purchase falls within this many days. Must be ≥ 1. | ## Request body example ```json { "account_ids": ["100000001"], "sort_by": "total_spend", "sort_dir": "desc", "limit": 25, "offset": 0, "total_spend": { "min": 100, "max": null }, "last_purchase_within_days": 30 } ``` ## Notes ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.fans[].id` | string \| null | The fan's OnlyFans numeric user ID. Pass it as `{fan_id}` to every other fan route. `null` only if the fan's profile record has been purged while their transactions survive. | | `data.fans[].name` | string \| null | OnlyFans display name. | | `data.fans[].username` | string \| null | OnlyFans username. | | `data.fans[].avatar_url` | string \| null | Avatar URL. | | `data.fans[].total_spend` | number | Gross lifetime spend across the named accounts. Gross, not net — this is what the fan paid, not what the creator received. | | `data.fans[].average_purchase` | number | `total_spend` ÷ `purchases_count`. | | `data.fans[].average_weekly_spend` | number | `7 × total_spend ÷ (days_active + 1)`, and **0 for any fan active 7 days or fewer** — a single large purchase would otherwise project an implausible weekly rate. | | `data.fans[].days_active` | number | Days between the fan's first and last transaction. 0 for a fan with a single purchase. | | `data.fans[].purchases_count` | integer | Number of non-refunded transactions. | | `data.fans[].last_purchase_at` | string \| null | Most recent transaction timestamp (RFC 3339, UTC). | | `_pagination.next_page` | string \| null | The `offset` to send for the next page. Absent when this is the last page. | ## Example response (200) ```json { "data": { "fans": [ { "id": "100000010", "name": "Fan XX", "username": "fan_XXXXX", "avatar_url": "https://public.onlyfans.com/files/.../avatar.jpg", "total_spend": 1250, "average_purchase": 50, "average_weekly_spend": 62.5, "days_active": 139, "purchases_count": 25, "last_purchase_at": "2025-05-31T07:48:16Z" } ] }, "_pagination": { "next_page": "25" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Fan Stats Section: API Reference › Fans. Page: https://api-docs.fansmetric.com/api-reference/fans/get-fan-stats A fan's spending split by account — one row per account you name, biggest spender first. Accounts they never bought from come back at zero rather than being dropped. The per-account view that [List Fans](https://api-docs.fansmetric.com/api-reference/fans/list-fans) rolls into a single total. **Endpoint:** `POST /v1/fans/{fan_id}/stats` **Base URL:** `https://public-api.fansmetric.com` **Data source:** FansMetric data. Served from the FansMetric database — revenue, cost, tags and extra filters, refreshed by the scraper. **Permission:** `api_fans_read_stats` Per-account lifetime spend aggregates for one fan. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `fan_id` | path | yes | | The fan's OnlyFans numeric user ID. | | `account_ids` | body | yes | | Array of OnlyFans numeric account IDs to report on. Every one you name gets a row, including accounts the fan has never bought from — those come back at `0` with null dates. | ## Request body example ```json { "account_ids": ["100000002", "100000001"] } ``` ## Notes ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.stats[].account_id` | string | OnlyFans numeric account ID — the same value you sent in `account_ids`. | | `data.stats[].account_name` | string | The account's OnlyFans username. | | `data.stats[].total_spend` | number | Gross lifetime spend by this fan on this account. | | `data.stats[].purchase_count` | integer | Number of non-refunded transactions. | | `data.stats[].largest_purchase` | number | Single biggest transaction. | | `data.stats[].average_purchase` | number | Mean transaction value. | | `data.stats[].first_purchase_at` | string \| null | Their first purchase on this account (RFC 3339, UTC). `null` when they have never bought from it. | | `data.stats[].last_purchase_at` | string \| null | Their most recent purchase on this account (RFC 3339, UTC). Same field name as on [List Fans](https://api-docs.fansmetric.com/api-reference/fans/list-fans), where it spans every account you named rather than one. | ## Example response (200) ```json { "data": { "stats": [ { "account_id": "100000001", "account_name": "creator_XXXXX", "total_spend": 1163.02, "purchase_count": 90, "largest_purchase": 39, "average_purchase": 12.922444444444444, "first_purchase_at": "2022-07-19T10:19:07Z", "last_purchase_at": "2025-09-06T00:17:16Z" }, { "account_id": "100000002", "account_name": "creator_YYYYY", "total_spend": 0, "purchase_count": 0, "largest_purchase": 0, "average_purchase": 0, "first_purchase_at": null, "last_purchase_at": null } ] }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Fan Transactions Section: API Reference › Fans. Page: https://api-docs.fansmetric.com/api-reference/fans/get-fan-transactions Every purchase one fan has made across the accounts you name, newest first, each with what the fan paid and what the creator kept. Refunds and chargebacks are included here, unlike the spend totals elsewhere, so a reversal shows up next to the charge it cancels. **Endpoint:** `POST /v1/fans/{fan_id}/transactions` **Base URL:** `https://public-api.fansmetric.com` **Data source:** FansMetric data. Served from the FansMetric database — revenue, cost, tags and extra filters, refreshed by the scraper. **Permission:** `api_fans_read_transactions` Paginated transaction history for one fan. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `fan_id` | path | yes | | The fan's OnlyFans numeric user ID. | | `account_ids` | body | yes | | Array of OnlyFans numeric account IDs. | | `limit` | body | no | | Default 25, min 1, max 100. | | `offset` | body | no | | Default 0. | | `categories` | body | no | array | Keep only these transaction kinds. Any of `tip`, `message`, `recurring_subscription`, `new_subscription`, `unlock`, `unknown`. Absent or `[]` means every category. An unrecognised value returns 400 listing the allowed set — it never silently matches nothing. | | `statuses` | body | no | array | Keep only these statuses. Any of `done`, `undo`, `pending_return`, `loading`. Absent or `[]` means every status, chargebacks included. An unrecognised value returns 400. | | `from` | body | no | | Window start, inclusive. `YYYY-MM-DD`, `YYYY-MM-DD HH:MM:SS`, RFC 3339, `now`, or a relative shorthand like `-30days`. Absent means no lower bound. | | `to` | body | no | | Window end, inclusive. Same formats. Absent means no upper bound. Sending `from` later than `to` returns 400. | ## Request body example ```json { "account_ids": ["100000001"], "limit": 25, "offset": 0, "categories": ["message", "tip"], "statuses": ["done"], "from": "2026-01-01", "to": "now" } ``` ## Notes ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.transactions[].id` | string | OnlyFans' own transaction ID — the same one OnlyFans shows for this charge. | | `data.transactions[].transaction_created_at` | string \| null | When the transaction occurred (RFC 3339, UTC). | | `data.transactions[].account_id` | string | OnlyFans numeric account ID the transaction belongs to — one of the `account_ids` you sent. | | `data.transactions[].account_name` | string | That account's OnlyFans username. | | `data.transactions[].amount` | number \| null | Gross — what the fan paid. This is the figure [List Fans](https://api-docs.fansmetric.com/api-reference/fans/list-fans) and [Get Fan Stats](https://api-docs.fansmetric.com/api-reference/fans/get-fan-stats) total up, so summing it reproduces `total_spend`. `null` on older rows imported without the breakdown. | | `data.transactions[].fee` | number \| null | OnlyFans' cut. `null` where unknown. | | `data.transactions[].vat_amount` | number \| null | VAT collected on the sale. `null` where unknown. | | `data.transactions[].net` | number | What the creator received — `amount` less `fee` and `vat_amount`. Always present, even where the breakdown is not. | | `data.transactions[].currency` | string \| null | Currency the amounts are in, as OnlyFans reported it. `null` on rows that predate the field. | | `data.transactions[].category` | string \| null | Transaction kind — one of `tip`, `message`, `recurring_subscription`, `new_subscription`, `unlock`, `unknown`. `null` is possible on legacy rows and is treated as `unknown` by the `categories` filter. | | `data.transactions[].status` | string | `done` (settled), `undo` (refund or chargeback), `pending_return` (reversal in progress), or `loading` (still processing), as reported by OnlyFans. | | `_pagination.next_page` | string \| null | The `offset` for the next page. Absent on the last page. | ## Example response (200) ```json { "data": { "transactions": [ { "id": "3491820745", "transaction_created_at": "2025-09-28T04:55:39Z", "account_id": "100000001", "account_name": "creator_XXXXX", "amount": 40, "fee": 8, "vat_amount": 0, "net": 32, "currency": "USD", "category": "message", "status": "done" } ] }, "_pagination": { "next_page": "25" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Fan Transaction Counts Section: API Reference › Fans. Page: https://api-docs.fansmetric.com/api-reference/fans/get-fan-transaction-counts How many transactions match your filters, split by type and by status. Takes the same body as [Get Fan Transactions](https://api-docs.fansmetric.com/api-reference/fans/get-fan-transactions), so you can show the counts without pulling the rows. **Endpoint:** `POST /v1/fans/{fan_id}/transactions/counts` **Base URL:** `https://public-api.fansmetric.com` **Data source:** FansMetric data. Served from the FansMetric database — revenue, cost, tags and extra filters, refreshed by the scraper. **Permission:** `api_fans_read_transactions` Counts for the filtered transaction set. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `fan_id` | path | yes | | The fan's OnlyFans numeric user ID. | | `account_ids` | body | yes | | Array of OnlyFans numeric account IDs. | | `categories` | body | no | array | Keep only these transaction kinds. Any of `tip`, `message`, `recurring_subscription`, `new_subscription`, `unlock`, `unknown`. Absent or `[]` means every category. An unrecognised value returns 400 listing the allowed set — it never silently matches nothing. | | `statuses` | body | no | array | Keep only these statuses. Any of `done`, `undo`, `pending_return`, `loading`. Absent or `[]` means every status, chargebacks included. An unrecognised value returns 400. | | `from` | body | no | | Window start, inclusive. `YYYY-MM-DD`, `YYYY-MM-DD HH:MM:SS`, RFC 3339, `now`, or a relative shorthand like `-30days`. Absent means no lower bound. | | `to` | body | no | | Window end, inclusive. Same formats as `from`. Absent means no upper bound. Sending `from` later than `to` returns 400. | | `limit` | body | no | | Accepted and ignored — this endpoint counts rather than pages, so nothing is truncated. Present only so the identical body works on [Get Fan Transactions](https://api-docs.fansmetric.com/api-reference/fans/get-fan-transactions) too. | | `offset` | body | no | | Accepted and ignored, like `limit`. | ## Request body example ```json { "account_ids": ["100000001"], "statuses": ["undo"] } ``` ## Notes ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.all` | integer | Total transactions matching the filters. | | `data.categories` | object | One key per category — `tip`, `message`, `recurring_subscription`, `new_subscription`, `unlock`, `unknown` — each an integer. Every key is always present, `0` when empty. | | `data.statuses` | object | One key per status — `done`, `undo`, `pending_return`, `loading`. Always all four, `0` when empty. | ## Example response (200) ```json { "data": { "all": 34, "categories": { "tip": 4, "message": 22, "recurring_subscription": 6, "new_subscription": 2, "unlock": 0, "unknown": 0 }, "statuses": { "done": 29, "undo": 5, "pending_return": 0, "loading": 0 } }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Fan Custom Name Section: API Reference › Fans. Page: https://api-docs.fansmetric.com/api-reference/fans/get-fm-name Your team's own name for a fan on one account — the label you typed, not the one OnlyFans shows. Comes back `null` when nobody has set one. **Endpoint:** `GET /v1/{account_id}/fm/fans/{fan_id}/name` **Base URL:** `https://public-api.fansmetric.com` **Data source:** FansMetric data. Served from the FansMetric database — revenue, cost, tags and extra filters, refreshed by the scraper. **Permission:** `api_fm_fans_read_name` Reads the FansMetric custom display name. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `fan_id` | path | yes | | Fan's OnlyFans numeric user ID. | ## Notes ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.name` | string \| null | The custom label, or `null` when your organisation has never set one for this fan on this account. | ## Example response (200) ```json { "data": { "name": "VIP" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Update Fan Custom Name Section: API Reference › Fans. Page: https://api-docs.fansmetric.com/api-reference/fans/update-fm-name Sets your team's own name for a fan on one account. Saved inside FansMetric only — to change the name OnlyFans shows, use [Update Fan Display Name](https://api-docs.fansmetric.com/api-reference/fans/update-display-name). **Endpoint:** `PATCH /v1/{account_id}/fm/fans/{fan_id}/name` **Base URL:** `https://public-api.fansmetric.com` **Data source:** FansMetric data. Served from the FansMetric database — revenue, cost, tags and extra filters, refreshed by the scraper. **Permission:** `api_fm_fans_update_name` Writes the FansMetric custom display name. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `fan_id` | path | yes | | Fan's OnlyFans numeric user ID. | | `name` | body | yes | | The label. An empty string `""` is stored and returned as `""`. Omitting the key, or sending `null`, returns 400. | ## Request body example ```json { "name": "VIP" } ``` ## Notes ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.name` | string | The value now stored. | ## Example response (200) ```json { "data": { "name": "VIP" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Fan Metadata Section: API Reference › Fans. Page: https://api-docs.fansmetric.com/api-reference/fans/get-fm-metadata Your private notes on a fan's timezone, birthday and city for one account. Each one is optional and comes back `null` when nobody has filled it in. **Endpoint:** `GET /v1/{account_id}/fm/fans/{fan_id}/metadata` **Base URL:** `https://public-api.fansmetric.com` **Data source:** FansMetric data. Served from the FansMetric database — revenue, cost, tags and extra filters, refreshed by the scraper. **Permission:** `api_fm_fans_read_metadata` Reads the fan's timezone, birthday and city. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `fan_id` | path | yes | | Fan's OnlyFans numeric user ID. | ## Notes ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.timezone` | string \| null | IANA timezone name, e.g. `America/New_York`. | | `data.birthday` | string \| null | Date only, `YYYY-MM-DD`. | | `data.city` | string \| null | Free text. | ## Example response (200) ```json { "data": { "timezone": "America/New_York", "birthday": "1990-04-01", "city": "Austin" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Update Fan Metadata Section: API Reference › Fans. Page: https://api-docs.fansmetric.com/api-reference/fans/update-fm-metadata Updates a fan's timezone, birthday or city. Send only what you want to change — anything you leave out stays as it is, and sending `null` clears it. **Endpoint:** `PATCH /v1/{account_id}/fm/fans/{fan_id}/metadata` **Base URL:** `https://public-api.fansmetric.com` **Data source:** FansMetric data. Served from the FansMetric database — revenue, cost, tags and extra filters, refreshed by the scraper. **Permission:** `api_fm_fans_update_metadata` Merge-patches the fan's metadata. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `fan_id` | path | yes | | Fan's OnlyFans numeric user ID. | | `timezone` | body | no | | String or `null`. Omit to leave unchanged. | | `birthday` | body | no | | `YYYY-MM-DD` or `null`. Any other format returns 400. | | `city` | body | no | | String or `null`. Omit to leave unchanged. | ## Request body example ```json { "birthday": "1990-04-01", "city": null } ``` ## Notes ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.timezone` | string \| null | Value after the patch. | | `data.birthday` | string \| null | Value after the patch. | | `data.city` | string \| null | Value after the patch. | ## Example response (200) ```json { "data": { "timezone": "America/New_York", "birthday": "1990-04-01", "city": null }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Fan Note Section: API Reference › Fans. Page: https://api-docs.fansmetric.com/api-reference/fans/get-fm-note Your team's free-text note about a fan on one account. This is FansMetric's own note, not the one OnlyFans keeps — see [Update Fan Notes](https://api-docs.fansmetric.com/api-reference/fans/update-notes) for that one. **Endpoint:** `GET /v1/{account_id}/fm/fans/{fan_id}/note` **Base URL:** `https://public-api.fansmetric.com` **Data source:** FansMetric data. Served from the FansMetric database — revenue, cost, tags and extra filters, refreshed by the scraper. **Permission:** `api_fm_fans_read_note` Reads the FansMetric note. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `fan_id` | path | yes | | Fan's OnlyFans numeric user ID. | ## Notes ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.body` | string \| null | The note text, or `null` when none exists. | | `data.created_at` | string \| null | When the note was first written (RFC 3339, UTC). | | `data.updated_at` | string \| null | When it was last changed (RFC 3339, UTC). | ## Example response (200) ```json { "data": { "body": "Prefers voice notes. Buys on Fridays.", "created_at": "2026-09-10T21:04:52Z", "updated_at": "2026-09-10T21:04:53Z" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Update Fan Note Section: API Reference › Fans. Page: https://api-docs.fansmetric.com/api-reference/fans/update-fm-note Writes your team's note about a fan on one account, creating it if there is not one yet. Leaves the note OnlyFans keeps untouched. **Endpoint:** `PATCH /v1/{account_id}/fm/fans/{fan_id}/note` **Base URL:** `https://public-api.fansmetric.com` **Data source:** FansMetric data. Served from the FansMetric database — revenue, cost, tags and extra filters, refreshed by the scraper. **Permission:** `api_fm_fans_update_note` Writes the FansMetric note. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `fan_id` | path | yes | | Fan's OnlyFans numeric user ID. | | `body` | body | yes | | Note text. `""` is stored and returned as `""`. Omitting the key, or sending `null`, returns 400. | ## Request body example ```json { "body": "Prefers voice notes. Buys on Fridays." } ``` ## Notes ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.body` | string | The note now stored. | | `data.created_at` | string | Unchanged by an update — it records the first write. | | `data.updated_at` | string | Refreshed on every write. | ## Example response (200) ```json { "data": { "body": "Prefers voice notes. Buys on Fridays.", "created_at": "2026-09-10T21:04:52Z", "updated_at": "2026-09-10T21:04:53Z" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Fan Links Section: API Reference › Fans. Page: https://api-docs.fansmetric.com/api-reference/fans/get-fm-links The trial and tracking links this fan claimed on one account — the "how did they find us" panel. Both lists are always arrays, empty when there is nothing to show. **Endpoint:** `GET /v1/{account_id}/fm/fans/{fan_id}/links` **Base URL:** `https://public-api.fansmetric.com` **Data source:** FansMetric data. Served from the FansMetric database — revenue, cost, tags and extra filters, refreshed by the scraper. **Permission:** `api_fm_fans_read_links` Lists the links a fan claimed on this account. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `fan_id` | path | yes | | Fan's OnlyFans numeric user ID. | ## Notes ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.trial_links[].name` | string \| null | Trial link name. | | `data.trial_links[].url` | string \| null | The OnlyFans trial URL. | | `data.trial_links[].claim_count` | integer \| null | Total claims on the link, across all fans — not this fan's claims. | | `data.trial_links[].is_hidden` | boolean \| null | Whether the link is hidden in the web app. | | `data.trial_links[].created_at` | string \| null | When the link was created (RFC 3339, UTC). | | `data.tracking_links[].name` | string \| null | Campaign name. | | `data.tracking_links[].code` | integer \| null | OnlyFans campaign code. A **number**, matching `campaignCode` on the tracking-link endpoints. | | `data.tracking_links[].claim_count` | integer \| null | Total claims on the campaign, across all fans. | | `data.tracking_links[].is_hidden` | boolean \| null | Whether the campaign is hidden in the web app. | | `data.tracking_links[].created_at` | string \| null | When the campaign was created (RFC 3339, UTC). | ## Example response (200) ```json { "data": { "trial_links": [], "tracking_links": [ { "name": "Reddit — r/onlyfans100", "code": 22, "claim_count": 320, "is_hidden": false, "created_at": "2025-04-23T20:27:51Z" } ] }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Fan Chat Summary Section: API Reference › Fans. Page: https://api-docs.fansmetric.com/api-reference/fans/get-fm-chat-summary The AI-written summary of a fan's conversation on one account. Read-only: it returns a summary that already exists and never writes a new one, so it comes back empty for a fan nobody has summarised. **Endpoint:** `GET /v1/{account_id}/fm/fans/{fan_id}/chat-summary` **Base URL:** `https://public-api.fansmetric.com` **Data source:** FansMetric data. Served from the FansMetric database — revenue, cost, tags and extra filters, refreshed by the scraper. **Permission:** `api_fm_fans_read_chat_summary` Reads the stored chat summary. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `fan_id` | path | yes | | Fan's OnlyFans numeric user ID. | ## Notes ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.body` | string \| null | The summary text, or `null` when this fan has never been summarised on this account. | | `data.created_at` | string \| null | When the summary was first generated (RFC 3339, UTC). | | `data.updated_at` | string \| null | When it was last regenerated (RFC 3339, UTC). | ## Example response (200) ```json { "data": { "body": "Long-term subscriber, mostly buys PPV photo sets. Responds well to voice notes and tends to purchase on Friday evenings.", "created_at": "2026-01-12T04:27:31Z", "updated_at": "2026-01-12T04:27:31Z" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Subscription History Section: API Reference › Subscriptions. Page: https://api-docs.fansmetric.com/api-reference/subscriptions/history Full subscription history of a fan — subscribe/unsubscribe events, renewals, expirations, and spend data. **Endpoint:** `GET /v1/{account_id}/subscriptions/{user_id}/history` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_subscriptions_read_history` Returns a fan's subscription history. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `user_id` | path | yes | | Fan's OnlyFans user ID. | ## Notes Raw OnlyFans response returned as-is — exact field shape varies. ## Example response (200) ```json { "data": [ { "type": "subscribe", "createdAt": "2025-06-01T00:00:00+00:00", "amount": 9.99 } ], "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Mark Notifications Read Section: API Reference › Notifications. Page: https://api-docs.fansmetric.com/api-reference/notifications/mark-read Marks all notifications of a specific type as read. **Endpoint:** `POST /v1/{account_id}/notifications/{type}/read` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_notifications_mark_read` Marks notifications of a category as read. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `type` | path | yes | | Notification type: `subscribed`, `purchases`, `tip`, `tags`, `commented`, `mentioned`, `favorited`, `message`, `deactivated_media`. | ## Notes - No request body ## Example response (200) ```json { "data": { "counters": { "subscribed": 0, "purchases": 0 }, "hasSystemNotifications": false, "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Notification Counts Section: API Reference › Notifications. Page: https://api-docs.fansmetric.com/api-reference/notifications/count Notification counts by category. **Endpoint:** `GET /v1/{account_id}/notifications/count` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_notifications_count` Returns unread notification counts per category. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | ## Notes ## Example response (200) ```json { "data": { "all": 0, "subscribed": 0, "purchases": 0, "tip": 0, "tags": 0, "commented": 0, "mentioned": 0, "favorited": 0, "message": 0, "system": 0, "deactivated_media": 0 }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Notification Tabs Order Section: API Reference › Notifications. Page: https://api-docs.fansmetric.com/api-reference/notifications/get-tabs-order Returns the configured order of notification tabs/categories. **Endpoint:** `GET /v1/{account_id}/notifications/tabs-order` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_notifications_read_tabs_order` Returns the saved notification tab order. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | ## Notes ## Example response (200) ```json { "data": [ "all", "subscribed", "purchases", "tip", "tags", "commented", "mentioned", "favorited", "message", "deactivated_media" ], "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Update Notification Tabs Order Section: API Reference › Notifications. Page: https://api-docs.fansmetric.com/api-reference/notifications/update-tabs-order Updates the order of notification tabs. **Endpoint:** `PUT /v1/{account_id}/notifications/tabs-order` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_notifications_update_tabs_order` Saves a new notification tab order. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | ## Request body example ```json [ "all", "subscribed", "purchases", "tip", "tags", "commented", "mentioned", "favorited", "deactivated_media", "message" ] ``` ## Notes Request body is a bare JSON array of tab keys in the desired order. The order is persisted as the user's notification tab layout. ## Example response (200) ```json { "data": [ "all", "subscribed", "purchases", "tip", "tags", "commented", "mentioned", "favorited", "deactivated_media", "message" ], "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Trending GIFs Section: API Reference › GIFs. Page: https://api-docs.fansmetric.com/api-reference/gifs/trending Trending GIFs via the OnlyFans Giphy proxy. Use to show a default GIF picker before any search is typed. **Endpoint:** `GET /v1/gifs/trending` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_gifs_trending` Lists trending GIFs. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `limit` | query | no | | Default 20. Min 1, max 50. | | `offset` | query | no | | Pagination offset. | ## Notes Response is a slim transform of the upstream Giphy payload — only the renditions listed above are returned. Per-rendition fields are limited to `url`, `width`, `height`, and `mp4` (when present). Stop paginating when `pagination.offset + pagination.count >= pagination.total_count`. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.data[].id` | string | Giphy GIF ID — pass as `giphyId` when sending a message. | | `data.data[].title` | string | Human-readable GIF title from Giphy. | | `data.data[].alt_text` | string | Accessibility alt text. May be empty. | | `data.data[].rating` | string | Giphy content rating (e.g. `g`, `pg`, `pg-13`, `r`). | | `data.data[].is_sticker` | integer | `1` if the asset is a sticker, otherwise `0`. | | `data.data[].type` | string | Asset type — typically `gif`. | | `data.data[].url` | string | Canonical Giphy page URL. | | `data.data[].embed_url` | string | Giphy embed URL. | | `data.data[].images` | object | Slim image rendition map: `fixed_height`, `fixed_width`, `original`, `original_mp4`, `preview_gif`. Per-rendition fields: `url`, `width`, `height`, and `mp4` (only when present). | | `data.pagination` | object | Giphy pagination block: `total_count`, `count`, `offset`. | ## Example response (200) ```json { "data": { "data": [ { "id": "cFyd0Xolac5zvmHvzx", "title": "Timothee Chalamet Shimmy GIF", "alt_text": "", "rating": "g", "is_sticker": 0, "type": "gif", "url": "https://giphy.com/gifs/...-cFyd0Xolac5zvmHvzx", "embed_url": "https://giphy.com/embed/cFyd0Xolac5zvmHvzx", "images": { "fixed_height": { "url": "https://media4.giphy.com/.../200.gif", "width": "356", "height": "200", "mp4": "https://media4.giphy.com/.../200.mp4" }, "fixed_width": { "url": "https://media4.giphy.com/.../200w.gif", "width": "200", "height": "112", "mp4": "https://media4.giphy.com/.../200w.mp4" }, "original": { "url": "https://media4.giphy.com/.../giphy.gif", "width": "480", "height": "480" }, "original_mp4": { "width": "480", "height": "480", "mp4": "https://media4.giphy.com/.../giphy.mp4" }, "preview_gif": { "url": "https://media4.giphy.com/.../giphy-preview.gif", "width": "100", "height": "100" } } } ], "pagination": { "total_count": 253, "count": 1, "offset": 0 } }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Search GIFs Section: API Reference › GIFs. Page: https://api-docs.fansmetric.com/api-reference/gifs/search Searches GIFs by keyword via the OnlyFans Giphy proxy. **Endpoint:** `GET /v1/gifs/search` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_gifs_search` Searches GIFs. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `q` | query | yes | | Search query, e.g. `"hello"`. | | `limit` | query | no | | Default 20. Min 1, max 50. | | `offset` | query | no | | Pagination offset. | ## Notes Response is a slim transform of the upstream Giphy payload — only the renditions listed above are returned. Per-rendition fields are limited to `url`, `width`, `height`, and `mp4` (when present). Stop paginating when `pagination.offset + pagination.count >= pagination.total_count`. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.data[].id` | string | Giphy GIF ID — pass as `giphyId` when sending a message. | | `data.data[].title` | string | Human-readable GIF title from Giphy. | | `data.data[].alt_text` | string | Accessibility alt text. May be empty. | | `data.data[].rating` | string | Giphy content rating (e.g. `g`, `pg`, `pg-13`, `r`). | | `data.data[].is_sticker` | integer | `1` if the asset is a sticker, otherwise `0`. | | `data.data[].type` | string | Asset type — typically `gif`. | | `data.data[].url` | string | Canonical Giphy page URL. | | `data.data[].embed_url` | string | Giphy embed URL. | | `data.data[].images` | object | Slim image rendition map: `fixed_height`, `fixed_width`, `original`, `original_mp4`, `preview_gif`. Per-rendition fields: `url`, `width`, `height`, and `mp4` (only when present). | | `data.pagination` | object | Giphy pagination block: `total_count`, `count`, `offset`. | ## Example response (200) ```json { "data": { "data": [ { "id": "cFyd0Xolac5zvmHvzx", "title": "Timothee Chalamet Shimmy GIF", "alt_text": "", "rating": "g", "is_sticker": 0, "type": "gif", "url": "https://giphy.com/gifs/...-cFyd0Xolac5zvmHvzx", "embed_url": "https://giphy.com/embed/cFyd0Xolac5zvmHvzx", "images": { "fixed_height": { "url": "https://media4.giphy.com/.../200.gif", "width": "356", "height": "200", "mp4": "https://media4.giphy.com/.../200.mp4" }, "fixed_width": { "url": "https://media4.giphy.com/.../200w.gif", "width": "200", "height": "112", "mp4": "https://media4.giphy.com/.../200w.mp4" }, "original": { "url": "https://media4.giphy.com/.../giphy.gif", "width": "480", "height": "480" }, "original_mp4": { "width": "480", "height": "480", "mp4": "https://media4.giphy.com/.../giphy.mp4" }, "preview_gif": { "url": "https://media4.giphy.com/.../giphy-preview.gif", "width": "100", "height": "100" } } } ], "pagination": { "total_count": 253, "count": 1, "offset": 0 } }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Tracking Links Section: API Reference › Tracking Links. Page: https://api-docs.fansmetric.com/api-reference/tracking-links/list Relays the creator's tracking campaigns live from OnlyFans — the same payload OF's webapp renders on its Campaigns tab, wrapped in the FansMetric envelope. `GET /v1/{account_id}/campaigns` is an alias for this route: same handler, same response, under OF's own naming. For revenue, cost, tags and the `search` / `tag_ids` / `visibility` filters, call the [FansMetric-backed list](https://api-docs.fansmetric.com/api-reference/tracking-links/list-fm) instead. **Endpoint:** `GET /v1/{account_id}/tracking-links` **Base URL:** `https://public-api.fansmetric.com` **Data source:** OnlyFans live. Relayed from OnlyFans at request time — raw OF payload, no FansMetric fields. **Permission:** `api_tracking_links_list` Lists tracking campaigns straight from OnlyFans. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `limit` | query | no | | Page size. Default 100. Min 1, max 200 (values above 200 are clamped). | | `offset` | query | no | | Rows to skip. Default 0. | | `field` | query | no | | Sort and stats column. One of `created_date` (default), `subscribers_counts`, `transitions_counts`, `clicks_count`, `name`, `shared`. | | `sort` | query | no | | `desc` (default) or `asc`. | | `with_deleted` | query | no | boolean | `true` (default) includes soft-deleted campaigns; `false` returns only active ones. Matches the OF webapp's Campaigns-tab toggle. | | `sorting_deleted` | query | no | boolean | When `true`, soft-deleted campaigns are sorted to the bottom even when included. Default `false`. | | `stats` | query | no | boolean | When `true`, OF computes `countSubscribers` and `countTransitions` over the `start_date` / `end_date` window. Default `false` — leave off unless you need windowed stats. | | `start_date` | query | no | | Only forwarded when `stats=true`. Format `YYYY-MM-DD HH:MM:SS` (UTC). Default: 2 years ago. The `T` separator is normalized to a space. | | `end_date` | query | no | | Only forwarded when `stats=true`. Format `YYYY-MM-DD HH:MM:SS` (UTC). Default: end of today UTC. | ## Notes Pure passthrough — no `fm*` fields, no `revenue` / `cost` / `tags` / `links`, and no `search`, `tag_ids` or `visibility` filters. Those live on the [FansMetric-backed list](https://api-docs.fansmetric.com/api-reference/tracking-links/list-fm), which trades live freshness for FansMetric's own attribution data. Upstream OnlyFans endpoint: `GET /campaigns?with_deleted=…&sorting_deleted=…&field=…&sort=…&pagination=1` (`&stats=true&startDate=…&endDate=…` added when `stats=true`). `with_deleted` defaults to `true`. Pass `?with_deleted=false&sorting_deleted=true` to match the OF webapp's active-only view with deleted entries at the bottom. Companion endpoints powered by the same OF feed: [share-access](https://api-docs.fansmetric.com/api-reference/tracking-links/list-share-access), [claimers](https://api-docs.fansmetric.com/api-reference/tracking-links/list-claimers), [chart](https://api-docs.fansmetric.com/api-reference/tracking-links/get-chart), [overview](https://api-docs.fansmetric.com/api-reference/tracking-links/get-overview). ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[]` | array | Campaigns on this page, including soft-deleted entries when `with_deleted=true`. | | `data.list[].id` | integer | OnlyFans campaign ID. | | `data.list[].campaignName` | string | Friendly display name on OnlyFans. | | `data.list[].campaignCode` | integer | Numeric code embedded in the tracking URL (`https://onlyfans.com/{username}/c{code}`). | | `data.list[].countTransitions` | integer | Click-throughs. Scoped to the window when `stats=true`; otherwise all-time. | | `data.list[].countSubscribers` | integer | Subscribers attributed to this campaign. Scoped to the window when `stats=true`; otherwise all-time. | | `data.list[].createdAt` | string | ISO timestamp when the campaign was created. | | `data.list[].endDate` | string \| null | ISO timestamp when the campaign expires; `null` if open-ended. | | `data.list[].deletedAt` | string \| null | ISO timestamp when the campaign was soft-deleted; `null` if active. | | `data.hasMore` | boolean | Whether more pages remain. | | `_pagination.next_page` | string | Relative URL preserving query parameters with `offset` bumped. Omitted on the last page. | ## Example response (200) ```json { "data": { "list": [ { "id": 100000010, "campaignName": "Reddit — March", "campaignCode": 101, "countSubscribers": 538, "countTransitions": 1389, "createdAt": "2026-04-21T12:28:53Z", "endDate": null, "deletedAt": null } ], "hasMore": true }, "_pagination": { "next_page": "/v1/100000001/tracking-links?limit=100&offset=100" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Tracking Links Section: API Reference › Tracking Links. Page: https://api-docs.fansmetric.com/api-reference/tracking-links/list-fm Lists the account's tracking campaigns from the FansMetric database, each with revenue, cost, and tags attached. Same resource and same permission as the [OnlyFans-relayed list](https://api-docs.fansmetric.com/api-reference/tracking-links/list) — this one adds FansMetric attribution and filters, at the cost of scraper-bounded freshness (~30 min). **Endpoint:** `GET /v1/{account_id}/fm/tracking-links` **Base URL:** `https://public-api.fansmetric.com` **Data source:** FansMetric data. Served from the FansMetric database — revenue, cost, tags and extra filters, refreshed by the scraper. **Permission:** `api_tracking_links_list` Lists tracking campaigns with revenue enrichment. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `limit` | query | no | | Page size. Default 10, max 25. | | `offset` | query | no | | Rows to skip. Default 0. | | `field` | query | no | | Sort column. One of `created_date` (default), `name`, `subscribers_counts`, `transitions_counts`, `clicks_count`. | | `sort` | query | no | | `desc` (default) or `asc`. | | `with_deleted` | query | no | boolean | Include deleted campaigns. Default `true`. | | `search` | query | no | | Match campaign name or custom name (case-insensitive). | | `tag_ids` | query | no | | Comma-separated tag IDs. Returns campaigns matching any of them. | | `visibility` | query | no | | Which campaigns to return by hide state: `visible` (default), `hidden` (only hidden) or `all`. Replaces the removed `include_hidden` boolean — pass `visibility=all` for the old `include_hidden=true` behaviour. | | `start_date` | query | no | | Window start for revenue and subscriber counts. Absent → all-time. | | `end_date` | query | no | | Window end. Absent → all-time. | ## Notes Served from the FansMetric database, so rows are as fresh as the last tracking scrape (~30 min) rather than live. When you need OF's current state instead, call the [OnlyFans-relayed list](https://api-docs.fansmetric.com/api-reference/tracking-links/list). [Get Tracking Link](https://api-docs.fansmetric.com/api-reference/tracking-links/get) returns the same per-item shape. Related: [claimers](https://api-docs.fansmetric.com/api-reference/tracking-links/list-claimers), [per-link stats](https://api-docs.fansmetric.com/api-reference/tracking-links/get-stats). ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[].id` | integer | Campaign ID. | | `data.list[].campaignName` | string | Campaign name. | | `data.list[].campaignCode` | integer | Numeric code embedded in the tracking URL. | | `data.list[].campaignUrl` | string \| null | Full tracking URL. | | `data.list[].countSubscribers` | integer | Subscribers claimed in the window (or all-time when no window is given). | | `data.list[].allCountSubscribers` | integer | All-time subscribers claimed. | | `data.list[].countTransitions` | integer | Total click-throughs (all-time). | | `data.list[].createdAt` | string \| null | Creation timestamp. | | `data.list[].endDate` | string \| null | Expiry timestamp, or `null`. | | `data.list[].customName` | string \| null | Custom name for internal labelling. | | `data.list[].customSourceUrl` | string \| null | Custom traffic source URL. | | `data.list[].note` | string \| null | Free-text note. | | `data.list[].isHidden` | boolean | Whether the campaign is hidden in the UI. | | `data.list[].isRevenueShared` | boolean | Whether revenue is shared with another creator. | | `data.list[].lastScannedAt` | string \| null | When this row was last refreshed. | | `data.list[].user.username` | string | Owning creator's OnlyFans username. | | `data.list[].tags[]` | array | Tags on this campaign. Each: `{ id, name, color, created_at }`. | | `data.list[].revenue.total` | string | Net revenue attributed to this campaign. | | `data.list[].revenue.spendersCount` | integer | Distinct spenders in the window. | | `data.list[].revenue.revenuePerSubscriber` | string | Average revenue per claimed subscriber. | | `data.list[].revenue.conversionToSpender` | string | Fraction of claimed subscribers who spent. | | `data.list[].cost.perPromo` | string \| null | Promo cost you configured. | | `data.list[].cost.perSub` | string \| null | Cost per claimed subscriber. | | `data.list[].cost.profit` | string \| null | Revenue minus promo cost. | | `data.list[].cost.roi` | string \| null | Return on investment (percent). | | `data.list[].links.related.subscribers` | string | URL to fetch subscribers claimed via this campaign. | | `data.hasMore` | boolean | Whether more pages remain. | | `data.totalCount` | integer | Total matching rows across all pages. | | `_pagination.next_page` | string | URL for the next page. Omitted on the last page. | ## Example response (200) ```json { "data": { "list": [ { "id": 100000010, "campaignName": "Reddit — March", "campaignCode": 101, "campaignUrl": "https://onlyfans.com/creator_XXXXX/c101", "countSubscribers": 538, "allCountSubscribers": 612, "countTransitions": 1389, "createdAt": "2026-04-21T12:28:53Z", "endDate": null, "customName": "Reddit r/onlyfansadvice", "customSourceUrl": "https://reddit.com/r/onlyfansadvice", "note": null, "isHidden": false, "isRevenueShared": false, "lastScannedAt": "2026-08-05T04:12:00Z", "user": { "username": "creator_XXXXX" }, "tags": [ { "id": 1, "name": "Reddit", "color": "#FF5733", "created_at": "2026-01-12T09:14:22Z" } ], "revenue": { "total": "1400.25", "spendersCount": 29, "revenuePerSubscriber": "2.6026", "conversionToSpender": "0.05390" }, "cost": { "perPromo": "50.00", "perSub": "0.0929", "profit": "1350.25", "roi": "2700.5" }, "links": { "related": { "subscribers": "/v1/100000001/tracking-links/100000010/claimers" } } } ], "hasMore": true, "totalCount": 43 }, "_pagination": { "next_page": "/v1/100000001/fm/tracking-links?limit=10&offset=10" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Tracking Link Section: API Reference › Tracking Links. Page: https://api-docs.fansmetric.com/api-reference/tracking-links/get Returns a single tracking link. Served from the FansMetric database, so the shape matches an item from the [FansMetric-backed list](https://api-docs.fansmetric.com/api-reference/tracking-links/list-fm) — not the leaner OnlyFans payload the [bare list route](https://api-docs.fansmetric.com/api-reference/tracking-links/list) relays. **Endpoint:** `GET /v1/{account_id}/tracking-links/{link_id}` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_tracking_links_read` Returns a single tracking link with revenue enrichment. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `link_id` | path | yes | | Tracking link ID. | | `start_date` | query | no | | Window start for revenue and subscriber counts. Absent → all-time. | | `end_date` | query | no | | Window end. Absent → all-time. | ## Notes Date filters affect `countSubscribers`, `revenue.*`, and `cost.perSub` / `cost.roi`. `allCountSubscribers` is always all-time. For daily and monthly time-series, use [Get Tracking Link Stats](https://api-docs.fansmetric.com/api-reference/tracking-links/get-stats). ## Response fields | Field | Type | Description | | --- | --- | --- | | `data` | object | Same fields as an item in the [FansMetric-backed list](https://api-docs.fansmetric.com/api-reference/tracking-links/list-fm). | ## Example response (200) ```json { "data": { "id": 100000010, "campaignName": "Reddit — March", "campaignCode": 101, "campaignUrl": "https://onlyfans.com/creator_XXXXX/c101", "countSubscribers": 538, "allCountSubscribers": 612, "countTransitions": 1389, "createdAt": "2026-04-21T12:28:53Z", "endDate": null, "customName": "Reddit r/onlyfansadvice", "customSourceUrl": "https://reddit.com/r/onlyfansadvice", "note": null, "isHidden": false, "isRevenueShared": false, "lastScannedAt": "2026-08-05T04:12:00Z", "user": { "username": "creator_XXXXX" }, "tags": [ { "id": 1, "name": "Reddit", "color": "#FF5733", "created_at": "2026-01-12T09:14:22Z" } ], "revenue": { "total": "1400.25", "spendersCount": 29, "revenuePerSubscriber": "2.6026", "conversionToSpender": "0.05390" }, "cost": { "perPromo": "50.00", "perSub": "0.0929", "profit": "1350.25", "roi": "2700.5" }, "links": { "related": { "subscribers": "/v1/100000001/tracking-links/100000010/claimers" } } }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Create Tracking Link Section: API Reference › Tracking Links. Page: https://api-docs.fansmetric.com/api-reference/tracking-links/create Creates a tracking link on OnlyFans and stores it in the FansMetric database. **Endpoint:** `POST /v1/{account_id}/tracking-links` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_tracking_links_create` Creates a tracking link. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `name` | body | yes | | Campaign name. | | `tag_ids` | body | no | | FansMetric tag IDs to assign. | | `custom_source_url` | body | no | | Custom source URL for traffic tracking. | ## Request body example ```json { "name": "My Campaign", "tag_ids": [1, 2], "custom_source_url": "https://reddit.com/r/example" } ``` ## Notes **Breaking change:** the 201 body is now the same item shape as [Get Tracking Link](https://api-docs.fansmetric.com/api-reference/tracking-links/get) — one canonical camelCase object with nested `revenue` / `cost` / `tags` / `links`. It previously returned the raw OnlyFans object plus `fmTags`, `fmCustomSourceUrl` and `fmTrackingLinkUrl`; those keys are gone. A brand-new campaign has no claims, clicks or attributed revenue, so every metric is zero and `cost` is all-`null` by definition. Tag resolution is best-effort: if the post-write tag-map fetch fails, `tags` returns `[]` rather than failing the create. Cross-org tag IDs are silently filtered out — pass an ID that isn't in your org and it won't appear. The new campaign shows up in the [live relay list](https://api-docs.fansmetric.com/api-reference/tracking-links/list) immediately, and in the [FansMetric list](https://api-docs.fansmetric.com/api-reference/tracking-links/list-fm) after the next scraper pass (~30 min). ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.id` | integer | Newly created OnlyFans campaign ID. | | `data.campaignName` | string | Campaign name as stored on OnlyFans. | | `data.campaignCode` | integer | Numeric code used in the tracking link URL. | | `data.campaignUrl` | string \| null | Full public tracking-link URL (`https://onlyfans.com/{username}/c{campaignCode}`). `null` if the username or code could not be resolved. | | `data.countSubscribers` | integer | Always `0` on creation. | | `data.allCountSubscribers` | integer | Always `0` on creation. | | `data.countTransitions` | integer | Always `0` on creation. | | `data.createdAt` | string \| null | Creation timestamp (RFC 3339). | | `data.endDate` | string \| null | `null` while the campaign is active; set when it is deleted. | | `data.customName` | string \| null | FansMetric display-name override. `null` on creation — set it via [Update Tracking Link](https://api-docs.fansmetric.com/api-reference/tracking-links/update). | | `data.customSourceUrl` | string \| null | Traffic-source URL stored in FansMetric (the value submitted in `custom_source_url`). | | `data.note` | string \| null | Free-text note. `null` on creation. | | `data.isHidden` | boolean | FansMetric hide flag. `false` on creation. | | `data.isRevenueShared` | boolean | Whether an enabled share exposes revenue. `false` on creation. | | `data.lastScannedAt` | string \| null | When the scraper last refreshed this link. `null` until the first pass. | | `data.user.username` | string | Creator username. Empty string if it could not be resolved. | | `data.tags[]` | array | Full tag objects for the IDs passed in `tag_ids`. Each element has `id`, `name`, `color`, `created_at` — same shape as `GET /v1/tags`. Resolution is best-effort: if the post-write tag-map fetch fails, `tags` is `[]` rather than failing the create. Tags belonging to a different org are silently filtered out, so a submitted ID may not appear. | | `data.revenue.total` | string | `"0.00"` on creation. | | `data.revenue.spendersCount` | integer | `0` on creation. | | `data.revenue.revenuePerSubscriber` | string | `"0"` on creation. | | `data.revenue.conversionToSpender` | string | `"0"` on creation. | | `data.cost` | object | `perPromo`, `perSub`, `profit`, `roi` — all `null` until a promo cost is set, which is how you tell "not set" from zero. | | `data.links.related.subscribers` | string | Path to this link's claimers. | ## Example response (201) ```json { "data": { "id": 100000011, "campaignName": "My Campaign", "campaignCode": 102, "campaignUrl": "https://onlyfans.com/creator_XXXXX/c102", "countSubscribers": 0, "allCountSubscribers": 0, "countTransitions": 0, "createdAt": "2026-05-15T10:00:00Z", "endDate": null, "customName": null, "customSourceUrl": "https://reddit.com/r/example", "note": null, "isHidden": false, "isRevenueShared": false, "lastScannedAt": null, "user": { "username": "creator_XXXXX" }, "tags": [ { "id": 1, "name": "Reddit", "color": "#FF5733", "created_at": "2026-01-12T09:14:22Z" }, { "id": 2, "name": "Twitter", "color": "#1DA1F2", "created_at": "2026-01-12T09:15:01Z" } ], "revenue": { "total": "0.00", "spendersCount": 0, "revenuePerSubscriber": "0", "conversionToSpender": "0" }, "cost": { "perPromo": null, "perSub": null, "profit": null, "roi": null }, "links": { "related": { "subscribers": "/v1/100000001/tracking-links/100000011/claimers" } } }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Delete Tracking Link Section: API Reference › Tracking Links. Page: https://api-docs.fansmetric.com/api-reference/tracking-links/delete Deletes a tracking link on OnlyFans. Sets `end_date` in the FansMetric database. **Endpoint:** `DELETE /v1/{account_id}/tracking-links/{link_id}` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_tracking_links_delete` Deletes a tracking link. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `link_id` | path | yes | | Tracking link platform ID. | ## Notes ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.success` | boolean | Always `true` on a successful delete. | ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Tracking Link Stats Section: API Reference › Tracking Links. Page: https://api-docs.fansmetric.com/api-reference/tracking-links/get-stats Returns cumulative totals plus daily and monthly time-series for a single tracking link. **Endpoint:** `GET /v1/{account_id}/tracking-links/{link_id}/stats` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_tracking_links_read` Returns summary + daily + monthly metrics for one tracking link. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `link_id` | path | yes | | Tracking link ID. | | `date_start` | query | no | | Window start (UTC). Absent → unbounded. | | `date_end` | query | no | | Window end (UTC). Absent → unbounded. | ## Notes **Breaking change:** `summary.clicks_total` and the per-bucket `clicks` field have been removed. There was never per-day click data; lifetime clicks are `countTransitions` on the [list](https://api-docs.fansmetric.com/api-reference/tracking-links/list-fm) and [get](https://api-docs.fansmetric.com/api-reference/tracking-links/get) endpoints. **Added:** `cumulative_subs_total`, `cumulative_revenue_total`, and per-bucket `cumulative_subs` / `cumulative_revenue`. Bucket values (`subs`, `revenue`, `spenders`) are incremental; `cumulative_subs` and `cumulative_revenue` are running totals since the link's first activity. The first returned bucket's `cumulative_revenue` can therefore exceed its own `revenue`, because it includes pre-window activity. `summary.subs_total` / `revenue_total` / `spenders_total` respect the requested window exactly. The `cumulative_*_total` pair runs from the link's inception to `date_end` and ignores `date_start` — a running total restarted at the window edge would not be a cumulative. Buckets are sliced on whole boundaries: a `date_start` in the middle of a day returns that entire day's bucket value, not a partial one. On an unwindowed call `subs_total == cumulative_subs_total`, `revenue_total == cumulative_revenue_total`, and the last daily bucket's `cumulative_revenue` equals `cumulative_revenue_total` — useful as a sanity check. Buckets are UTC day/month boundaries and sparse: only buckets with activity are emitted, with no zero-filling. The FansMetric web app buckets in the viewer's timezone and zero-fills empty days, so cross-checking against the web app across a timezone boundary can appear to shift by a day. Bucket coverage is bounded by sync history — claims and transactions older than the connection's first sync do not appear. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.summary.subs_total` | integer | Subscribers claimed inside the requested window. | | `data.summary.cumulative_subs_total` | integer | Subscribers claimed since the link's inception, up to `date_end`. Ignores `date_start`. | | `data.summary.revenue_total` | string | Net attributed revenue inside the window. | | `data.summary.cumulative_revenue_total` | string | Net attributed revenue since inception, up to `date_end`. Ignores `date_start`. | | `data.summary.spenders_total` | integer | Distinct spenders inside the window. | | `data.summary.last_scanned_at` | string \| null | When this link was last refreshed by the scraper. | | `data.daily_metrics[]` | array | Per-day buckets, UTC, sparse — only days with activity are emitted (no zero-filling). | | `data.daily_metrics[].timestamp` | string | Bucket start (`YYYY-MM-DD`, midnight UTC). | | `data.daily_metrics[].subs` | integer | Subscribers claimed in the bucket. Incremental. | | `data.daily_metrics[].cumulative_subs` | integer | Running total of claims from the link's first activity through this bucket — not from the window start. | | `data.daily_metrics[].revenue` | string | Net revenue in the bucket. Incremental. | | `data.daily_metrics[].cumulative_revenue` | string | Running total of revenue from the link's first activity through this bucket. | | `data.daily_metrics[].spenders` | integer | Distinct spenders in the bucket. | | `data.monthly_metrics[]` | array | Per-month buckets. Same shape as `daily_metrics[]`, aligned to the 1st of the month UTC. | ## Example response (200) ```json { "data": { "summary": { "subs_total": 612, "cumulative_subs_total": 612, "revenue_total": "1400.25", "cumulative_revenue_total": "1400.25", "spenders_total": 29, "last_scanned_at": "2026-08-05T04:12:00Z" }, "daily_metrics": [ { "timestamp": "2026-07-31", "subs": 8, "cumulative_subs": 559, "revenue": "24.90", "cumulative_revenue": "1211.15", "spenders": 1 }, { "timestamp": "2026-08-01", "subs": 11, "cumulative_subs": 570, "revenue": "38.20", "cumulative_revenue": "1249.35", "spenders": 2 }, { "timestamp": "2026-08-02", "subs": 9, "cumulative_subs": 579, "revenue": "15.00", "cumulative_revenue": "1264.35", "spenders": 1 } ], "monthly_metrics": [ { "timestamp": "2026-07-01", "subs": 187, "cumulative_subs": 559, "revenue": "465.10", "cumulative_revenue": "1250.05", "spenders": 12 }, { "timestamp": "2026-08-01", "subs": 53, "cumulative_subs": 612, "revenue": "150.20", "cumulative_revenue": "1400.25", "spenders": 5 } ] }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Update Tracking Link Section: API Reference › Tracking Links. Page: https://api-docs.fansmetric.com/api-reference/tracking-links/update Partially updates FansMetric metadata on a tracking link — hide state, note, custom name, source URL and promo cost. **Endpoint:** `PATCH /v1/{account_id}/tracking-links/{link_id}` **Base URL:** `https://public-api.fansmetric.com` **Data source:** FansMetric data. Served from the FansMetric database — revenue, cost, tags and extra filters, refreshed by the scraper. **Permission:** `api_tracking_links_update` Updates FansMetric metadata on a tracking link. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `link_id` | path | yes | | Tracking link platform ID. | | `custom_name` | body | no | | FansMetric display-name override. Max 64 characters. Send `null` to clear. | | `note` | body | no | | Free-text note. Max 2000 characters. Send `null` to clear. | | `custom_source_url` | body | no | | Traffic-source URL. Max 2048 characters, must be an `http`/`https` URL with a host and no whitespace. Send `null` to clear. | | `promo_cost` | body | no | | Promo cost, between 0 and 99999. Send `null` to clear. | | `is_hidden` | body | no | | FansMetric hide flag (the eye toggle). Boolean — **not** nullable; `null` returns 400. | ## Request body example ```json { "note": null } ``` ## Notes **Merge-patch semantics.** A key absent from the body is left untouched; a key sent as explicit `null` clears the column to SQL `NULL`; a key sent with a value is validated and set. The one exception is `is_hidden`, which is non-nullable — sending `null` returns 400. The sample body above sends only `{"note": null}`: it clears the note and leaves `custom_name`, `custom_source_url`, `promo_cost` and `is_hidden` exactly as they were. An empty body (`{}`) returns 400 — send at least one of the five fields. An unknown field name also returns 400 rather than being ignored, so typos surface immediately instead of silently doing nothing. Writes FansMetric's own fields only — this endpoint never calls OnlyFans. The campaign name on OnlyFans is not editable through it; set `custom_name` for a FansMetric-side rename. `custom_source_url` is validated here even though the FansMetric web app historically accepted anything — a `javascript:` URL is rejected with 400. The response is the full updated item, identical in shape to [Get Tracking Link](https://api-docs.fansmetric.com/api-reference/tracking-links/get), with all-time metrics (no date window is applied). ## Response fields | Field | Type | Description | | --- | --- | --- | | `data` | object | The full updated tracking link, same shape as [Get Tracking Link](https://api-docs.fansmetric.com/api-reference/tracking-links/get). | ## Example response (200) ```json { "data": { "id": 100000010, "campaignName": "Reddit Push", "campaignCode": 101, "campaignUrl": "https://onlyfans.com/creator_XXXXX/c101", "countSubscribers": 538, "allCountSubscribers": 538, "countTransitions": 1389, "createdAt": "2026-04-21T12:28:53Z", "endDate": null, "customName": "Reddit — r/example", "customSourceUrl": "https://reddit.com/r/example", "note": null, "isHidden": false, "isRevenueShared": false, "lastScannedAt": "2026-08-31T09:12:04Z", "user": { "username": "creator_XXXXX" }, "tags": [ { "id": 1, "name": "Reddit", "color": "#FF5733", "created_at": "2026-01-12T09:14:22Z" } ], "revenue": { "total": "1400.25", "spendersCount": 29, "revenuePerSubscriber": "2.6026951672862454", "conversionToSpender": "0.05390334572490706" }, "cost": { "perPromo": "250.00", "perSub": "0.46468401486988845", "profit": "1150.25", "roi": "460.1" }, "links": { "related": { "subscribers": "/v1/100000001/tracking-links/100000010/claimers" } } }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Tracking Link Claimers Section: API Reference › Tracking Links. Page: https://api-docs.fansmetric.com/api-reference/tracking-links/list-claimers Returns the subscribers who joined via a specific tracking campaign. Same per-user shape as entries in [List Subscribers](https://api-docs.fansmetric.com/api-reference/subscribers/list-subscribers). **Endpoint:** `GET /v1/{account_id}/tracking-links/{tracking_link_id}/claimers` **Base URL:** `https://public-api.fansmetric.com` **Data source:** OnlyFans live. Relayed from OnlyFans at request time — raw OF payload, no FansMetric fields. **Permission:** `api_tracking_links_list_claimers` Lists subscribers who claimed a specific tracking campaign. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `tracking_link_id` | path | yes | | OnlyFans campaign ID — the `id` field returned by [List Tracking Links](https://api-docs.fansmetric.com/api-reference/tracking-links/list). | | `limit` | query | no | | Page size. Default 10. Min 1, max 100. | | `offset` | query | no | | Rows to skip. Default 0. The server derives OF's `more` flag (false on `offset=0`, true otherwise) automatically. | ## Notes Upstream OnlyFans endpoint: `GET /campaigns/{id}/claimers?more=…&limit=…&offset=…`. The trial-link mirror is the [OnlyFans-relayed trial claimers list](https://api-docs.fansmetric.com/api-reference/trial-links/list-subscribers). This page shares its title with the [FansMetric-attributed claimers list](https://api-docs.fansmetric.com/api-reference/tracking-links/list-claimers-fm); the **OF** and **FM** badges are what tell them apart, as with the two tracking-link lists. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[]` | array | Full OF user objects for each claimer — same shape as `/subscribers`. | | `data.hasMore` | boolean | Whether more pages remain. | ## Example response (200) ```json { "data": { "list": [ { "id": 555000001, "username": "fan_one", "name": "Fan One", "subscribePrice": 9.99, "subscribedOnData": { "date": "2026-05-20T00:00:00Z" } } ], "hasMore": false }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Tracking Link Claimers Section: API Reference › Tracking Links. Page: https://api-docs.fansmetric.com/api-reference/tracking-links/list-claimers-fm The fans who claimed a tracking link, with FansMetric revenue attribution. **Endpoint:** `GET /v1/{account_id}/fm/tracking-links/{link_id}/claimers` **Base URL:** `https://public-api.fansmetric.com` **Data source:** FansMetric data. Served from the FansMetric database — revenue, cost, tags and extra filters, refreshed by the scraper. **Permission:** `api_tracking_links_list_claimers` Lists FM-attributed claimers of a tracking link. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `link_id` | path | yes | | Tracking link platform ID. | | `limit` | query | no | | Results per page. Default 50, clamped to 1–100. | | `offset` | query | no | | Results to skip. Default 0. | | `field` | query | no | | Sort column: `revenue` (default), `claimed_at`, `lifetime_revenue` or `lifetime_revenue_since_claim`. Anything else returns 400. | | `sort` | query | no | | `asc` or `desc`. Default `desc`. | | `date_start` | query | no | | Window start (UTC). What it filters depends on `claimed_in_range`. | | `date_end` | query | no | | Window end (UTC). What it filters depends on `claimed_in_range`. | | `claimed_in_range` | query | no | boolean | Default `false`: the window filters transaction dates (revenue is windowed) and zero-revenue claimers are hidden. Set `true` to window claim dates instead and include zero-revenue claimers. | ## Notes FansMetric's own attribution, not an OnlyFans relay — this is the data behind the web app's Claims modal. This page and the [OnlyFans-relayed claimers list](https://api-docs.fansmetric.com/api-reference/tracking-links/list-claimers) share a title and are told apart by the badge, the same way the two tracking-link lists are. **Each money field has its own scope.** `revenue` and `raw_revenue` are **net** and limited to this account's connections. `lifetime_revenue` and `lifetime_revenue_since_claim` are **net** across every connection in your organisation — the web app's "across all creators in your agency" columns. `raw_revenue` vs `revenue`: when one fan claims several links in the same instant, `revenue` divides the transaction between those links while `raw_revenue` does not. A fan whose `raw_revenue` is double their `revenue` claimed two links simultaneously. Transactions with status `undo` are excluded from all four money fields. `hasMore` is `true` whenever the page came back full, so a final page of exactly `limit` rows reports `hasMore: true` and the following request returns an empty list. There is no `totalCount` on this endpoint. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[].id` | integer | The fan's OnlyFans user ID. | | `data.list[].username` | string \| null | OnlyFans username. | | `data.list[].name` | string \| null | Display name. | | `data.list[].avatar_url` | string \| null | Avatar URL. | | `data.list[].claimed_at` | string | When they claimed this link (RFC 3339). | | `data.list[].revenue` | string | Net revenue attributed to **this link**. When the fan claimed several links at the same instant, the transaction is split evenly between them. | | `data.list[].raw_revenue` | string | The same sum **without** the split applied — useful for reconciling against a single link in isolation. | | `data.list[].lifetime_revenue` | string | The fan's total net revenue across **all connections in your organisation** — every creator in the agency — all time. | | `data.list[].lifetime_revenue_since_claim` | string | Same, counting only from their claim onward. | | `data.hasMore` | boolean | `true` when the page came back full. | ## Example response (200) ```json { "data": { "list": [ { "id": 100000501, "username": "fan_one", "name": "Fan One", "avatar_url": "https://cdn.example/avatar.jpg", "claimed_at": "2026-07-01T10:00:00Z", "revenue": "100.00", "raw_revenue": "100.00", "lifetime_revenue": "150.00", "lifetime_revenue_since_claim": "100.00" }, { "id": 100000502, "username": "fan_casual", "name": null, "avatar_url": null, "claimed_at": "2026-07-03T08:00:00Z", "revenue": "40.00", "raw_revenue": "80.00", "lifetime_revenue": "80.00", "lifetime_revenue_since_claim": "80.00" } ], "hasMore": false }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Tracking Links Chart Section: API Reference › Tracking Links. Page: https://api-docs.fansmetric.com/api-reference/tracking-links/get-chart Returns the daily clicks + claims timeseries that backs the line graph on OF's Campaigns tab. Passthrough — the upstream payload is returned verbatim inside `data`. Campaigns and tracking links are the same resource; this one keeps OF's naming in the path (`/campaigns/chart`). **Endpoint:** `GET /v1/{account_id}/campaigns/chart` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_campaigns_read_chart` Daily clicks / claims timeseries across all campaigns. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `start_date` | query | no | | Window start. `YYYY-MM-DD HH:MM:SS` UTC (the `T` separator is accepted and normalized). Default: 2 years ago. | | `end_date` | query | no | | Window end. Same format as `start_date`. Default: end of today UTC. | ## Notes Upstream OnlyFans endpoint: `GET /campaigns/chart?filter[clicks]=clicks&filter[claims]=claims&startDate=…&endDate=…`. Returns the same shape OF's webapp consumes — no FansMetric transformations applied. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.clicks[]` | array | Daily click counts. Each entry is `{ date, count }`. | | `data.claims[]` | array | Daily claim counts. Each entry is `{ date, count }`. | ## Example response (200) ```json { "data": { "clicks": [ { "date": "2026-06-01", "count": 42 }, { "date": "2026-06-02", "count": 35 } ], "claims": [ { "date": "2026-06-01", "count": 3 }, { "date": "2026-06-02", "count": 4 } ] }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Tracking Links Overview Section: API Reference › Tracking Links. Page: https://api-docs.fansmetric.com/api-reference/tracking-links/get-overview Returns the campaign-scoped summary card on OF's Campaigns tab — total count / claims / clicks with windowed deltas plus a small chart. Backed by the same OF endpoint as `/earnings/overview`, with `by=campaign` carved out as a dedicated route. Like the [chart](https://api-docs.fansmetric.com/api-reference/tracking-links/get-chart), it keeps OF's naming in the path (`/campaigns/overview`). **Endpoint:** `GET /v1/{account_id}/campaigns/overview` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_campaigns_read_overview` Headline counts and deltas for the campaign window. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `start_date` | query | no | | Window start. `YYYY-MM-DD HH:MM:SS` UTC. Default: 2 years ago. | | `end_date` | query | no | | Window end. Same format. Default: end of today UTC. | ## Notes Upstream OnlyFans endpoint: `GET /users/me/stats/overview?by=campaign&startDate=…&endDate=…`. Pair with [Get Tracking Links Chart](https://api-docs.fansmetric.com/api-reference/tracking-links/get-chart) for the full timeseries. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.campaigns.hasStatistic` | boolean | Whether OF has computed stats for this account. | | `data.campaigns.count` | object | `{ total, delta }` — total campaigns and change vs. previous window. | | `data.campaigns.claims` | object | `{ total, delta }` — claims across all campaigns. | | `data.campaigns.clicks` | object | `{ total, delta }` — clicks across all campaigns. | | `data.campaigns.chartData[]` | array | Sparkline data. Each entry is `{ date, count }`. | ## Example response (200) ```json { "data": { "campaigns": { "hasStatistic": true, "count": { "total": 12, "delta": 2 }, "claims": { "total": 178, "delta": 23 }, "clicks": { "total": 4502, "delta": 312 }, "chartData": [ { "date": "2026-06-01", "count": 3 }, { "date": "2026-06-02", "count": 4 } ] } }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Tracking Link Shares Section: API Reference › Tracking Links. Page: https://api-docs.fansmetric.com/api-reference/tracking-links/list-shares Lists the public stats-share links created for a tracking link. **Endpoint:** `GET /v1/{account_id}/tracking-links/{link_id}/shares` **Base URL:** `https://public-api.fansmetric.com` **Data source:** FansMetric data. Served from the FansMetric database — revenue, cost, tags and extra filters, refreshed by the scraper. **Permission:** `api_tracking_links_list_shares` Lists share links for a tracking link. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `link_id` | path | yes | | Tracking Link platform ID. | ## Notes Returns up to 100 shares, newest first. There is no pagination on this endpoint. The `url` origin depends on which FansMetric deployment served the request (`https://app.fansmetric.com`, `https://app.staging.fansmetric.com` or `https://app.buffmetrics.com`). Use the returned `url` rather than assembling it from the `id` yourself. The share row's UUID **is** the public token — anyone holding the URL can view the page without authenticating. Treat it like a secret link. `is_enabled` exists in the underlying schema but is dead — nothing reads it — so it is not exposed here. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[].id` | string | Share UUID. This is also the public token in the URL. | | `data.list[].name` | string \| null | Optional label for your own reference. Max 128 characters. | | `data.list[].is_revenue_shared` | boolean | Whether the public page shows revenue figures. | | `data.list[].url` | string | The ready-to-send public page URL (`{app-origin}/share/{id}`). | | `data.list[].created_at` | string | Creation timestamp (RFC 3339). | | `data.list[].updated_at` | string | Last-update timestamp (RFC 3339). | ## Example response (200) ```json { "data": { "list": [ { "id": "6f1c2d9e-4a7b-4c31-9f80-2b5e7a91c3d4", "name": "reddit push", "is_revenue_shared": true, "url": "https://app.fansmetric.com/share/6f1c2d9e-4a7b-4c31-9f80-2b5e7a91c3d4", "created_at": "2026-08-31T10:00:00Z", "updated_at": "2026-08-31T10:00:00Z" } ] }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Create Tracking Link Share Section: API Reference › Tracking Links. Page: https://api-docs.fansmetric.com/api-reference/tracking-links/create-share Creates a public stats-share link for a tracking link and returns its ready-to-send URL. **Endpoint:** `POST /v1/{account_id}/tracking-links/{link_id}/shares` **Base URL:** `https://public-api.fansmetric.com` **Data source:** FansMetric data. Served from the FansMetric database — revenue, cost, tags and extra filters, refreshed by the scraper. **Permission:** `api_tracking_links_create_share` Creates a share link for a tracking link. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `link_id` | path | yes | | Tracking Link platform ID. | | `name` | body | no | | Optional label for your own reference. Max 128 characters. Default `null`. | | `is_revenue_shared` | body | no | | Whether the public page shows revenue. Default `false`. | ## Request body example ```json { "name": "reddit push", "is_revenue_shared": true } ``` ## Notes An empty body (`{}`) is valid and creates a share with the defaults (`name: null`, `is_revenue_shared: false`). The `url` origin depends on which FansMetric deployment served the request (`https://app.fansmetric.com`, `https://app.staging.fansmetric.com` or `https://app.buffmetrics.com`). Use the returned `url` rather than assembling it from the `id` yourself. The share row's UUID **is** the public token — anyone holding the URL can view the page without authenticating. Treat it like a secret link. Each call mints a **new** share with a new UUID — there is no upsert. Creating three shares for one link gives you three independent URLs, which is the intended way to hand different recipients revocable links. Creating a share for a tracking link also sets the organisation's "has shared a tracking link" onboarding flag, matching the web app. That side effect is best-effort — if it fails the share is still created. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.id` | string | Share UUID. This is also the public token in the URL. | | `data.name` | string \| null | Optional label for your own reference. Max 128 characters. | | `data.is_revenue_shared` | boolean | Whether the public page shows revenue figures. | | `data.url` | string | The ready-to-send public page URL (`{app-origin}/share/{id}`). | | `data.created_at` | string | Creation timestamp (RFC 3339). | | `data.updated_at` | string | Last-update timestamp (RFC 3339). | ## Example response (201) ```json { "data": { "id": "6f1c2d9e-4a7b-4c31-9f80-2b5e7a91c3d4", "name": "reddit push", "is_revenue_shared": true, "url": "https://app.fansmetric.com/share/6f1c2d9e-4a7b-4c31-9f80-2b5e7a91c3d4", "created_at": "2026-08-31T10:00:00Z", "updated_at": "2026-08-31T10:00:00Z" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Update Tracking Link Share Section: API Reference › Tracking Links. Page: https://api-docs.fansmetric.com/api-reference/tracking-links/update-share Partially updates a tracking link share — its label and whether the public page shows revenue. **Endpoint:** `PATCH /v1/{account_id}/tracking-links/{link_id}/shares/{share_id}` **Base URL:** `https://public-api.fansmetric.com` **Data source:** FansMetric data. Served from the FansMetric database — revenue, cost, tags and extra filters, refreshed by the scraper. **Permission:** `api_tracking_links_update_share` Updates a share link. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `link_id` | path | yes | | Tracking Link platform ID. | | `share_id` | path | yes | | Share UUID. | | `name` | body | no | | Label. Max 128 characters. Send `null` to clear. | | `is_revenue_shared` | body | no | | Whether the public page shows revenue. Boolean. | ## Request body example ```json { "is_revenue_shared": false } ``` ## Notes Merge-patch, same rules as the link PATCH: an absent key is left untouched, `name: null` clears the label, and a value is validated and set. An empty body or an unknown field returns 400. Toggling `is_revenue_shared` takes effect on the existing URL — the token does not change, so a link already sent out will start or stop showing revenue. A `share_id` that is not a well-formed UUID simply matches nothing and returns 404 rather than erroring. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.id` | string | Share UUID. This is also the public token in the URL. | | `data.name` | string \| null | Optional label for your own reference. Max 128 characters. | | `data.is_revenue_shared` | boolean | Whether the public page shows revenue figures. | | `data.url` | string | The ready-to-send public page URL (`{app-origin}/share/{id}`). | | `data.created_at` | string | Creation timestamp (RFC 3339). | | `data.updated_at` | string | Last-update timestamp (RFC 3339). | ## Example response (200) ```json { "data": { "id": "6f1c2d9e-4a7b-4c31-9f80-2b5e7a91c3d4", "name": "reddit push", "is_revenue_shared": false, "url": "https://app.fansmetric.com/share/6f1c2d9e-4a7b-4c31-9f80-2b5e7a91c3d4", "created_at": "2026-08-31T10:00:00Z", "updated_at": "2026-08-31T11:30:00Z" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Delete Tracking Link Share Section: API Reference › Tracking Links. Page: https://api-docs.fansmetric.com/api-reference/tracking-links/delete-share Permanently deletes a tracking link share, immediately breaking its public URL. **Endpoint:** `DELETE /v1/{account_id}/tracking-links/{link_id}/shares/{share_id}` **Base URL:** `https://public-api.fansmetric.com` **Data source:** FansMetric data. Served from the FansMetric database — revenue, cost, tags and extra filters, refreshed by the scraper. **Permission:** `api_tracking_links_delete_share` Deletes a share link. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `link_id` | path | yes | | Tracking Link platform ID. | | `share_id` | path | yes | | Share UUID. | ## Notes **Hard delete.** The row is removed, the public page 404s immediately, and the token cannot be revived. There is no disable — recreate the share to get a new URL. Deleting an already-deleted or unknown share returns 404. If you only want to stop exposing revenue, PATCH `is_revenue_shared` to `false` instead and keep the URL working. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.success` | boolean | Always `true` on a successful delete. | ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Shared Tracking Links Section: API Reference › Tracking Links. Page: https://api-docs.fansmetric.com/api-reference/tracking-links/list-share-access Returns tracking campaigns from other creators that this account has been granted share-access to. Read-only mirror of [List Tracking Links](https://api-docs.fansmetric.com/api-reference/tracking-links/list); items here are owned upstream and cannot be edited from this account. **Endpoint:** `GET /v1/{account_id}/tracking-links/share-access` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_tracking_links_list_share_access` Lists tracking campaigns shared with this account by other creators. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `limit` | query | no | | Page size. Default 10. Min 1, max 200. | | `offset` | query | no | | Rows to skip. Default 0. | | `field` | query | no | | Sort column. Same allowlist as [List Tracking Links](https://api-docs.fansmetric.com/api-reference/tracking-links/list): `created_date`, `subscribers_counts`, `transitions_counts`, `clicks_count`, `name`, `shared`. Default `created_date`. | | `sort` | query | no | | `desc` (default) or `asc`. | | `with_deleted` | query | no | boolean | `true` (default) includes soft-deleted shares; `false` returns only active ones. | | `sorting_deleted` | query | no | boolean | When `true`, soft-deleted shares are sorted to the bottom. Default `false`. | | `stats` | query | no | boolean | When `true`, OF computes windowed `countSubscribers` / `countTransitions`. Default `false`. | | `start_date` | query | no | | Only forwarded when `stats=true`. `YYYY-MM-DD HH:MM:SS` UTC. Default: 2 years ago. | | `end_date` | query | no | | Only forwarded when `stats=true`. Default: end of today UTC. | ## Notes Upstream OnlyFans endpoint: `GET /campaigns/share-access?…`. Items here cannot be edited via [Delete Tracking Link](https://api-docs.fansmetric.com/api-reference/tracking-links/delete) — they're owned by the granting creator. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[]` | array | Shared campaigns on this page. Same per-item shape as [List Tracking Links](https://api-docs.fansmetric.com/api-reference/tracking-links/list). | | `data.hasMore` | boolean | Whether more pages remain. | ## Example response (200) ```json { "data": { "list": [ { "id": 100000099, "campaignName": "Partner Promo", "campaignCode": "partner-99", "countSubscribers": 14, "countTransitions": 88, "createdAt": "2026-05-12T08:00:00Z", "endDate": null, "deletedAt": null } ], "hasMore": false }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Trial Links Section: API Reference › Trial Links. Page: https://api-docs.fansmetric.com/api-reference/trial-links/list Relays the creator's trial links live from OnlyFans — the same payload OF's webapp renders on its Trials tab, wrapped in the FansMetric envelope. For revenue, cost, tags and the `search` / `tag_ids` / `visibility` / `status` filters, call the [FansMetric-backed list](https://api-docs.fansmetric.com/api-reference/trial-links/list-fm) instead. **Endpoint:** `GET /v1/{account_id}/trial-links` **Base URL:** `https://public-api.fansmetric.com` **Data source:** OnlyFans live. Relayed from OnlyFans at request time — raw OF payload, no FansMetric fields. **Permission:** `api_trial_links_list` Lists trial links straight from OnlyFans. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `limit` | query | no | | Page size. Default 10. Min 1, max 200 (values above 200 are clamped). | | `offset` | query | no | | Rows to skip. Default 0. | | `field` | query | no | | Sort column. One of `create_date` (default — note the missing `d`, this matches OF), `expire_date`, `claims_count`, `clicks_count`, `subscribe_counts`, `subscribe_days`, `shared`. | | `sort` | query | no | | `desc` (default) or `asc`. | ## Notes Pure passthrough — no `fm*` fields, no `revenue` / `cost` / `tags` / `links`, and no `search`, `tag_ids`, `visibility`, `status` or `start_date` / `end_date` filters. Those live on the [FansMetric-backed list](https://api-docs.fansmetric.com/api-reference/trial-links/list-fm), which trades live freshness for FansMetric's own attribution data. Upstream OnlyFans endpoint: `GET /trials?limit=…&offset=…&pagination=1&sort=…&field=…`. Watch the `field` allowlist — OF uses `create_date` (not `created_date`). Passing `created_date` returns a `400` from this endpoint. Companion endpoints powered by the same OF feed: [share-access](https://api-docs.fansmetric.com/api-reference/trial-links/list-share-access), [claimers](https://api-docs.fansmetric.com/api-reference/trial-links/list-subscribers), [chart](https://api-docs.fansmetric.com/api-reference/trial-links/get-chart), [overview](https://api-docs.fansmetric.com/api-reference/trial-links/get-overview), [stats](https://api-docs.fansmetric.com/api-reference/trial-links/list-stats). ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[].id` | integer | OnlyFans trial link ID. | | `data.list[].trialLinkName` | string | Trial link name on OnlyFans. | | `data.list[].url` | string | Full ready-to-share trial link URL. | | `data.list[].subscribeDays` | integer | Trial duration in days. | | `data.list[].subscribeCounts` | integer | Subscriber limit (0 = unlimited). | | `data.list[].claimCounts` | integer | All-time claim count. | | `data.list[].clicksCounts` | integer | All-time click count. | | `data.list[].isFinished` | boolean | Whether the trial has expired or been deleted. | | `data.list[].createdAt` | string | Creation timestamp (RFC 3339). | | `data.list[].expiredAt` | string \| null | Expiration timestamp (RFC 3339). `null` if no expiry. | | `data.list[].user` | object | OF user object for the owning creator. | | `data.list[].sharedWith` | array | Other creators this trial has been shared with (may be empty). | | `data.hasMore` | boolean | Whether more pages remain. | | `_pagination.next_page` | string | Relative URL preserving query params with `offset` bumped. Omitted on the last page. | ## Example response (200) ```json { "data": { "list": [ { "id": 100000020, "trialLinkName": "1 MONTH FREE TRIAL", "url": "https://onlyfans.com/creator_XXXXX/trial/XXXXXXXXXXXXXXXXXXXXXXXXX", "subscribeDays": 30, "subscribeCounts": 0, "claimCounts": 37, "clicksCounts": 412, "isFinished": false, "createdAt": "2026-04-05T17:02:51Z", "expiredAt": null, "user": { "id": 100000001, "username": "creator_XXXXX" }, "sharedWith": [] } ], "hasMore": false }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Trial Links Section: API Reference › Trial Links. Page: https://api-docs.fansmetric.com/api-reference/trial-links/list-fm Lists the account's trial links from the FansMetric database, each with revenue, cost, and tags attached. Same resource and same permission as the [OnlyFans-relayed list](https://api-docs.fansmetric.com/api-reference/trial-links/list) — this one adds FansMetric attribution and filters, at the cost of scraper-bounded freshness (~2 h). **Endpoint:** `GET /v1/{account_id}/fm/trial-links` **Base URL:** `https://public-api.fansmetric.com` **Data source:** FansMetric data. Served from the FansMetric database — revenue, cost, tags and extra filters, refreshed by the scraper. **Permission:** `api_trial_links_list` Lists trial links with revenue enrichment. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `limit` | query | no | | Page size. Default 10, max 25. | | `offset` | query | no | | Rows to skip. Default 0. | | `field` | query | no | | Sort column. One of `create_date` (default), `expire_date`, `claims_count`, `subscribe_counts`, `subscribe_days`, `name`. | | `sort` | query | no | | `desc` (default) or `asc`. | | `search` | query | no | | Match trial link name or custom name (case-insensitive). | | `tag_ids` | query | no | | Comma-separated tag IDs. Returns trials matching any of them. | | `visibility` | query | no | | Which trials to return by hide state: `visible` (default), `hidden` (only hidden) or `all`. Replaces the removed `include_hidden` boolean — pass `visibility=all` for the old `include_hidden=true` behaviour. | | `status` | query | no | | Trial lifecycle filter: `all` (default, no filter), `active` (`isFinished` false) or `finished`. The trial analogue of tracking links' `with_deleted`, since OnlyFans finishes trials rather than deleting them. Combines freely with `visibility`. | | `start_date` | query | no | | Window start for revenue and claim counts. Absent → all-time. | | `end_date` | query | no | | Window end. Absent → all-time. | ## Notes Served from the FansMetric database, so rows are as fresh as the last trials scrape (~2 h) rather than live. When you need OF's current state instead, call the [OnlyFans-relayed list](https://api-docs.fansmetric.com/api-reference/trial-links/list). [Get Trial Link](https://api-docs.fansmetric.com/api-reference/trial-links/get) returns the same per-item shape. The default sort field is `create_date` (no `d`) — passing `created_date` returns `400`. Related: [claimers](https://api-docs.fansmetric.com/api-reference/trial-links/list-subscribers), [per-link stats](https://api-docs.fansmetric.com/api-reference/trial-links/get-stats). ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[].id` | integer | Trial link ID. | | `data.list[].trialLinkName` | string | Trial link name. | | `data.list[].url` | string | Ready-to-share trial link URL. | | `data.list[].subscribeDays` | integer | Trial duration in days. | | `data.list[].subscribeCounts` | integer | Subscriber limit (`0` = unlimited). | | `data.list[].claimCounts` | integer | Claims in the window (or all-time when no window is given). | | `data.list[].allClaimCounts` | integer | All-time claim count. | | `data.list[].isFinished` | boolean | Whether the trial has expired or been deleted. | | `data.list[].createdAt` | string \| null | Creation timestamp. | | `data.list[].expiredAt` | string \| null | Expiration timestamp, or `null`. | | `data.list[].customName` | string \| null | Custom name for internal labelling. | | `data.list[].customSourceUrl` | string \| null | Custom traffic source URL. | | `data.list[].note` | string \| null | Free-text note. | | `data.list[].isHidden` | boolean | Whether the trial is hidden in the UI. | | `data.list[].isRevenueShared` | boolean | Whether revenue is shared with another creator. | | `data.list[].lastScannedAt` | string \| null | When this row was last refreshed. | | `data.list[].user.username` | string | Owning creator's OnlyFans username. | | `data.list[].tags[]` | array | Tags on this trial. Each: `{ id, name, color, created_at }`. | | `data.list[].revenue.total` | string | Net revenue attributed to this trial. | | `data.list[].revenue.spendersCount` | integer | Distinct spenders in the window. | | `data.list[].revenue.revenuePerSubscriber` | string | Average revenue per claimed subscriber. | | `data.list[].revenue.conversionToSpender` | string | Fraction of claimers who spent. | | `data.list[].cost.perPromo` | string \| null | Promo cost you configured. | | `data.list[].cost.perSub` | string \| null | Cost per claimed subscriber. | | `data.list[].cost.profit` | string \| null | Revenue minus promo cost. | | `data.list[].cost.roi` | string \| null | Return on investment (percent). | | `data.list[].links.related.subscribers` | string | URL to fetch subscribers who claimed this trial. | | `data.hasMore` | boolean | Whether more pages remain. | | `data.totalCount` | integer | Total matching rows across all pages. | | `_pagination.next_page` | string | URL for the next page. Omitted on the last page. | ## Example response (200) ```json { "data": { "list": [ { "id": 100000020, "trialLinkName": "1 MONTH FREE TRIAL", "url": "https://onlyfans.com/creator_XXXXX/trial/XXXXXXXXXXXXXXXXXXXXXXXXX", "subscribeDays": 30, "subscribeCounts": 0, "claimCounts": 37, "allClaimCounts": 45, "isFinished": false, "createdAt": "2026-04-05T17:02:51Z", "expiredAt": null, "customName": "Instagram bio", "customSourceUrl": "https://instagram.com/creator_XXXXX", "note": null, "isHidden": false, "isRevenueShared": false, "lastScannedAt": "2026-08-05T02:11:30Z", "user": { "username": "creator_XXXXX" }, "tags": [ { "id": 2, "name": "Instagram", "color": "#E4405F", "created_at": "2026-02-04T16:02:10Z" } ], "revenue": { "total": "245.50", "spendersCount": 6, "revenuePerSubscriber": "6.6351", "conversionToSpender": "0.16216" }, "cost": { "perPromo": "20.00", "perSub": "0.5405", "profit": "225.50", "roi": "1127.5" }, "links": { "related": { "subscribers": "/v1/100000001/trial-links/100000020/subscribers" } } } ], "hasMore": false, "totalCount": 1 }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Trial Link Section: API Reference › Trial Links. Page: https://api-docs.fansmetric.com/api-reference/trial-links/get Returns a single trial link. Served from the FansMetric database, so the shape matches an item from the [FansMetric-backed list](https://api-docs.fansmetric.com/api-reference/trial-links/list-fm) — not the leaner OnlyFans payload the [bare list route](https://api-docs.fansmetric.com/api-reference/trial-links/list) relays. **Endpoint:** `GET /v1/{account_id}/trial-links/{link_id}` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_trial_links_read` Returns a single trial link with revenue enrichment. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `link_id` | path | yes | | Trial link ID. | | `start_date` | query | no | | Window start for revenue and claim counts. Absent → all-time. | | `end_date` | query | no | | Window end. Absent → all-time. | ## Notes Date filters affect `claimCounts`, `revenue.*`, and `cost.perSub` / `cost.roi`. `allClaimCounts` is always all-time. For daily and monthly time-series, use [Get Trial Link Stats](https://api-docs.fansmetric.com/api-reference/trial-links/get-stats). ## Response fields | Field | Type | Description | | --- | --- | --- | | `data` | object | Same fields as an item in the [FansMetric-backed list](https://api-docs.fansmetric.com/api-reference/trial-links/list-fm). | ## Example response (200) ```json { "data": { "id": 100000020, "trialLinkName": "1 MONTH FREE TRIAL", "url": "https://onlyfans.com/creator_XXXXX/trial/XXXXXXXXXXXXXXXXXXXXXXXXX", "subscribeDays": 30, "subscribeCounts": 0, "claimCounts": 37, "allClaimCounts": 45, "isFinished": false, "createdAt": "2026-04-05T17:02:51Z", "expiredAt": null, "customName": "Instagram bio", "customSourceUrl": "https://instagram.com/creator_XXXXX", "note": null, "isHidden": false, "isRevenueShared": false, "lastScannedAt": "2026-08-05T02:11:30Z", "user": { "username": "creator_XXXXX" }, "tags": [ { "id": 2, "name": "Instagram", "color": "#E4405F", "created_at": "2026-02-04T16:02:10Z" } ], "revenue": { "total": "245.50", "spendersCount": 6, "revenuePerSubscriber": "6.6351", "conversionToSpender": "0.16216" }, "cost": { "perPromo": "20.00", "perSub": "0.5405", "profit": "225.50", "roi": "1127.5" }, "links": { "related": { "subscribers": "/v1/100000001/trial-links/100000020/subscribers" } } }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Create Trial Link Section: API Reference › Trial Links. Page: https://api-docs.fansmetric.com/api-reference/trial-links/create Creates a trial link on OnlyFans and stores it in the FansMetric database. **Endpoint:** `POST /v1/{account_id}/trial-links` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_trial_links_create` Creates a trial link. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `name` | body | yes | | Trial link name. | | `subscribe_days` | body | yes | | Trial duration in days. Valid: 1, 3, 7, 14, 30, 90, 180, 360. | | `subscribe_counts` | body | no | | Max claims. 0 = unlimited. Default 0. | | `expire_days` | body | no | | Days until link expires. 0 = no expiry. | | `tag_ids` | body | no | | FansMetric tag IDs. | | `custom_source_url` | body | no | | Custom source URL. | ## Request body example ```json { "name": "1 Month Free Trial", "subscribe_days": 30, "subscribe_counts": 100, "expire_days": 7, "tag_ids": [1, 2], "custom_source_url": "https://reddit.com/r/example" } ``` ## Notes **Breaking change:** the 201 body is now the same item shape as [Get Trial Link](https://api-docs.fansmetric.com/api-reference/trial-links/get) — one canonical camelCase object with nested `revenue` / `cost` / `tags` / `links`. It previously returned the raw OnlyFans object plus `fmTags` and `fmCustomSourceUrl`; those keys are gone. A brand-new trial has no claims or attributed revenue, so every metric is zero and `cost` is all-`null` by definition. Tag resolution is best-effort: if the post-write tag-map fetch fails, `tags` returns `[]` rather than failing the create. Cross-org tag IDs are silently filtered out. The new link shows up in the [live relay list](https://api-docs.fansmetric.com/api-reference/trial-links/list) immediately, and in the [FansMetric list](https://api-docs.fansmetric.com/api-reference/trial-links/list-fm) after the next scraper pass (~2 h). ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.id` | integer | Newly created OnlyFans trial link ID. | | `data.trialLinkName` | string | Trial link name as stored on OnlyFans. | | `data.url` | string | The OnlyFans trial URL fans claim. | | `data.subscribeDays` | integer | Length of the free trial granted to a claimer, in days. | | `data.subscribeCounts` | integer | The **claim limit** — the "y" in "x of y". `0` means unlimited. OnlyFans' naming, kept for parity; it is not a count of subscribers. | | `data.claimCounts` | integer | Always `0` on creation. | | `data.allClaimCounts` | integer | Always `0` on creation. Lifetime claims — the "x" in "x of y". | | `data.isFinished` | boolean | Always `false` on creation. OnlyFans finishes trials rather than deleting them. | | `data.createdAt` | string \| null | Creation timestamp (RFC 3339). | | `data.expiredAt` | string \| null | Expiry timestamp, or `null` when the link does not expire. | | `data.customName` | string \| null | FansMetric display-name override. `null` on creation — set it via [Update Trial Link](https://api-docs.fansmetric.com/api-reference/trial-links/update). | | `data.customSourceUrl` | string \| null | Traffic-source URL stored in FansMetric (the value submitted in `custom_source_url`). | | `data.note` | string \| null | Free-text note. `null` on creation. | | `data.isHidden` | boolean | FansMetric hide flag. `false` on creation. | | `data.isRevenueShared` | boolean | Whether an enabled share exposes revenue. `false` on creation. | | `data.lastScannedAt` | string \| null | When the scraper last refreshed this link. `null` until the first pass. | | `data.user.username` | string | Creator username. Empty string if it could not be resolved. | | `data.tags[]` | array | Full tag objects for the IDs passed in `tag_ids`. Each element has `id`, `name`, `color`, `created_at` — same shape as `GET /v1/tags`. Resolution is best-effort: if the post-write tag-map fetch fails, `tags` is `[]` rather than failing the create. Cross-org tag IDs are silently filtered out. | | `data.revenue.total` | string | `"0.00"` on creation. | | `data.revenue.spendersCount` | integer | `0` on creation. | | `data.revenue.revenuePerSubscriber` | string | `"0"` on creation. | | `data.revenue.conversionToSpender` | string | Claim→spend rate. `"0"` on creation. | | `data.cost` | object | `perPromo`, `perSub`, `profit`, `roi` — all `null` until a promo cost is set, which is how you tell "not set" from zero. | | `data.links.related.subscribers` | string | Path to this link's claimers. | ## Example response (201) ```json { "data": { "id": 100000021, "trialLinkName": "1 Month Free Trial", "url": "https://onlyfans.com/action/trial/XXXXXXXXXXXXXXXXXXXXXXXXX", "subscribeDays": 30, "subscribeCounts": 100, "claimCounts": 0, "allClaimCounts": 0, "isFinished": false, "createdAt": "2026-05-15T10:00:00Z", "expiredAt": "2026-05-22T10:00:00Z", "customName": null, "customSourceUrl": "https://reddit.com/r/example", "note": null, "isHidden": false, "isRevenueShared": false, "lastScannedAt": null, "user": { "username": "creator_XXXXX" }, "tags": [ { "id": 1, "name": "Reddit", "color": "#FF5733", "created_at": "2026-01-12T09:14:22Z" }, { "id": 2, "name": "Twitter", "color": "#1DA1F2", "created_at": "2026-01-12T09:15:01Z" } ], "revenue": { "total": "0.00", "spendersCount": 0, "revenuePerSubscriber": "0", "conversionToSpender": "0" }, "cost": { "perPromo": null, "perSub": null, "profit": null, "roi": null }, "links": { "related": { "subscribers": "/v1/100000001/trial-links/100000021/subscribers" } } }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Delete Trial Link Section: API Reference › Trial Links. Page: https://api-docs.fansmetric.com/api-reference/trial-links/delete Deletes a trial link on OnlyFans. Sets `is_finished = true` in the FansMetric database. **Endpoint:** `DELETE /v1/{account_id}/trial-links/{link_id}` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_trial_links_delete` Deletes a trial link. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `link_id` | path | yes | | Trial link platform ID. | ## Notes ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.success` | boolean | Always `true` on a successful delete. | ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Trial Link Stats Section: API Reference › Trial Links. Page: https://api-docs.fansmetric.com/api-reference/trial-links/get-stats Returns cumulative totals plus daily and monthly time-series for a single trial link. **Endpoint:** `GET /v1/{account_id}/trial-links/{link_id}/stats` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_trial_links_read` Returns summary + daily + monthly metrics for one trial link. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `link_id` | path | yes | | Trial link ID. | | `date_start` | query | no | | Window start (UTC). Absent → unbounded. | | `date_end` | query | no | | Window end (UTC). Absent → unbounded. | ## Notes **Breaking change:** `summary.clicks_total` and the per-bucket `clicks` field have been removed. For trial links they were always `null` — FansMetric never synced OnlyFans' `clicksCounts` — so this is a pure cleanup with no replacement. Use tracking links if you need clicks. **Added:** `cumulative_subs_total`, `cumulative_revenue_total`, and per-bucket `cumulative_subs` / `cumulative_revenue`. Bucket values (`subs`, `revenue`, `spenders`) are incremental; `cumulative_subs` and `cumulative_revenue` are running totals since the link's first activity. The first returned bucket's `cumulative_revenue` can therefore exceed its own `revenue` — see the 1 August bucket above, which earned nothing but carries July's total forward. `summary.subs_total` / `revenue_total` / `spenders_total` respect the requested window exactly. The `cumulative_*_total` pair runs from the link's inception to `date_end` and ignores `date_start` — a running total restarted at the window edge would not be a cumulative. Buckets are sliced on whole boundaries: a `date_start` in the middle of a day returns that entire day's bucket value, not a partial one. On an unwindowed call `subs_total == cumulative_subs_total`, `revenue_total == cumulative_revenue_total`, and the last daily bucket's `cumulative_revenue` equals `cumulative_revenue_total` — useful as a sanity check. Buckets are UTC day/month boundaries and sparse: only buckets with activity are emitted, with no zero-filling. The FansMetric web app buckets in the viewer's timezone and zero-fills empty days, so cross-checking against the web app across a timezone boundary can appear to shift by a day. Bucket coverage is bounded by sync history — claims and transactions older than the connection's first sync do not appear. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.summary.subs_total` | integer | Claims claimed inside the requested window. | | `data.summary.cumulative_subs_total` | integer | Claims claimed since the link's inception, up to `date_end`. Ignores `date_start`. | | `data.summary.revenue_total` | string | Net attributed revenue inside the window. | | `data.summary.cumulative_revenue_total` | string | Net attributed revenue since inception, up to `date_end`. Ignores `date_start`. | | `data.summary.spenders_total` | integer | Distinct spenders inside the window. | | `data.summary.last_scanned_at` | string \| null | When this link was last refreshed by the scraper. | | `data.daily_metrics[]` | array | Per-day buckets, UTC, sparse — only days with activity are emitted (no zero-filling). | | `data.daily_metrics[].timestamp` | string | Bucket start (`YYYY-MM-DD`, midnight UTC). | | `data.daily_metrics[].subs` | integer | Claims claimed in the bucket. Incremental. | | `data.daily_metrics[].cumulative_subs` | integer | Running total of claims from the link's first activity through this bucket — not from the window start. | | `data.daily_metrics[].revenue` | string | Net revenue in the bucket. Incremental. | | `data.daily_metrics[].cumulative_revenue` | string | Running total of revenue from the link's first activity through this bucket. | | `data.daily_metrics[].spenders` | integer | Distinct spenders in the bucket. | | `data.monthly_metrics[]` | array | Per-month buckets. Same shape as `daily_metrics[]`, aligned to the 1st of the month UTC. | ## Example response (200) ```json { "data": { "summary": { "subs_total": 45, "cumulative_subs_total": 45, "revenue_total": "245.50", "cumulative_revenue_total": "245.50", "spenders_total": 6, "last_scanned_at": "2026-08-05T02:11:30Z" }, "daily_metrics": [ { "timestamp": "2026-07-31", "subs": 3, "cumulative_subs": 30, "revenue": "12.50", "cumulative_revenue": "180.30", "spenders": 1 }, { "timestamp": "2026-08-01", "subs": 2, "cumulative_subs": 32, "revenue": "0.00", "cumulative_revenue": "180.30", "spenders": 0 }, { "timestamp": "2026-08-02", "subs": 4, "cumulative_subs": 36, "revenue": "38.20", "cumulative_revenue": "218.50", "spenders": 2 } ], "monthly_metrics": [ { "timestamp": "2026-07-01", "subs": 30, "cumulative_subs": 30, "revenue": "180.30", "cumulative_revenue": "180.30", "spenders": 4 }, { "timestamp": "2026-08-01", "subs": 15, "cumulative_subs": 45, "revenue": "65.20", "cumulative_revenue": "245.50", "spenders": 2 } ] }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Update Trial Link Section: API Reference › Trial Links. Page: https://api-docs.fansmetric.com/api-reference/trial-links/update Partially updates FansMetric metadata on a trial link — hide state, note, custom name, source URL and promo cost. **Endpoint:** `PATCH /v1/{account_id}/trial-links/{link_id}` **Base URL:** `https://public-api.fansmetric.com` **Data source:** FansMetric data. Served from the FansMetric database — revenue, cost, tags and extra filters, refreshed by the scraper. **Permission:** `api_trial_links_update` Updates FansMetric metadata on a trial link. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `link_id` | path | yes | | Trial link platform ID. | | `custom_name` | body | no | | FansMetric display-name override. Max 64 characters. Send `null` to clear. | | `note` | body | no | | Free-text note. Max 2000 characters. Send `null` to clear. | | `custom_source_url` | body | no | | Traffic-source URL. Max 2048 characters, must be an `http`/`https` URL with a host and no whitespace. Send `null` to clear. | | `promo_cost` | body | no | | Promo cost, between 0 and 99999. Send `null` to clear. | | `is_hidden` | body | no | | FansMetric hide flag (the eye toggle). Boolean — **not** nullable; `null` returns 400. | ## Request body example ```json { "note": null } ``` ## Notes **Merge-patch semantics.** A key absent from the body is left untouched; a key sent as explicit `null` clears the column to SQL `NULL`; a key sent with a value is validated and set. The one exception is `is_hidden`, which is non-nullable — sending `null` returns 400. The sample body above sends only `{"note": null}`: it clears the note and leaves `custom_name`, `custom_source_url`, `promo_cost` and `is_hidden` exactly as they were. An empty body (`{}`) returns 400 — send at least one of the five fields. An unknown field name also returns 400 rather than being ignored, so typos surface immediately instead of silently doing nothing. Writes FansMetric's own fields only — this endpoint never calls OnlyFans. A trial's name, length and claim limit are fixed on OnlyFans once created; set `custom_name` for a FansMetric-side rename. `custom_source_url` is validated here even though the FansMetric web app historically accepted anything — a `javascript:` URL is rejected with 400. The response is the full updated item, identical in shape to [Get Trial Link](https://api-docs.fansmetric.com/api-reference/trial-links/get), with all-time metrics (no date window is applied). ## Response fields | Field | Type | Description | | --- | --- | --- | | `data` | object | The full updated trial link, same shape as [Get Trial Link](https://api-docs.fansmetric.com/api-reference/trial-links/get). | ## Example response (200) ```json { "data": { "id": 100000020, "trialLinkName": "July trial", "url": "https://onlyfans.com/action/trial/XXXXXXXXXXXXXXXXXXXXXXXXX", "subscribeDays": 7, "subscribeCounts": 100, "claimCounts": 9, "allClaimCounts": 9, "isFinished": false, "createdAt": "2026-07-01T00:00:00Z", "expiredAt": null, "customName": "July — Reddit", "customSourceUrl": "https://reddit.com/r/example", "note": null, "isHidden": false, "isRevenueShared": false, "lastScannedAt": "2026-08-31T08:02:11Z", "user": { "username": "creator_XXXXX" }, "tags": [ { "id": 1, "name": "Reddit", "color": "#FF5733", "created_at": "2026-01-12T09:14:22Z" } ], "revenue": { "total": "245.50", "spendersCount": 8, "revenuePerSubscriber": "27.27777777777778", "conversionToSpender": "0.8888888888888888" }, "cost": { "perPromo": "50.00", "perSub": "5.555555555555555", "profit": "195.50", "roi": "391" }, "links": { "related": { "subscribers": "/v1/100000001/trial-links/100000020/subscribers" } } }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Trial Link Claimers Section: API Reference › Trial Links. Page: https://api-docs.fansmetric.com/api-reference/trial-links/list-subscribers Returns the subscribers who joined via a specific trial link. Same per-user shape as entries in [List Subscribers](https://api-docs.fansmetric.com/api-reference/subscribers/list-subscribers). **Endpoint:** `GET /v1/{account_id}/trial-links/{trial_id}/subscribers` **Base URL:** `https://public-api.fansmetric.com` **Data source:** OnlyFans live. Relayed from OnlyFans at request time — raw OF payload, no FansMetric fields. **Permission:** `api_trial_links_list_subscribers` Lists subscribers who claimed a specific trial link. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `trial_id` | path | yes | | OnlyFans trial link ID — the `id` field returned by [List Trial Links](https://api-docs.fansmetric.com/api-reference/trial-links/list). | | `limit` | query | no | | Page size. Default 10. Min 1, max 100. | | `offset` | query | no | | Rows to skip. Default 0. | ## Notes Upstream OnlyFans endpoint: `GET /subscriptions/subscribers?filter[trial_id]=…&format=infinite&limit=…&offset=…`. Tracking-link mirror: the [OnlyFans-relayed tracking claimers list](https://api-docs.fansmetric.com/api-reference/tracking-links/list-claimers). The two return the same per-user shape. Titled *claimers* to match that mirror, because it is the same thing — the fans who took the link up. OnlyFans calls them subscribers on trials and claimers on campaigns, which is why this route's path, slug and permission all still say `subscribers` while the tracking one says `claimers`. Nothing about the request or response changed with the rename. This page shares its title with the [FansMetric-attributed claimers list](https://api-docs.fansmetric.com/api-reference/trial-links/list-claimers-fm); the **OF** and **FM** badges are what tell them apart, as with the two trial-link lists. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[]` | array | Full OF user objects for each claimer — same shape as `/subscribers`. | | `data.hasMore` | boolean | Whether more pages remain. | ## Example response (200) ```json { "data": { "list": [ { "id": 555000002, "username": "fan_two", "name": "Fan Two", "subscribePrice": 0, "subscribedOnData": { "date": "2026-05-22T00:00:00Z" } } ], "hasMore": false }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Trial Link Claimers Section: API Reference › Trial Links. Page: https://api-docs.fansmetric.com/api-reference/trial-links/list-claimers-fm The fans who claimed a trial link, with FansMetric revenue attribution. **Endpoint:** `GET /v1/{account_id}/fm/trial-links/{link_id}/claimers` **Base URL:** `https://public-api.fansmetric.com` **Data source:** FansMetric data. Served from the FansMetric database — revenue, cost, tags and extra filters, refreshed by the scraper. **Permission:** `api_trial_links_list_subscribers` Lists FM-attributed claimers of a trial link. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `link_id` | path | yes | | Trial link platform ID. | | `limit` | query | no | | Results per page. Default 50, clamped to 1–100. | | `offset` | query | no | | Results to skip. Default 0. | | `field` | query | no | | Sort column: `revenue` (default), `claimed_at`, `lifetime_revenue` or `lifetime_revenue_since_claim`. Anything else returns 400. | | `sort` | query | no | | `asc` or `desc`. Default `desc`. | | `date_start` | query | no | | Window start (UTC). What it filters depends on `claimed_in_range`. | | `date_end` | query | no | | Window end (UTC). What it filters depends on `claimed_in_range`. | | `claimed_in_range` | query | no | boolean | Default `false`: the window filters transaction dates (revenue is windowed) and zero-revenue claimers are hidden. Set `true` to window claim dates instead and include zero-revenue claimers. | ## Notes FansMetric's own attribution, not an OnlyFans relay — this is the data behind the web app's Claims modal. This page and the [OnlyFans-relayed claimers list](https://api-docs.fansmetric.com/api-reference/trial-links/list-subscribers) share a title and are told apart by the badge, the same way the two trial-link lists are. **Each money field has its own scope.** `revenue` and `raw_revenue` are **net** and limited to this account's connections. `lifetime_revenue` and `lifetime_revenue_since_claim` are **net** across every connection in your organisation — the web app's "across all creators in your agency" columns. `raw_revenue` vs `revenue`: when one fan claims several links in the same instant, `revenue` divides the transaction between those links while `raw_revenue` does not. A fan whose `raw_revenue` is double their `revenue` claimed two links simultaneously. Transactions with status `undo` are excluded from all four money fields. `hasMore` is `true` whenever the page came back full, so a final page of exactly `limit` rows reports `hasMore: true` and the following request returns an empty list. There is no `totalCount` on this endpoint. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[].id` | integer | The fan's OnlyFans user ID. | | `data.list[].username` | string \| null | OnlyFans username. | | `data.list[].name` | string \| null | Display name. | | `data.list[].avatar_url` | string \| null | Avatar URL. | | `data.list[].claimed_at` | string | When they claimed this link (RFC 3339). | | `data.list[].revenue` | string | Net revenue attributed to **this link**. When the fan claimed several links at the same instant, the transaction is split evenly between them. | | `data.list[].raw_revenue` | string | The same sum **without** the split applied — useful for reconciling against a single link in isolation. | | `data.list[].lifetime_revenue` | string | The fan's total net revenue across **all connections in your organisation** — every creator in the agency — all time. | | `data.list[].lifetime_revenue_since_claim` | string | Same, counting only from their claim onward. | | `data.hasMore` | boolean | `true` when the page came back full. | ## Example response (200) ```json { "data": { "list": [ { "id": 100000501, "username": "fan_one", "name": "Fan One", "avatar_url": "https://cdn.example/avatar.jpg", "claimed_at": "2026-07-01T10:00:00Z", "revenue": "100.00", "raw_revenue": "100.00", "lifetime_revenue": "150.00", "lifetime_revenue_since_claim": "100.00" }, { "id": 100000502, "username": "fan_casual", "name": null, "avatar_url": null, "claimed_at": "2026-07-03T08:00:00Z", "revenue": "40.00", "raw_revenue": "80.00", "lifetime_revenue": "80.00", "lifetime_revenue_since_claim": "80.00" } ], "hasMore": false }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Trial Links Chart Section: API Reference › Trial Links. Page: https://api-docs.fansmetric.com/api-reference/trial-links/get-chart Returns the daily claims timeseries that backs the line graph on OF's Trials tab. **Endpoint:** `GET /v1/{account_id}/trial-links/chart` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_trial_links_read_chart` Daily claim timeseries across all trial links. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `start_date` | query | no | | Window start. `YYYY-MM-DD HH:MM:SS` UTC. Default: 2 years ago. | | `end_date` | query | no | | Window end. Same format. Default: end of today UTC. | ## Notes Upstream OnlyFans endpoint: `GET /trials/chart?stats=1&startDate=…&endDate=…`. OnlyFans does not expose a daily clicks series on trials — only claims. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.claims.chart[]` | array | Daily claim counts. Each entry is `{ date, count }`. | ## Example response (200) ```json { "data": { "claims": { "chart": [ { "date": "2026-06-01", "count": 5 }, { "date": "2026-06-02", "count": 8 } ] } }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Trial Links Overview Section: API Reference › Trial Links. Page: https://api-docs.fansmetric.com/api-reference/trial-links/get-overview Returns the trial-scoped summary card on OF's Trials tab — offers / claims with deltas and a small chart. Same upstream endpoint as `/earnings/overview` with `by=trials` carved out as a dedicated route. **Endpoint:** `GET /v1/{account_id}/trial-links/overview` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_trial_links_read_overview` Headline offers / claims counts and deltas for the trial window. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `start_date` | query | no | | Window start. `YYYY-MM-DD HH:MM:SS` UTC. Default: 2 years ago. | | `end_date` | query | no | | Window end. Same format. Default: end of today UTC. | ## Notes Upstream OnlyFans endpoint: `GET /users/me/stats/overview?by=trials&startDate=…&endDate=…`. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.trials.hasStatistic` | boolean | Whether OF has computed stats for this account. | | `data.trials.offers` | object | `{ total, delta }` — trials offered in the window. | | `data.trials.claims` | object | `{ total, delta }` — trials claimed in the window. | | `data.trials.chartData[]` | array | Sparkline data. Each entry is `{ date, count }`. | ## Example response (200) ```json { "data": { "trials": { "hasStatistic": true, "offers": { "total": 6, "delta": 1 }, "claims": { "total": 89, "delta": 12 }, "chartData": [ { "date": "2026-06-01", "count": 2 }, { "date": "2026-06-02", "count": 4 } ] } }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Trial Links Stats Section: API Reference › Trial Links. Page: https://api-docs.fansmetric.com/api-reference/trial-links/list-stats Returns the per-trial stats table on OF's Trials tab — claim count, click count, and conversion over the requested window, paginated. **Endpoint:** `GET /v1/{account_id}/trial-links/stats` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_trial_links_list_stats` Per-trial stats over a date window (paginated). ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `limit` | query | no | | Page size. Default 10. Min 1, max 100. | | `offset` | query | no | | Rows to skip. Default 0. | | `start_date` | query | no | | Window start. `YYYY-MM-DD HH:MM:SS` UTC. Default: 2 years ago. | | `end_date` | query | no | | Window end. Same format. Default: end of today UTC. | ## Notes Upstream OnlyFans endpoint: `GET /trials/stats?offset=…&limit=…&startDate=…&endDate=…`. Container key is `items` (not `list`). Treat `hasMore` as the source of truth for pagination. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.items[]` | array | Per-trial stats rows. Note OF returns `items` here rather than the more common `list`. | | `data.hasMore` | boolean | Whether more pages remain. | ## Example response (200) ```json { "data": { "items": [ { "trialId": 100000020, "trialLinkName": "1 MONTH FREE TRIAL", "claimsCount": 37, "clicksCount": 412 } ], "hasMore": false }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Trial Link Shares Section: API Reference › Trial Links. Page: https://api-docs.fansmetric.com/api-reference/trial-links/list-shares Lists the public stats-share links created for a trial link. **Endpoint:** `GET /v1/{account_id}/trial-links/{link_id}/shares` **Base URL:** `https://public-api.fansmetric.com` **Data source:** FansMetric data. Served from the FansMetric database — revenue, cost, tags and extra filters, refreshed by the scraper. **Permission:** `api_trial_links_list_shares` Lists share links for a trial link. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `link_id` | path | yes | | Trial Link platform ID. | ## Notes Returns up to 100 shares, newest first. There is no pagination on this endpoint. The `url` origin depends on which FansMetric deployment served the request (`https://app.fansmetric.com`, `https://app.staging.fansmetric.com` or `https://app.buffmetrics.com`). Use the returned `url` rather than assembling it from the `id` yourself. The share row's UUID **is** the public token — anyone holding the URL can view the page without authenticating. Treat it like a secret link. `is_enabled` exists in the underlying schema but is dead — nothing reads it — so it is not exposed here. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[].id` | string | Share UUID. This is also the public token in the URL. | | `data.list[].name` | string \| null | Optional label for your own reference. Max 128 characters. | | `data.list[].is_revenue_shared` | boolean | Whether the public page shows revenue figures. | | `data.list[].url` | string | The ready-to-send public page URL (`{app-origin}/share/{id}`). | | `data.list[].created_at` | string | Creation timestamp (RFC 3339). | | `data.list[].updated_at` | string | Last-update timestamp (RFC 3339). | ## Example response (200) ```json { "data": { "list": [ { "id": "6f1c2d9e-4a7b-4c31-9f80-2b5e7a91c3d4", "name": "reddit push", "is_revenue_shared": true, "url": "https://app.fansmetric.com/share/6f1c2d9e-4a7b-4c31-9f80-2b5e7a91c3d4", "created_at": "2026-08-31T10:00:00Z", "updated_at": "2026-08-31T10:00:00Z" } ] }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Create Trial Link Share Section: API Reference › Trial Links. Page: https://api-docs.fansmetric.com/api-reference/trial-links/create-share Creates a public stats-share link for a trial link and returns its ready-to-send URL. **Endpoint:** `POST /v1/{account_id}/trial-links/{link_id}/shares` **Base URL:** `https://public-api.fansmetric.com` **Data source:** FansMetric data. Served from the FansMetric database — revenue, cost, tags and extra filters, refreshed by the scraper. **Permission:** `api_trial_links_create_share` Creates a share link for a trial link. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `link_id` | path | yes | | Trial Link platform ID. | | `name` | body | no | | Optional label for your own reference. Max 128 characters. Default `null`. | | `is_revenue_shared` | body | no | | Whether the public page shows revenue. Default `false`. | ## Request body example ```json { "name": "reddit push", "is_revenue_shared": true } ``` ## Notes An empty body (`{}`) is valid and creates a share with the defaults (`name: null`, `is_revenue_shared: false`). The `url` origin depends on which FansMetric deployment served the request (`https://app.fansmetric.com`, `https://app.staging.fansmetric.com` or `https://app.buffmetrics.com`). Use the returned `url` rather than assembling it from the `id` yourself. The share row's UUID **is** the public token — anyone holding the URL can view the page without authenticating. Treat it like a secret link. Each call mints a **new** share with a new UUID — there is no upsert. Creating three shares for one link gives you three independent URLs, which is the intended way to hand different recipients revocable links. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.id` | string | Share UUID. This is also the public token in the URL. | | `data.name` | string \| null | Optional label for your own reference. Max 128 characters. | | `data.is_revenue_shared` | boolean | Whether the public page shows revenue figures. | | `data.url` | string | The ready-to-send public page URL (`{app-origin}/share/{id}`). | | `data.created_at` | string | Creation timestamp (RFC 3339). | | `data.updated_at` | string | Last-update timestamp (RFC 3339). | ## Example response (201) ```json { "data": { "id": "6f1c2d9e-4a7b-4c31-9f80-2b5e7a91c3d4", "name": "reddit push", "is_revenue_shared": true, "url": "https://app.fansmetric.com/share/6f1c2d9e-4a7b-4c31-9f80-2b5e7a91c3d4", "created_at": "2026-08-31T10:00:00Z", "updated_at": "2026-08-31T10:00:00Z" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Update Trial Link Share Section: API Reference › Trial Links. Page: https://api-docs.fansmetric.com/api-reference/trial-links/update-share Partially updates a trial link share — its label and whether the public page shows revenue. **Endpoint:** `PATCH /v1/{account_id}/trial-links/{link_id}/shares/{share_id}` **Base URL:** `https://public-api.fansmetric.com` **Data source:** FansMetric data. Served from the FansMetric database — revenue, cost, tags and extra filters, refreshed by the scraper. **Permission:** `api_trial_links_update_share` Updates a share link. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `link_id` | path | yes | | Trial Link platform ID. | | `share_id` | path | yes | | Share UUID. | | `name` | body | no | | Label. Max 128 characters. Send `null` to clear. | | `is_revenue_shared` | body | no | | Whether the public page shows revenue. Boolean. | ## Request body example ```json { "is_revenue_shared": false } ``` ## Notes Merge-patch, same rules as the link PATCH: an absent key is left untouched, `name: null` clears the label, and a value is validated and set. An empty body or an unknown field returns 400. Toggling `is_revenue_shared` takes effect on the existing URL — the token does not change, so a link already sent out will start or stop showing revenue. A `share_id` that is not a well-formed UUID simply matches nothing and returns 404 rather than erroring. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.id` | string | Share UUID. This is also the public token in the URL. | | `data.name` | string \| null | Optional label for your own reference. Max 128 characters. | | `data.is_revenue_shared` | boolean | Whether the public page shows revenue figures. | | `data.url` | string | The ready-to-send public page URL (`{app-origin}/share/{id}`). | | `data.created_at` | string | Creation timestamp (RFC 3339). | | `data.updated_at` | string | Last-update timestamp (RFC 3339). | ## Example response (200) ```json { "data": { "id": "6f1c2d9e-4a7b-4c31-9f80-2b5e7a91c3d4", "name": "reddit push", "is_revenue_shared": false, "url": "https://app.fansmetric.com/share/6f1c2d9e-4a7b-4c31-9f80-2b5e7a91c3d4", "created_at": "2026-08-31T10:00:00Z", "updated_at": "2026-08-31T11:30:00Z" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Delete Trial Link Share Section: API Reference › Trial Links. Page: https://api-docs.fansmetric.com/api-reference/trial-links/delete-share Permanently deletes a trial link share, immediately breaking its public URL. **Endpoint:** `DELETE /v1/{account_id}/trial-links/{link_id}/shares/{share_id}` **Base URL:** `https://public-api.fansmetric.com` **Data source:** FansMetric data. Served from the FansMetric database — revenue, cost, tags and extra filters, refreshed by the scraper. **Permission:** `api_trial_links_delete_share` Deletes a share link. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `link_id` | path | yes | | Trial Link platform ID. | | `share_id` | path | yes | | Share UUID. | ## Notes **Hard delete.** The row is removed, the public page 404s immediately, and the token cannot be revived. There is no disable — recreate the share to get a new URL. Deleting an already-deleted or unknown share returns 404. If you only want to stop exposing revenue, PATCH `is_revenue_shared` to `false` instead and keep the URL working. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.success` | boolean | Always `true` on a successful delete. | ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Shared Trial Links Section: API Reference › Trial Links. Page: https://api-docs.fansmetric.com/api-reference/trial-links/list-share-access Returns trial links from other creators that this account has been granted share-access to. Read-only mirror of [List Trial Links](https://api-docs.fansmetric.com/api-reference/trial-links/list). **Endpoint:** `GET /v1/{account_id}/trial-links/share-access` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_trial_links_list_share_access` Lists trial links shared with this account by other creators. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `limit` | query | no | | Page size. Default 10. Min 1, max 200. | | `offset` | query | no | | Rows to skip. Default 0. | | `field` | query | no | | Sort column. One of `create_date`, `expire_date`, `claims_count`, `clicks_count`, `subscribe_counts`, `subscribe_days`, `shared` (default). | | `sort` | query | no | | `desc` (default) or `asc`. | ## Notes Upstream OnlyFans endpoint: `GET /trials/share-access?…`. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[]` | array | Shared trial links on this page. Same per-item shape as [List Trial Links](https://api-docs.fansmetric.com/api-reference/trial-links/list), minus the `isFinished` flag (those entries are owned upstream). | | `data.hasMore` | boolean | Whether more pages remain. | ## Example response (200) ```json { "data": { "list": [ { "id": 200000050, "trialLinkName": "Cross-promo: 7 days free", "url": "https://onlyfans.com/other_creator/trial/YYYYYYYYY", "subscribeDays": 7, "subscribeCounts": 100, "claimCounts": 22, "clicksCounts": 410, "createdAt": "2026-04-01T10:00:00Z", "expiredAt": null, "user": { "id": 999000001, "username": "other_creator" } } ], "hasMore": false }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Tags Section: API Reference › Tags. Page: https://api-docs.fansmetric.com/api-reference/tags/list Returns all link tags for the authenticated organization. Tags can be assigned to tracking links and trial links. **Endpoint:** `GET /v1/tags` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_tags_list` Lists organization-wide link tags. ## Notes Tags are scoped to the organization, not to an individual account. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.tags[].id` | integer | Tag ID. | | `data.tags[].name` | string | Tag name (unique per org). | | `data.tags[].color` | string | Hex color (e.g. `#93c5fd`). | | `data.tags[].created_at` | string | RFC 3339 timestamp. | ## Example response (200) ```json { "data": { "tags": [ { "id": 1, "name": "Reddit", "color": "#93c5fd", "created_at": "2026-04-20T10:30:00Z" }, { "id": 4, "name": "Twitter", "color": "#fca5a5", "created_at": "2026-04-21T14:00:00Z" } ] }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Create Tag Section: API Reference › Tags. Page: https://api-docs.fansmetric.com/api-reference/tags/create Creates a new link tag. Max 500 tags per organization. Names must be unique. **Endpoint:** `POST /v1/tags` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_tags_create` Creates a tag. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `name` | body | yes | | Tag name (unique per org). | | `color` | body | yes | | Hex color, e.g. `#93c5fd`. | ## Request body example ```json { "name": "Reddit", "color": "#93c5fd" } ``` ## Notes Returns 409 if a tag with that name already exists in the org. ## Example response (201) ```json { "data": { "tag": { "id": 5, "name": "Reddit", "color": "#93c5fd", "created_at": "2026-05-14T12:00:00Z" } }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Set Tracking Link Tags Section: API Reference › Tags. Page: https://api-docs.fansmetric.com/api-reference/tags/set-tracking-link Replaces all tags on a tracking link. Pass an empty array to remove all tags. **Endpoint:** `PUT /v1/{account_id}/tracking-links/{tracking_link_id}/tags` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_tags_set_tracking_link` Replaces a tracking link's tags. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `tracking_link_id` | path | yes | | Tracking link platform ID. | | `tag_ids` | body | yes | | Array of tag IDs. Pass `[]` to clear. Only tags belonging to your org are applied. | ## Request body example ```json { "tag_ids": [1, 4, 6] } ``` ## Notes `tag_ids` must be a JSON array of integers — e.g. `[1, 4, 6]`. A single value should still be wrapped (`[8]`). Pass `[]` to clear all tags. Omitting `tag_ids` or sending `null` returns 400. Cross-org tag IDs are silently filtered — only tags belonging to your organization are applied. ## Example response (200) ```json { "data": { "tracking_link_id": "100000010", "tag_ids": [1, 4, 6] }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Set Trial Link Tags Section: API Reference › Tags. Page: https://api-docs.fansmetric.com/api-reference/tags/set-trial-link Replaces all tags on a trial link. **Endpoint:** `PUT /v1/{account_id}/trial-links/{trial_link_id}/tags` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_tags_set_trial_link` Replaces a trial link's tags. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `trial_link_id` | path | yes | | Trial link platform ID. | | `tag_ids` | body | yes | | Array of tag IDs. Pass `[]` to clear. | ## Request body example ```json { "tag_ids": [1, 2] } ``` ## Notes `tag_ids` must be a JSON array of integers — e.g. `[1, 2]`. A single value should still be wrapped (`[8]`). Pass `[]` to clear all tags. Omitting `tag_ids` or sending `null` returns 400. Cross-org tag IDs are silently filtered — only tags belonging to your organization are applied. ## Example response (200) ```json { "data": { "trial_link_id": "100000020", "tag_ids": [1, 2] }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Bulk Add Tags to Tracking Links Section: API Reference › Tags. Page: https://api-docs.fansmetric.com/api-reference/tags/bulk-add-tracking Adds tags to many tracking links at once. Does not remove existing tags. **Endpoint:** `POST /v1/{account_id}/tracking-links/tags/add` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_tags_bulk_add_tracking_links` Bulk-adds tags to tracking links. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `link_ids` | body | yes | | Array of tracking link platform IDs. | | `tag_ids` | body | yes | | Tag IDs to add. | ## Request body example ```json { "link_ids": ["100000010", "100000012"], "tag_ids": [1, 2] } ``` ## Notes `link_ids` is a JSON array of tracking link IDs; `tag_ids` is a JSON array of integers. Single values must still be wrapped (`[8]`). Both fields are required. Empty arrays or missing fields return 400. Cross-org link IDs and tag IDs are silently filtered — only entities belonging to your organization are affected. ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Bulk Remove Tags from Tracking Links Section: API Reference › Tags. Page: https://api-docs.fansmetric.com/api-reference/tags/bulk-remove-tracking Removes tags from many tracking links at once. **Endpoint:** `POST /v1/{account_id}/tracking-links/tags/remove` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_tags_bulk_remove_tracking_links` Bulk-removes tags from tracking links. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `link_ids` | body | yes | | Array of tracking link platform IDs. | | `tag_ids` | body | yes | | Tag IDs to remove. | ## Request body example ```json { "link_ids": ["100000010", "100000012"], "tag_ids": [1, 2] } ``` ## Notes `link_ids` is a JSON array of tracking link IDs; `tag_ids` is a JSON array of integers. Single values must still be wrapped (`[8]`). Both fields are required. Empty arrays or missing fields return 400. Cross-org link IDs and tag IDs are silently filtered — only entities belonging to your organization are affected. ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Bulk Add Tags to Trial Links Section: API Reference › Tags. Page: https://api-docs.fansmetric.com/api-reference/tags/bulk-add-trial Adds tags to many trial links at once. **Endpoint:** `POST /v1/{account_id}/trial-links/tags/add` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_tags_bulk_add_trial_links` Bulk-adds tags to trial links. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `link_ids` | body | yes | | Array of trial link platform IDs. | | `tag_ids` | body | yes | | Tag IDs to add. | ## Request body example ```json { "link_ids": ["100000020", "11174258"], "tag_ids": [1, 2] } ``` ## Notes `link_ids` is a JSON array of trial link IDs; `tag_ids` is a JSON array of integers. Single values must still be wrapped (`[8]`). Both fields are required. Empty arrays or missing fields return 400. Cross-org link IDs and tag IDs are silently filtered — only entities belonging to your organization are affected. ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Bulk Remove Tags from Trial Links Section: API Reference › Tags. Page: https://api-docs.fansmetric.com/api-reference/tags/bulk-remove-trial Removes tags from many trial links at once. **Endpoint:** `POST /v1/{account_id}/trial-links/tags/remove` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_tags_bulk_remove_trial_links` Bulk-removes tags from trial links. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `link_ids` | body | yes | | Array of trial link platform IDs. | | `tag_ids` | body | yes | | Tag IDs to remove. | ## Request body example ```json { "link_ids": ["100000020", "11174258"], "tag_ids": [1, 2] } ``` ## Notes `link_ids` is a JSON array of trial link IDs; `tag_ids` is a JSON array of integers. Single values must still be wrapped (`[8]`). Both fields are required. Empty arrays or missing fields return 400. Cross-org link IDs and tag IDs are silently filtered — only entities belonging to your organization are affected. ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Tracking Link Tags Section: API Reference › Tags. Page: https://api-docs.fansmetric.com/api-reference/tags/list-tracking-link Returns the tags attached to a single tracking link. **Endpoint:** `GET /v1/{account_id}/tracking-links/{link_id}/tags` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_tracking_links_read` Lists tags on one tracking link. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `link_id` | path | yes | | Tracking link ID. | ## Notes ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.tags[]` | array | Tags on this link. Each: `{ id, name, color, created_at }`. | ## Example response (200) ```json { "data": { "tags": [ { "id": 1, "name": "Reddit", "color": "#FF5733", "created_at": "2026-01-12T09:14:22Z" }, { "id": 4, "name": "Instagram", "color": "#E4405F", "created_at": "2026-02-04T16:02:10Z" } ] }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Add Tags to Tracking Link Section: API Reference › Tags. Page: https://api-docs.fansmetric.com/api-reference/tags/add-tracking-link Adds tags (by name) to a tracking link. Existing tags are preserved. **Endpoint:** `POST /v1/{account_id}/tracking-links/{link_id}/tags` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_tags_bulk_add_tracking_links` Adds tags (by name) to one tracking link. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `link_id` | path | yes | | Tracking link ID. | | `tags` | body | yes | | Tag **names**. Each must already exist — create tags via [Create Tag](https://api-docs.fansmetric.com/api-reference/tags/create) first. | ## Request body example ```json { "tags": ["Reddit", "Instagram"] } ``` ## Notes Unknown tag names return `400` — nothing is applied. For adding tags to many links at once, use [Bulk Add Tags to Tracking Links](https://api-docs.fansmetric.com/api-reference/tags/bulk-add-tracking). ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.tags[]` | array | Full tag list on this link after the update. | ## Example response (200) ```json { "data": { "tags": [ { "id": 1, "name": "Reddit", "color": "#FF5733", "created_at": "2026-01-12T09:14:22Z" }, { "id": 4, "name": "Instagram", "color": "#E4405F", "created_at": "2026-02-04T16:02:10Z" }, { "id": 6, "name": "TikTok", "color": "#00C4B8", "created_at": "2026-03-21T11:48:09Z" } ] }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Remove Tags from Tracking Link Section: API Reference › Tags. Page: https://api-docs.fansmetric.com/api-reference/tags/remove-tracking-link Removes tags (by name) from a tracking link. **Endpoint:** `DELETE /v1/{account_id}/tracking-links/{link_id}/tags` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_tags_bulk_remove_tracking_links` Removes tags (by name) from one tracking link. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `link_id` | path | yes | | Tracking link ID. | | `tags` | body | yes | | Tag **names**. Unknown names return `400`. | ## Request body example ```json { "tags": ["Instagram"] } ``` ## Notes Names not currently on the link are silently ignored. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.tags[]` | array | Full tag list on this link after the update. | ## Example response (200) ```json { "data": { "tags": [ { "id": 1, "name": "Reddit", "color": "#FF5733", "created_at": "2026-01-12T09:14:22Z" }, { "id": 6, "name": "TikTok", "color": "#00C4B8", "created_at": "2026-03-21T11:48:09Z" } ] }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Trial Link Tags Section: API Reference › Tags. Page: https://api-docs.fansmetric.com/api-reference/tags/list-trial-link Returns the tags attached to a single trial link. **Endpoint:** `GET /v1/{account_id}/trial-links/{link_id}/tags` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_trial_links_read` Lists tags on one trial link. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `link_id` | path | yes | | Trial link ID. | ## Notes ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.tags[]` | array | Tags on this link. Each: `{ id, name, color, created_at }`. | ## Example response (200) ```json { "data": { "tags": [ { "id": 2, "name": "Instagram", "color": "#E4405F", "created_at": "2026-02-04T16:02:10Z" } ] }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Add Tags to Trial Link Section: API Reference › Tags. Page: https://api-docs.fansmetric.com/api-reference/tags/add-trial-link Adds tags (by name) to a trial link. Existing tags are preserved. **Endpoint:** `POST /v1/{account_id}/trial-links/{link_id}/tags` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_tags_bulk_add_trial_links` Adds tags (by name) to one trial link. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `link_id` | path | yes | | Trial link ID. | | `tags` | body | yes | | Tag **names**. Each must already exist — create tags via [Create Tag](https://api-docs.fansmetric.com/api-reference/tags/create) first. | ## Request body example ```json { "tags": ["Instagram", "Twitter"] } ``` ## Notes Unknown tag names return `400` — nothing is applied. For adding tags to many links at once, use [Bulk Add Tags to Trial Links](https://api-docs.fansmetric.com/api-reference/tags/bulk-add-trial). ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.tags[]` | array | Full tag list on this link after the update. | ## Example response (200) ```json { "data": { "tags": [ { "id": 2, "name": "Instagram", "color": "#E4405F", "created_at": "2026-02-04T16:02:10Z" }, { "id": 3, "name": "Twitter", "color": "#1DA1F2", "created_at": "2026-01-12T09:15:01Z" } ] }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Remove Tags from Trial Link Section: API Reference › Tags. Page: https://api-docs.fansmetric.com/api-reference/tags/remove-trial-link Removes tags (by name) from a trial link. **Endpoint:** `DELETE /v1/{account_id}/trial-links/{link_id}/tags` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_tags_bulk_remove_trial_links` Removes tags (by name) from one trial link. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `link_id` | path | yes | | Trial link ID. | | `tags` | body | yes | | Tag **names**. Unknown names return `400`. | ## Request body example ```json { "tags": ["Twitter"] } ``` ## Notes Names not currently on the link are silently ignored. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.tags[]` | array | Full tag list on this link after the update. | ## Example response (200) ```json { "data": { "tags": [ { "id": 2, "name": "Instagram", "color": "#E4405F", "created_at": "2026-02-04T16:02:10Z" } ] }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Model Start Date Section: API Reference › Accounts. Page: https://api-docs.fansmetric.com/api-reference/accounts/get-model-start-date Returns the date the creator's account was registered on OnlyFans. Useful as a `start_date` value for full-history pulls on the earnings, payouts, and chargeback endpoints. **Endpoint:** `GET /v1/{account_id}/me/start-date` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_me_read_start_date` Returns the OnlyFans registration timestamp for the account. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/users/me/start-date-model`. Pass the returned `startDate` as `start_date` on history-windowed endpoints (`/earnings`, `/payouts/chargebacks/ratio`, etc.) to scan the full account lifetime. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.startDate` | string | Account registration timestamp on OnlyFans. UTC, `YYYY-MM-DD HH:MM:SS` format. | ## Example response (200) ```json { "data": { "startDate": "2025-09-17 04:23:50" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Today's Activity Section: API Reference › Activity. Page: https://api-docs.fansmetric.com/api-reference/activity/today Returns the creator's activity counts for the current day — stories, posts, chats, streams. Drives the OnlyFans dashboard's "today" indicators. **Endpoint:** `GET /v1/{account_id}/activity/today` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_activity_read_today` Returns today's posting / streaming / messaging counts for the account. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/users/me/stats/today-activity`. "Today" is OnlyFans's interpretation — observed to be the creator's local-tz day, not strictly UTC. Treat the rollover boundary as approximate. These counts feed the streak counters; the [`List Activity Streaks`](https://api-docs.fansmetric.com/api-reference/streaks/list-activity-streaks) totals will reflect today's numbers once the day closes. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.stories` | integer | Stories posted today. | | `data.posts` | integer | Feed posts published today. | | `data.chats` | integer | Chat messages sent today (DM activity). | | `data.streams` | integer | Streams started today (count, not duration). | ## Example response (200) ```json { "data": { "stories": 0, "posts": 104, "chats": 310, "streams": 0 }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Earnings Overview Section: API Reference › Earnings. Page: https://api-docs.fansmetric.com/api-reference/earnings/overview Returns aggregated earnings and activity stats for a date window — top-line totals plus per-section breakdowns (posts, streams, visitors, mass messages) with chart data. The "dashboard" view; for the per-transaction feed use List All Earnings. **Endpoint:** `GET /v1/{account_id}/earnings/overview` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_earnings_read_overview` Returns aggregated earnings and per-section activity stats for a window. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `start_date` | query | no | | Window start. Default 2 years ago, UTC. Format `YYYY-MM-DD HH:MM:SS` or ISO 8601. | | `end_date` | query | no | | Window end. Default end of today, UTC. Same format as `start_date`. | | `by` | query | no | | Narrow the response to a single section. Values: `earnings` (top-line only), `posts`, `streams`, `visitors`, `messages`, `story`, `promo`. Forwarded upstream as-is. `by` is an input vocabulary and does not always match the response key — `by=messages` returns the section keyed `massMessages`. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/users/me/stats/overview?startDate=…&endDate=…&by=…`. When `by=earnings`, only `{ earning }` is returned — the other sections are omitted (not zeroed). `by=story` returns a `stories` section with a `tips` sub-object (stories monetize via tips, not purchases) instead of `earnings`. `by=promo` returns a `promo` section with `offers.total`, `claims.total`, monthly `chartData`, and `earnings` attributed to promo-claim subscriptions. Other `by` values (`posts`, `streams`, `visitors`) return only that section, keyed by the same name. `by=messages` is the exception: it returns the section keyed `massMessages`. `chartData` bucket granularity is window-dependent, not fixed — a 90-day window has been observed returning daily buckets, the 2-year default monthly ones. Read each point's `date` rather than assuming a period. `delta` is a whole-number percent and saturates at `100` — treat ≥100 as "at least doubled". All currency amounts are in the account's payout currency (see `/v1/{account_id}/payouts/balances`). For a richer visitor breakdown (top countries, duration, monthly chart), use [`/v1/{account_id}/reach/profile-visitors`](https://api-docs.fansmetric.com/api-reference/reach/profile-visitors). ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.earning.total` | number | Net earnings to the creator across the window. | | `data.earning.gross` | number | Gross earnings before fees/taxes. | | `data.earning.delta` | integer | Percent change vs the prior equal-length window (`100` = +100%, saturates at 100). | | `data.posts` | object | Posts section. `count` = posts published; `views` = total post views; `earnings` = revenue attributed to posts. See Section shape. | | `data.streams` | object | Streams section. `count.total` is a **string** duration (e.g. `"4h 12m"`); `views` is viewer count. | | `data.visitors` | object | Profile visitors. Also carries `subscriptions.new` and `subscriptions.renew` counters. | | `data.massMessages` | object | Mass-message activity. `count` = messages sent; `views` = opens. | | `data.
.hasStatistic` | boolean | `true` if upstream has data for this section in the window. `false` sections still return zeroed fields for layout stability. | | `data.
.chartData[]` | array | Chart buckets `{ date, count }`. Bucket granularity is window-dependent — read each point's `date` rather than assuming a period. `count` units are section-defined — earnings for posts/streams/massMessages, visitor counts for visitors. | ## Example response (200) ```json { "data": { "earning": { "total": 1340918.6, "gross": 1675118.6, "delta": 100 }, "posts": { "hasStatistic": true, "count": { "total": 5354, "delta": 100 }, "views": { "total": 9821330, "delta": 100 }, "earnings": { "total": 244018.4, "gross": 305023.0, "delta": 100 }, "chartData": [ { "date": "2025-09-01T00:00:00+00:00", "count": 12410.5 } ] }, "streams": { "hasStatistic": false, "count": { "total": "0m", "delta": 0 }, "views": { "total": 0, "delta": 0 }, "earnings": { "total": 0, "gross": 0, "delta": 0 }, "chartData": [] }, "visitors": { "hasStatistic": true, "count": { "total": 2581195, "delta": 100 }, "visitors": { "total": 2581195, "delta": 100 }, "subscriptions": { "new": { "total": 3210, "delta": 100 }, "renew": { "total": 8154, "delta": 33 } }, "chartData": [ { "date": "2025-09-01T00:00:00+00:00", "count": 19922 } ] }, "massMessages": { "hasStatistic": true, "count": { "total": 412, "delta": 100 }, "views": { "total": 198455, "delta": 100 }, "earnings": { "total": 78211.45, "gross": 97764.31, "delta": 100 }, "chartData": [] } }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Earnings Chart Section: API Reference › Earnings. Page: https://api-docs.fansmetric.com/api-reference/earnings/chart Returns the per-source earnings timeseries that backs the OnlyFans **Statements → Earnings** page — one $ series (`chartAmount`), one transaction-count series (`chartCount`), net + gross totals, and OF's percent-change `delta` vs the previous equal-length window. Bucket granularity (daily vs monthly) is chosen by OnlyFans based on window length. **Endpoint:** `GET /v1/{account_id}/earnings/chart` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_earnings_read_chart` Returns per-source earnings amount and transaction-count series with window net/gross totals and prior-period delta. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `by` | query | no | | Revenue source. One of `total` (default), `subscribes`, `tips`, `post`, `chat_messages`, `stream`, `tips_profile`, `tips_post`, `tips_chat`, `tips_stream`, `tips_story`. The five `tips_*` variants drill the Tips series down by source. | | `start_date` | query | no | | Window start. Default 2 years ago, UTC. `YYYY-MM-DD HH:MM:SS` or ISO 8601 (the `T` separator is normalized to a space). To pull a full lifetime chart, pass the `startDate` from `/me/start-date`. | | `end_date` | query | no | | Window end. Default end of today, UTC. Same format as `start_date`. | ## Notes Response shape is the same for every `by` value. Field name `count` is shared by both series — it represents dollars in `chartAmount` and transaction rows in `chartCount`. Bucket granularity is OF-controlled. Short windows return daily buckets; multi-month windows return monthly buckets aligned to the 1st-of-month UTC. For the per-transaction feed use [List All Earnings](https://api-docs.fansmetric.com/api-reference/earnings/list); for the broader dashboard view use [Earnings Overview](https://api-docs.fansmetric.com/api-reference/earnings/overview). ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.chartAmount[]` | array | One bucket per period in the window (daily or monthly — OF picks). `date` is midnight UTC ISO 8601 at the bucket start; `count` is **earnings $** in that bucket, in the account's payout currency. | | `data.chartCount[]` | array | Same bucket alignment as `chartAmount`. `count` is the **number of transactions** in that bucket. | | `data.total` | number | **Net** earnings (after platform fees) over the window — sum of `chartAmount[].count`. | | `data.gross` | number | **Gross** earnings (before platform fees) over the window. | | `data.delta` | number | OF-computed change vs the immediately preceding equal-length window. Reported as a whole-number percent and saturates at `100` (treat ≥100 as "at least doubled"). | ## Example response (200) ```json { "data": { "chartAmount": [ { "date": "2025-09-01T00:00:00+00:00", "count": 10040 }, { "date": "2025-10-01T00:00:00+00:00", "count": 152856.81 } ], "chartCount": [ { "date": "2025-09-01T00:00:00+00:00", "count": 395 }, { "date": "2025-10-01T00:00:00+00:00", "count": 5286 } ], "total": 1404729.68, "gross": 1754794.68, "delta": 100 }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List All Earnings Section: API Reference › Earnings. Page: https://api-docs.fansmetric.com/api-reference/earnings/list Returns the account's per-transaction earnings feed across all revenue streams combined — subscriptions, tips, PPV post purchases, paid messages, stream earnings. One row per payment. Filter to a single stream with `type`; narrow tips to a single surface with `tips_source`. **Endpoint:** `GET /v1/{account_id}/earnings` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_earnings_list` Lists per-transaction earnings rows newest first, with cursor pagination. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `start_date` | query | no | | Lower bound on `createdAt`. Default 2 years ago, UTC. Format `YYYY-MM-DD HH:MM:SS` or ISO 8601 (`T` is normalized to a space). | | `end_date` | query | no | | Optional upper bound on `createdAt`. Same format as `start_date`. | | `marker` | query | no | | Pagination cursor (unix seconds). Omit on the first page; pass the previous response's `nextMarker` for subsequent pages. | | `type` | query | no | | Revenue-stream filter. Values: `subscribes`, `tips`, `post`, `chat_messages`, `stream`. Omit for everything. | | `tips_source` | query | no | | Only meaningful when `type=tips`. Narrows to a single surface. Values: `profile`, `post_all`, `chat`, `stream`, `story`. Forwarded upstream as `tipsSource`. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/payouts/transactions?startDate=…&marker=…`. Returned newest first. Page size is set by OnlyFans (≈10 rows) and is not currently configurable. `marker` is a unix-seconds timestamp cursor — effectively the `createdAt` of the last row seen — not an opaque token. `description` is HTML; for analytics joins prefer `user.id` / `user.username` over parsing the string. A transaction's `net` only becomes withdrawable after `payoutPendingDays` have elapsed since `createdAt` (subject to chargeback reversal). To pull full lifetime history, pass the `startDate` returned by [`/v1/{account_id}/me/start-date`](https://api-docs.fansmetric.com/api-reference/accounts/get-model-start-date) as `start_date`. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[]` | array | Transactions in this page, newest first. | | `data.list[].id` | string | OnlyFans transaction ID (hex). | | `data.list[].amount` | number | Gross transaction amount in `currency`. | | `data.list[].vatAmount` | number | VAT collected from the fan. | | `data.list[].taxAmount` | number | Other tax withheld from the creator. | | `data.list[].mediaTaxAmount` | number | Media-specific tax withheld (digital-goods tax in some jurisdictions). | | `data.list[].fee` | number | OnlyFans platform fee (typically 20% of `amount`). | | `data.list[].net` | number | Amount credited to the creator (`amount − fee − taxes`). | | `data.list[].currency` | string | ISO 4217 currency code. | | `data.list[].createdAt` | string | ISO 8601 transaction timestamp. | | `data.list[].description` | string | Human-readable label containing an HTML `` to the paying fan. Common prefixes: `Payment for message from …`, `Tip from …`, `Post purchase by …`, `Subscription from …`. | | `data.list[].status` | string | Settlement status. `loading` while still in the `payoutPendingDays` hold; transitions to settled after. | | `data.list[].payoutPendingDays` | integer | Days the row stays pending before counting toward `payoutAvailable`. | | `data.list[].user` | object | Paying fan: `id`, `username`, `name`, `displayName`, `avatar`, `avatarThumbs`. | | `data.marker` | integer | Cursor used to fetch this page (unix seconds). | | `data.hasMore` | boolean | Whether more pages remain. | | `data.nextMarker` | integer | Cursor for the next page. Absent on the last page. | ## Example response (200) ```json { "data": { "list": [ { "id": "fd1d0844b7129594ba045a5cf8045fc5", "amount": 19, "vatAmount": 0, "taxAmount": 0, "mediaTaxAmount": 0, "net": 15.2, "fee": 3.8, "currency": "USD", "createdAt": "2026-05-28T12:54:47+00:00", "description": "Payment for message from Fan XX", "status": "loading", "payoutPendingDays": 7, "user": { "id": 100000005, "name": "Fan XX", "username": "u100000005", "displayName": "Fan XX", "view": "t", "isVerified": false, "isDeleted": false, "isActive": true, "avatar": null, "avatarThumbs": null } } ], "marker": 1779973132, "hasMore": true, "nextMarker": 1779966690 }, "_pagination": { "next_page": "/v1/100000001/earnings?start_date=2025-09-17%2004%3A23%3A50&marker=1779966690" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Chat Overview Section: API Reference › Chat. Page: https://api-docs.fansmetric.com/api-reference/chat/overview Returns the 11-stat chat performance headline for an account over a date window — the current value, the previous window's value, and the percent change for each stat. Pair with [Chat Chart](https://api-docs.fansmetric.com/api-reference/chat/chart) to draw a trend line for any single stat. **Endpoint:** `GET /v1/{account_id}/chat/overview` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_chat_read_overview` Chat KPIs for a window, with previous-window deltas. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `from` | query | no | | Window start (UTC). Default 30 days ago. Accepts ISO 8601 (`2026-07-08T00:00:00Z`) or relative shorthand (`-30days`, `-24h`). | | `to` | query | no | | Window end (UTC). Default now. Must be after `from`. | | `revenue_type` | query | no | | `net` (default) or `gross`. Applies to `tips`, `messages`, `chatearnings`, `averagetip`, `averagemessage`. Count stats ignore this. `monthlychatearnings` and `chatafv` are always net. | ## Notes The 11 stats are always returned in this order — index by position if it helps: `outgoingmessages`, `monthlychattingfans`, `monthlychatearnings`, `chatafv`, `chatearnings`, `averagetip`, `averagemessage`, `tips`, `messages`, `tipscount`, `messagescount`. The previous window is the same-length span immediately before `from`. On the default 30-day window, that's days -60 to -30. `change` is a decimal (`0.25` = +25%). If you want a whole-number percent for display, multiply by 100. For a per-bucket time-series on any single stat, use [Chat Chart](https://api-docs.fansmetric.com/api-reference/chat/chart). Currency amounts are in the account's payout currency. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.metrics[]` | array | The 11 stats, always in the same fixed order — see Behavior below for the list. | | `data.metrics[].stat` | string | Machine-readable stat key. | | `data.metrics[].statHuman` | string | Human-readable label (e.g. `"Tips ($)"`). | | `data.metrics[].description` | string | One-line explanation of the stat. | | `data.metrics[].current` | number | Value over the requested window. | | `data.metrics[].previous` | number | Value over the same-length window immediately before `from`. | | `data.metrics[].change` | number | `(current − previous) / previous` as a decimal (0.25 = +25%). `0` when `previous` is 0. | | `data.metrics[].symbol` | string | `$`, `%`, or empty (for count stats). | | `data.metrics[].valueIsInteger` | boolean | Render hint — whether to drop decimals. | | `data.metrics[].symbolFirst` | boolean | Render hint — put `symbol` before the value (`$100`) vs after (`100%`). | | `data.metrics[].positiveIsGood` | boolean | Render hint — colour a positive `change` as good vs bad. | | `data.from` | string | Resolved window start (RFC 3339 UTC). | | `data.to` | string | Resolved window end (RFC 3339 UTC). | | `data.revenueType` | string | Echoes the effective revenue variant. | ## Example response (200) ```json { "data": { "metrics": [ { "stat": "outgoingmessages", "statHuman": "Outgoing Messages", "description": "The number of outgoing messages sent by your chatters.", "current": 48210, "previous": 41805, "change": 0.1532, "symbol": "", "valueIsInteger": true, "symbolFirst": true, "positiveIsGood": true }, { "stat": "chatearnings", "statHuman": "Chat Earnings", "description": "Earnings from tips and PPV message unlocks for the window.", "current": 82441.28, "previous": 74991.10, "change": 0.0993, "symbol": "$", "valueIsInteger": false, "symbolFirst": true, "positiveIsGood": true }, { "stat": "tips", "statHuman": "Tips ($)", "description": "Earnings from tips for the window.", "current": 21440.16, "previous": 19052.32, "change": 0.1253, "symbol": "$", "valueIsInteger": false, "symbolFirst": true, "positiveIsGood": true } ], "from": "2026-07-11T00:00:00Z", "to": "2026-08-10T00:00:00Z", "revenueType": "net" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Chat Chart Section: API Reference › Chat. Page: https://api-docs.fansmetric.com/api-reference/chat/chart Returns a time-series for one chat stat over the requested window, with per-bucket values for both the current window and the previous window (same length, immediately before). Use for line/bar charts. For the full 11-stat headline card in a single call, use [Chat Overview](https://api-docs.fansmetric.com/api-reference/chat/overview). **Endpoint:** `GET /v1/{account_id}/chat/chart` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_chat_read_chart` Time-series for one chat stat with a previous-window overlay. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `stat` | query | yes | | Which stat to chart. One of `outgoingmessages`, `monthlychattingfans`, `monthlychatearnings`, `chatafv`, `chatearnings`, `averagetip`, `averagemessage`, `tips`, `messages`, `tipscount`, `messagescount`. | | `from` | query | no | | Window start (UTC). Default 30 days ago. Accepts ISO 8601 or relative shorthand (`-30days`). | | `to` | query | no | | Window end (UTC). Default now. Must be after `from`. | | `granularity` | query | no | | Bucket size — `hour`, `day`, `week`, or `month`. Defaults: `hour` under a day, `month` over four months, otherwise `day`. `monthlychatearnings`, `monthlychattingfans`, and `chatafv` are day-only; other granularities are treated as `day` on those stats. | | `revenue_type` | query | no | | `net` (default) or `gross`. Same semantics as [Chat Overview](https://api-docs.fansmetric.com/api-reference/chat/overview). Ignored for count stats and for always-net rolling stats. | ## Notes `chartValues` and `chartValuesPrevious` are always the same length and align by index — pair them positionally for an overlay chart. `granularity=hour` on a 30-day window returns 720 buckets. Consider what your chart can render before asking for it. For rolling stats (`monthlychatearnings`, `monthlychattingfans`, `chatafv`), `current`/`previous` are the last/first bucket values, not sums — matching how those stats appear on FansMetric summary cards. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.stat` | string | Echoes the requested stat. | | `data.statHuman` | string | Human-readable label. | | `data.description` | string | One-line explanation of the stat. | | `data.granularity` | string | Resolved bucket size. | | `data.chartLabels[]` | array | RFC 3339 UTC timestamps at the start of each current-window bucket. | | `data.chartValues[]` | array | Per-bucket values for the current window. Empty buckets are zero-filled. | | `data.chartValuesPrevious[]` | array | Per-bucket values for the previous window (same length, aligned index-by-index with `chartValues`). | | `data.current` | number | Summary for the current window. Sum of `chartValues` for most stats; last value for rolling stats (`monthlychatearnings`, `monthlychattingfans`, `chatafv`). | | `data.previous` | number | Summary for the previous window (same rule as `current`). | | `data.change` | number | `(current − previous) / previous` as a decimal. `0` when `previous` is 0. | | `data.symbol` | string | `$`, `%`, or empty. | | `data.valueIsInteger` | boolean | Render hint. | | `data.symbolFirst` | boolean | Render hint. | | `data.positiveIsGood` | boolean | Render hint. | | `data.from` | string | Bucket-aligned start of the current window (RFC 3339 UTC). May be snapped to the bucket boundary — e.g. `2026-07-15T14:32:00Z` at `day` becomes `2026-07-15T00:00:00Z`. | | `data.to` | string | Bucket-aligned end of the current window. | | `data.revenueType` | string | Echoes the effective revenue variant. | ## Example response (200) ```json { "data": { "stat": "chatearnings", "statHuman": "Chat Earnings", "description": "Earnings from tips and PPV message unlocks, bucketed.", "granularity": "day", "chartLabels": [ "2026-08-04T00:00:00Z", "2026-08-05T00:00:00Z", "2026-08-06T00:00:00Z", "2026-08-07T00:00:00Z", "2026-08-08T00:00:00Z", "2026-08-09T00:00:00Z", "2026-08-10T00:00:00Z" ], "chartValues": [11482.10, 10940.32, 9821.05, 12211.78, 13045.20, 8791.44, 10990.00], "chartValuesPrevious": [ 9821.32, 10012.55, 10488.10, 11201.44, 11890.02, 9020.10, 9975.60], "current": 77281.89, "previous": 72409.13, "change": 0.0673, "symbol": "$", "valueIsInteger": false, "symbolFirst": true, "positiveIsGood": true, "from": "2026-08-04T00:00:00Z", "to": "2026-08-11T00:00:00Z", "revenueType": "net" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Chatters Section: API Reference › Chatters. Page: https://api-docs.fansmetric.com/api-reference/chatters/list Returns a paginated list of chatters in your organization, with each user's roles and team memberships included on every row. Use to populate chatter-selector dropdowns before hitting [Compare Chatters](https://api-docs.fansmetric.com/api-reference/chatters/compare) or [Chatter Report](https://api-docs.fansmetric.com/api-reference/chatters/report). **Endpoint:** `GET /v1/chatters` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_chat_chatters_list` Paginated list of org members with roles and teams. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `team_ids` | query | no | | Comma-separated team UUIDs. Filters to users in any of these teams (OR). Omit for every user in the org. | | `include_deactivated` | query | no | boolean | `true` to include deactivated members. Default `false`. | | `limit` | query | no | | Page size. Default `100`, max `500`. | | `offset` | query | no | | Number of rows to skip. Default `0`. | ## Notes Sorted by name ascending. Order is stable across pages, so `limit`/`offset` are safe to page with. `team_ids` is OR-logic — passing multiple UUIDs returns users in any of those teams, not the intersection. Roles and teams are included on every row; you do not need follow-up calls to enrich the list. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.chatters[]` | array | Users in this page, sorted by name ascending. | | `data.chatters[].id` | string | FansMetric user UUID. Pass this to Compare Chatters or Chatter Report. | | `data.chatters[].name` | string | Display name. | | `data.chatters[].email` | string | Sign-in email address. | | `data.chatters[].is_deactivated` | boolean | Whether the user is deactivated in the org. | | `data.chatters[].roles[]` | array | Roles: `id`, `name`, `color` (hex or CSS colour for UI badges). | | `data.chatters[].teams[]` | array | Teams: `id`, `name`. | | `data.total` | integer | Total users matching the filters (across all pages). | | `data.limit` | integer | Effective page size. | | `data.offset` | integer | Effective offset. | ## Example response (200) ```json { "data": { "chatters": [ { "id": "b7a9e0f1-2fa4-4d0b-9c2a-6c4d0b41f2c7", "name": "Alex Chen", "email": "alex@example.com", "is_deactivated": false, "roles": [ { "id": "r_01", "name": "Chatter", "color": "#22c55e" }, { "id": "r_02", "name": "Team Lead", "color": "#3b82f6" } ], "teams": [ { "id": "t_01", "name": "Team A" } ] }, { "id": "c5d6e7f8-9012-3456-7890-abcdef012345", "name": "Jordan Rivera", "email": "jordan@example.com", "is_deactivated": false, "roles": [ { "id": "r_01", "name": "Chatter", "color": "#22c55e" } ], "teams": [] } ], "total": 247, "limit": 100, "offset": 0 }, "_pagination": { "next_page": "/v1/chatters?offset=100&limit=100" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Compare Chatters Section: API Reference › Chatters. Page: https://api-docs.fansmetric.com/api-reference/chatters/compare Returns per-chatter time-series across 11 chat performance stats for up to 5 chatters over a single window. Powers side-by-side comparison charts — every user shares the same bucket axis so their series overlay directly. **Endpoint:** `POST /v1/chatters/compare` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_chat_chatters_compare` Per-chatter time-series across 11 stats, up to 5 chatters per call. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `user_ids` | body | yes | | Array of FansMetric user UUIDs from [List Chatters](https://api-docs.fansmetric.com/api-reference/chatters/list). 1–5 per call — batch client-side if you need more. | | `account_ids` | body | yes | | Array of OnlyFans numeric account IDs (as strings). At least one. Every ID must belong to your org — unknown IDs return `404`. | | `from` | body | no | | Window start (UTC). Default 30 days ago. Accepts ISO 8601 or relative shorthand (`-30days`). | | `to` | body | no | | Window end (UTC). Default now. Must be after `from`. | | `team_ids` | body | no | | Array of team UUIDs. When set, every `user_ids` entry must also be a member of one of these teams — otherwise the call returns `404`. | | `granularity` | body | no | | Bucket size — `hour`, `day`, `week`, or `month`. Default derived from window length. | ## Request body example ```json { "from": "2026-07-11T00:00:00Z", "to": "2026-08-10T23:59:59Z", "user_ids": ["b7a9e0f1-2fa4-4d0b-9c2a-6c4d0b41f2c7", "c5d6e7f8-9012-3456-7890-abcdef012345"], "account_ids": ["100000001", "100000002"], "granularity": "day" } ``` ## Notes Up to 5 chatters per call. Any unknown `user_ids` (or missing team membership when `team_ids` is set) returns `404` with no partial results. Every user shares the same `chartLabels` axis at the response's granularity, so per-user series overlay directly without alignment work on the client. Revenue is reported net — a gross toggle is not currently available on this endpoint. If your accounts have no chat activity in the window, every user still comes back with zero-filled series so charts render. - At most 5 `user_ids` per call ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.chatters[]` | array | One entry per requested user, sorted by name (not input order — index by `user_id`). | | `data.chatters[].user_id` | string | FansMetric user UUID. | | `data.chatters[].user_name` | string | Display name. | | `data.chatters[].metrics` | object | Keyed by stat name. Keys: `tips_revenue`, `tips_count`, `unlocked_ppvs_revenue`, `unlocked_ppvs_count`, `all_messages_count`, `all_ppvs_count`, `fans_count`, `word_count`, `employee_sales`, `golden_ratio`, `unlock_ratio`. | | `data.chatters[].metrics..chartLabels` | array | RFC 3339 UTC bucket-start timestamps. Shared axis across every user in the response. | | `data.chatters[].metrics..chartValues` | array | Per-bucket values for this user + stat. Empty buckets are zero-filled. | | `data.chatters[].metrics..statHuman` | string | Human-readable label. | | `data.chatters[].metrics..description` | string | One-line explanation of the stat. | | `data.chatters[].metrics..symbol` | string | `$`, `%`, or empty. | | `data.chatters[].metrics..valueIsInteger` | boolean | Render hint. | | `data.chatters[].metrics..symbolFirst` | boolean | Render hint. `false` for `%` stats. | | `data.chatters[].metrics..positiveIsGood` | boolean | Render hint. | | `data.chatters[].metrics..granularity` | string | Bucket size for this series. | | `data.from` | string | Bucket-aligned window start (RFC 3339 UTC). | | `data.to` | string | Bucket-aligned window end (RFC 3339 UTC). | | `data.granularity` | string | Bucket size for the response. | ## Example response (200) ```json { "data": { "chatters": [ { "user_id": "b7a9e0f1-2fa4-4d0b-9c2a-6c4d0b41f2c7", "user_name": "Alex Chen", "metrics": { "employee_sales": { "stat": "employee_sales", "statHuman": "Employee Sales", "description": "Total revenue from tips and unlocked PPVs sent on each day", "chartLabels": ["2026-08-08T00:00:00Z", "2026-08-09T00:00:00Z", "2026-08-10T00:00:00Z"], "chartValues": [1240.55, 985.10, 1502.20], "symbol": "$", "valueIsInteger": false, "symbolFirst": true, "positiveIsGood": true, "granularity": "day" }, "golden_ratio": { "stat": "golden_ratio", "statHuman": "Golden Ratio", "description": "Percentage of PPVs sent to messages sent on each day", "chartLabels": ["2026-08-08T00:00:00Z", "2026-08-09T00:00:00Z", "2026-08-10T00:00:00Z"], "chartValues": [12.4, 10.8, 14.1], "symbol": "%", "valueIsInteger": false, "symbolFirst": false, "positiveIsGood": true, "granularity": "day" } } }, { "user_id": "c5d6e7f8-9012-3456-7890-abcdef012345", "user_name": "Jordan Rivera", "metrics": { "employee_sales": { "stat": "employee_sales", "statHuman": "Employee Sales", "description": "Total revenue from tips and unlocked PPVs sent on each day", "chartLabels": ["2026-08-08T00:00:00Z", "2026-08-09T00:00:00Z", "2026-08-10T00:00:00Z"], "chartValues": [980.20, 1105.00, 1220.65], "symbol": "$", "valueIsInteger": false, "symbolFirst": true, "positiveIsGood": true, "granularity": "day" } } } ], "from": "2026-07-11T00:00:00Z", "to": "2026-08-11T00:00:00Z", "granularity": "day" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Chatter Report Section: API Reference › Chatters. Page: https://api-docs.fansmetric.com/api-reference/chatters/report Returns a paginated per-chatter aggregate table across the window, plus an `aggregate` totals row that spans every chatter (not just the current page). Companion to [Compare Chatters](https://api-docs.fansmetric.com/api-reference/chatters/compare) — same data, tabular shape instead of time-series. **Endpoint:** `POST /v1/chatters/report` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_chat_chatters_report` Paginated per-chatter aggregates plus a full-set totals row. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_ids` | body | yes | | Array of OnlyFans numeric account IDs (as strings). At least one. Every ID must belong to your org. | | `from` | body | no | | Window start (UTC). Default 30 days ago. | | `to` | body | no | | Window end (UTC). Default now. Must be after `from`. | | `team_ids` | body | no | | Array of team UUIDs. Restricts the report to users in any of these teams. | | `limit` | body | no | | Page size. Default `100`, max `500`. | | `offset` | body | no | | Rows to skip. Default `0`. | | `compare_to_previous` | body | no | | `true` (default) to include `*_prev` fields on each row for the same-length window immediately before `from`. Set `false` for a faster response. | | `skip_revenue_stats` | body | no | | `true` to return only `hours_worked` and `messages_sent` per row — no revenue, PPV, tips, or previous-window compare. Use for fast roster listings. Default `false`. | ## Request body example ```json { "from": "2026-07-11T00:00:00Z", "to": "2026-08-10T23:59:59Z", "account_ids": ["100000001", "100000002"], "limit": 100, "offset": 0, "compare_to_previous": true } ``` ## Notes Sorted by `all_earnings` descending, stable across pages. `data.aggregate` totals every chatter in the result set — not just the current page — so paginated callers still see the org total. Only chatters active in the current window appear. Users active only in the previous window are excluded. Set `skip_revenue_stats=true` for a fast roster listing with only `hours_worked` and `messages_sent`. Revenue is reported net — a gross toggle is not currently available on this endpoint. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.chatters[]` | array | Rows in this page, sorted by `all_earnings` descending. | | `data.chatters[].id` | string | FansMetric user UUID. | | `data.chatters[].email` | string | Sign-in email. | | `data.chatters[].name` | string | Display name. | | `data.chatters[].roles` | array | Roles (`id`, `name`, `color`). | | `data.chatters[].hours_worked` | integer | Hours the chatter was clocked in during the window. | | `data.chatters[].messages_sent` | integer | Total messages sent (text + PPV). | | `data.chatters[].unique_messaged_fans` | integer | Distinct fans the chatter messaged. | | `data.chatters[].unique_fans` | integer | Distinct fans that responded to or interacted with this chatter. | | `data.chatters[].all_earnings` | number | Total attributed revenue (`tips_revenue + ppvs_revenue`, net). In the account's payout currency. | | `data.chatters[].tips_revenue` | number | Net tips revenue attributed to this chatter. | | `data.chatters[].tips_count` | integer | Number of tips. | | `data.chatters[].ppvs_revenue` | number | Net revenue from unlocked PPVs attributed to this chatter. | | `data.chatters[].ppvs_count` | integer | Number of PPV messages sent. | | `data.chatters[].unlocked_ppvs_count` | integer | Number of PPVs that were unlocked. | | `data.chatters[].golden_ratio` | number | `(ppvs_count / messages_sent) × 100`, rounded to 2 decimals. `0` when `messages_sent` is 0. | | `data.chatters[].unlock_ratio` | number | `(unlocked_ppvs_count / ppvs_count) × 100`, rounded to 2 decimals. `0` when `ppvs_count` is 0. | | `data.chatters[].chargebacks_total` | number | Sum of chargeback amounts on this chatter's transactions. | | `data.chatters[].chargebacks_count` | integer | Number of chargebacks. | | `data.chatters[]._prev` | any | Every current-window field is repeated with a `_prev` suffix for the same-length window immediately before `from`. Present only when `compare_to_previous=true`. | | `data.aggregate` | object | Totals across every row in the result set (not just the current page). Same fields as `data.chatters[]` minus identity. Ratios are re-derived from the summed numerators/denominators. | | `data.total` | integer | Total rows across all pages. | | `data.limit` | integer | Effective page size. | | `data.offset` | integer | Effective offset. | | `data.from` | string | Resolved window start (RFC 3339 UTC). | | `data.to` | string | Resolved window end (RFC 3339 UTC). | ## Example response (200) ```json { "data": { "chatters": [ { "id": "b7a9e0f1-2fa4-4d0b-9c2a-6c4d0b41f2c7", "email": "alex@example.com", "name": "Alex Chen", "roles": [ { "id": "r_02", "name": "Team Lead", "color": "#3b82f6" } ], "hours_worked": 168, "messages_sent": 9421, "unique_messaged_fans": 812, "unique_fans": 744, "all_earnings": 38214.72, "tips_revenue": 10442.10, "tips_count": 321, "ppvs_revenue": 27772.62, "ppvs_count": 1520, "unlocked_ppvs_count": 842, "golden_ratio": 16.13, "unlock_ratio": 55.39, "chargebacks_total": 124.50, "chargebacks_count": 3, "hours_worked_prev": 160, "messages_sent_prev": 8801, "unique_messaged_fans_prev": 780, "unique_fans_prev": 701, "all_earnings_prev": 35218.90, "tips_revenue_prev": 9812.20, "tips_count_prev": 302, "ppvs_revenue_prev": 25406.70, "ppvs_count_prev": 1441, "unlocked_ppvs_count_prev": 790, "golden_ratio_prev": 16.37, "unlock_ratio_prev": 54.82, "chargebacks_total_prev": 98.00, "chargebacks_count_prev": 2 }, { "id": "c5d6e7f8-9012-3456-7890-abcdef012345", "email": "jordan@example.com", "name": "Jordan Rivera", "roles": [ { "id": "r_01", "name": "Chatter", "color": "#22c55e" } ], "hours_worked": 120, "messages_sent": 6540, "unique_messaged_fans": 512, "unique_fans": 488, "all_earnings": 21445.10, "tips_revenue": 5210.30, "tips_count": 184, "ppvs_revenue": 16234.80, "ppvs_count": 980, "unlocked_ppvs_count": 541, "golden_ratio": 14.98, "unlock_ratio": 55.20, "chargebacks_total": 0, "chargebacks_count": 0 } ], "aggregate": { "hours_worked": 288, "messages_sent": 15961, "unique_messaged_fans": 1324, "unique_fans": 1232, "all_earnings": 59659.82, "tips_revenue": 15652.40, "tips_count": 505, "ppvs_revenue": 44007.42, "ppvs_count": 2500, "unlocked_ppvs_count": 1383, "golden_ratio": 15.66, "unlock_ratio": 55.32, "chargebacks_total": 124.50, "chargebacks_count": 3 }, "total": 47, "limit": 100, "offset": 0, "from": "2026-07-11T00:00:00Z", "to": "2026-08-10T23:59:59Z" }, "_pagination": { "next_page": null }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Top Highlights Section: API Reference › Highlights. Page: https://api-docs.fansmetric.com/api-reference/highlights/top Returns the single top-performing record per metric for a content category over a date window — the post / message / stream / story / fan that scored highest on each leaderboard slot. The "highlights" view used to populate the OnlyFans "Top of period" cards. **Endpoint:** `GET /v1/{account_id}/highlights/{category}` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_highlights_read` Returns the top record per metric for one content category. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `category` | path | yes | | One of `post`, `message`, `stream`, `story`, `fan`. | | `start_date` | query | no | | Window start. Default 2 years ago, UTC. Format `YYYY-MM-DD HH:MM:SS` or ISO 8601. | | `end_date` | query | no | | Window end. Default end of today, UTC. Same format as `start_date`. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/users/me/stats/top/{category}?startDate=…&endDate=…` (with `skip_users=all` auto-appended for `category=post`). A single record can win multiple slots — e.g. one post topping both `purchases` and `views`. The response will repeat the same object under each key. `category=fan` returns full user objects; the `subscribedOnData.*Summ` totals are **lifetime**, not windowed — the window only chooses which fan tops each lane. `category=stream` returns the all-null shape (not a 404) for non-streaming accounts so callers can render a uniform layout. `category=story` omits the `purchases` slot. Media `files.*.url` are signed + IP-bound (≈24h expiry) and will not work from a different IP than the caller. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.purchases` | object\|null | Top record by purchases (PPV/post unlocks). `null` if no data in window. Omitted for `category=story` (stories aren't purchasable). | | `data.tips` | object\|null | Top record by tips. `null` if no tips in window. | | `data.views` | object\|null | Top record by views. `null` if no data. | | `data.likes` | object\|null | Top record by likes. | | `data.comments` | object\|null | Top record by comments. | | `data.` | object | For `category=fan`, slots are `total`, `subscriptions`, `tips`, `messages`, `streams`. Each is a full user object with `subscribedOnData` containing per-revenue-stream lifetime sums. | ## Example response (200) ```json { "data": { "purchases": { "id": 2155691024, "postedAt": "2025-12-17T03:05:15+00:00", "rawText": "New set out now", "price": 9.99, "stats": { "lookCount": 8810, "uniqueLookCount": 4947, "likeCount": 666, "commentCount": 0, "purchasedCount": 41, "purchasedSumm": 409.59, "tipCount": 0, "tipSum": 0 }, "media": [] }, "tips": null, "views": null, "likes": null, "comments": null }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Top Posts by Engagement Section: API Reference › Engagement. Page: https://api-docs.fansmetric.com/api-reference/engagement/top-posts Returns a paginated leaderboard of top-performing posts ranked by a single engagement metric. Unlike `/highlights/post` (one top post per metric, no pagination), this returns the full ranked list for one metric. **Endpoint:** `GET /v1/{account_id}/engagement/posts/{by}` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_engagement_list_posts` Lists posts ranked by one engagement metric, with offset pagination. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `by` | path | yes | | Ranking metric. One of `comments`, `likes`, `views`, `tips`, `purchases`. | | `start_date` | query | no | | Window start. Default 2 years ago, UTC. | | `end_date` | query | no | | Window end. Default end of today, UTC. | | `offset` | query | no | | Rows to skip. Page size is fixed at 10. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/posts/top?startDate=…&endDate=…&by=…&offset=…&skip_users=all`. `skip_users=all` is appended upstream automatically — the response carries post objects, not the engaging users. Page size is fixed by OnlyFans at **10**. The response key is `items` (not `list`) — this is the only endpoint that uses that name. Don't generalize a `list`-only post-processor for this route. A post that wins multiple `by` rankings will appear in each leaderboard. Deduplicate by `id` across metrics. Media URLs are signed + IP-bound (≈24h expiry). Use [`/highlights/post`](https://api-docs.fansmetric.com/api-reference/highlights/top) for a single "top of period" record per metric. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.items[]` | array | Post objects in this page, ranked by `{by}` (descending). Note the key is `items` — not `list` — and is passed through verbatim from OnlyFans. | | `data.items[].id` | integer | OnlyFans post ID. | | `data.items[].postedAt` | string | ISO 8601 publish time. | | `data.items[].text` | string | HTML post body. | | `data.items[].rawText` | string | Plain-text post body. | | `data.items[].mediaCount` | integer | Number of media attachments. | | `data.items[].price` | number | Unlock price for PPV posts. Absent on free posts. | | `data.items[].isPinned` | boolean | `true` if pinned to the top of the feed. | | `data.items[].stats` | object | `lookCount`, `uniqueLookCount`, `likeCount`, `commentCount`, `tipCount`, `tipSum`, `purchasedCount`, `purchasedSumm`. | | `data.items[].media` | array | Media attachments: `id`, `type`, `files.{full,thumb,preview,squarePreview}`, `duration`, `videoSources.{240,720}` for videos. | | `data.hasMore` | boolean | Whether more pages are available. | ## Example response (200) ```json { "data": { "hasMore": true, "items": [ { "id": 2155691024, "postedAt": "2025-12-17T03:05:15+00:00", "rawText": "New set out now", "favoritesCount": 666, "mediaCount": 1, "isPinned": false, "stats": { "lookCount": 8810, "uniqueLookCount": 4947, "likeCount": 666, "commentCount": 0, "tipCount": 0, "tipSum": 0, "purchasedCount": 0, "purchasedSumm": 0 }, "media": [] } ] }, "_pagination": { "next_page": "/v1/100000001/engagement/posts/likes?start_date=2025-09-17%2004%3A23%3A50&end_date=2026-05-28%2013%3A22%3A18&offset=10" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Top Stories by Engagement Section: API Reference › Engagement. Page: https://api-docs.fansmetric.com/api-reference/engagement/top-stories Paginated leaderboard of top-performing stories by a single engagement metric. Parallel to List Top Posts — same shape, same pagination, but for stories. Stories aren't purchasable, so `by=purchases` is not valid here. **Endpoint:** `GET /v1/{account_id}/engagement/stories/{by}` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_engagement_list_stories` Lists stories ranked by one engagement metric, with offset pagination. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `by` | path | yes | | Ranking metric. One of `tips`, `views`, `likes`, `comments`. | | `start_date` | query | no | | Window start. Default 2 years ago, UTC. | | `end_date` | query | no | | Window end. Default end of today, UTC. | | `offset` | query | no | | Rows to skip. Page size is fixed at 10. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/stories/top?startDate=…&endDate=…&by=…&offset=…`. Unlike `/posts/top`, this endpoint does **not** receive `skip_users=all` upstream — the OF web UI doesn't send it for stories. Page size is fixed at 10. The embedded `viewers` array is a preview (first few). Fetch the full paginated list with [`/v1/{account_id}/stories/{story_id}/viewers`](https://api-docs.fansmetric.com/api-reference/engagement/list-story-viewers). ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.items[]` | array | Story objects, ranked by `{by}` descending. | | `data.items[].id` | integer | OnlyFans story ID. | | `data.items[].userId` | integer | The creator's user ID (always the queried account). | | `data.items[].createdAt` | string | ISO 8601 publish time. | | `data.items[].media` | array | Story media (typically 1 entry). Same media shape as posts. | | `data.items[].tipsAmount` | string | Formatted total tips (e.g. `"$200"`). | | `data.items[].tipsAmountRaw` | number | Numeric total tips. | | `data.items[].tipsCount` | integer | Number of distinct tippers. | | `data.items[].likesCount` | integer | Likes. | | `data.items[].commentsCount` | integer | Comments. | | `data.items[].viewersCount` | integer | Total viewers. | | `data.items[].viewers` | array | Preview of viewer user objects (first 4-5). Use List Story Viewers for the full paginated list. | | `data.items[].isHighlightCover` | boolean | `true` if this story is the cover of a saved highlight. | | `data.items[].isLastInHighlight` | boolean | `true` if this is the final story in its highlight. | | `data.hasMore` | boolean | Whether more pages are available. | ## Example response (200) ```json { "data": { "hasMore": true, "items": [ { "id": 94660491, "userId": 100000001, "createdAt": "2026-05-27T13:00:00+00:00", "media": [], "tipsAmount": "$200", "tipsAmountRaw": 200, "tipsCount": 8, "likesCount": 412, "commentsCount": 17, "viewersCount": 9821, "viewers": [], "isHighlightCover": false, "isLastInHighlight": false } ] }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Story Viewers Section: API Reference › Engagement. Page: https://api-docs.fansmetric.com/api-reference/engagement/list-story-viewers Returns the paginated list of users who viewed a specific story. Pass `only_with_tips=true` to materialize a tipper-only list. **Endpoint:** `GET /v1/{account_id}/stories/{story_id}/viewers` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_stories_list_viewers` Lists viewers of a single story, optionally filtered to tippers. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `story_id` | path | yes | | Story ID (from `engagement/stories/{by}` or `highlights/story`). | | `limit` | query | no | | Page size. Default 10. Min 1, max 100. | | `offset` | query | no | | Rows to skip. | | `only_with_tips` | query | no | | `true` or `1` to narrow to viewers who tipped on the story. Forwarded upstream as `onlyWithTips=true`. Other values (including `false`) are treated as omitted. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/stories/{story_id}/viewers?limit=…&offset=…[&onlyWithTips=true]`. `only_with_tips=true` accepts the strings `"true"` or `"1"`. Other values are treated as omitted. Subscription-state fields (`subscribedBy`, `subscribedOn`, `subscribedByExpireDate`, …) match the rest of the user-list endpoints — useful for joining viewer engagement to subscription tenure. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[]` | array | Viewer rows. | | `data.list[].id` | integer | Viewer user ID. | | `data.list[].username` | string | Viewer username. | | `data.list[].name` | string | Display name. | | `data.list[].view` | string | `"s"` — viewer-scoped projection. | | `data.list[].isStoryLiked` | boolean | Whether this viewer liked the story. | | `data.list[].isStoryBlockedUser` | boolean | Whether the creator has blocked this user from viewing stories. | | `data.list[].hasStoryTips` | boolean | Whether this viewer tipped on the story. | | `data.list[].hasTopStoryTips` | boolean | Whether this viewer is among the top tippers on the story. | | `data.list[].subscribedBy` | boolean | Whether the calling account subscribes to this viewer. | | `data.list[].subscribedOn` | boolean | Whether the viewer subscribes to the calling account. | | `data.list[].lastSeen` | string\|null | Last-seen timestamp on the platform (not story-specific). | | `data.hasMore` | boolean | Whether more pages are available. | ## Example response (200) ```json { "data": { "hasMore": true, "list": [ { "id": 100000006, "username": "u100000006", "name": "Fan XX", "view": "s", "isStoryLiked": false, "isStoryBlockedUser": false, "hasStoryTips": false, "hasTopStoryTips": false, "subscribedBy": true, "subscribedByExpire": false, "subscribedOn": true, "lastSeen": "2026-09-01T18:30:00+00:00", "listsStates": [] } ] }, "_pagination": { "next_page": "/v1/100000001/stories/94660491/viewers?limit=10&offset=10" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Profile Visitors Overview Section: API Reference › Reach. Page: https://api-docs.fansmetric.com/api-reference/reach/profile-visitors Full "Profile Visitors" reach payload — top countries + duration users + visitors/duration chart + total counter — in one response. For a smaller card-shaped summary, use Earnings Overview with `by=visitors`. **Endpoint:** `GET /v1/{account_id}/reach/profile-visitors` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_reach_read_profile_visitors` Returns the combined Profile Visitors reach payload. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `start_date` | query | no | | Window start. Default 2 years ago, UTC. | | `end_date` | query | no | | Window end. Default end of today, UTC. | | `by` | query | no | | Bucket used to rank `topCountries`. Values: `total` (default), `guests`, `users`, `subscribers`. | | `limit` | query | no | | Top-N rows in `topCountries`. Default 10. Capped at 100. Pass `0` for upstream default. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/users/me/profile/stats?startDate=…&endDate=…&limit=…&by=…`. `duration` is in **seconds**. Convert before display (`/60` for minutes, `/3600` for hours). Quirk: `topCountries.totals.guests` / `topCountries.totals.users` come back as **strings** while `total` / `subscribers` are numbers. Parse defensively. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.isAvailable` | boolean | `true` when reach analytics is enabled for the account. | | `data.hasStats` | boolean | `true` when there's data for the window. | | `data.topCountries` | object | Country leaderboard. See the dedicated countries endpoint for field details. | | `data.topDurationUsers` | object | Total time-on-profile breakdown (in **seconds**). Same `totals` shape as `topCountries`. | | `data.chart.visitors` | array | Monthly `{ date, count }` visitor count. | | `data.chart.duration` | array | Monthly `{ date, count }` total time on profile, in **seconds**. | | `data.total.current` | string | Window-total visitor count. **Returned as a string.** | | `data.total.delta` | integer | Percent change vs the prior equal-length window. Saturates at `100`. | ## Example response (200) ```json { "data": { "isAvailable": true, "hasStats": true, "topCountries": { "hasMore": true, "totals": { "total": 2581195, "guests": "22445", "users": "2558750", "subscribers": 0 }, "rows": [] }, "topDurationUsers": { "totals": { "total": 17803159, "guests": "258154", "users": "17545005", "subscribers": 0 } }, "chart": { "visitors": [ { "date": "2025-09-01T00:00:00+00:00", "count": 19922 } ], "duration": [ { "date": "2025-09-01T00:00:00+00:00", "count": 116885 } ] }, "total": { "current": "2581195", "delta": 100 } }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Profile Visitors Top Countries Section: API Reference › Reach. Page: https://api-docs.fansmetric.com/api-reference/reach/profile-visitors-countries Ranked country breakdown of profile-page visits — guests + signed-in users + paying subscribers — with an `Others` rollup row. **Endpoint:** `GET /v1/{account_id}/reach/profile-visitors/countries` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_reach_read_profile_visitors_countries` Returns the top-countries leaderboard for profile visitors. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `start_date` | query | no | | Window start. Default 2 years ago, UTC. | | `end_date` | query | no | | Window end. Default end of today, UTC. | | `by` | query | no | | Bucket: `total` (default), `guests`, `users`, `subscribers`. | | `limit` | query | no | | Top-N rows. Default 10. Capped at 100. | ## Notes Upstream OnlyFans endpoint: same `GET /api2/v2/users/me/profile/stats?…&filter[]=topCountries` as the other Profile Visitors endpoints — only the `filter[]` differs. The `Others` rollup is always last and uses an empty `countryCode`. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.topCountries.hasMore` | boolean | `true` if more country rows are aggregated into the `Others` rollup beyond the returned top-N. | | `data.topCountries.totals` | object | Account-wide totals across all countries. Quirk: `total` and `subscribers` are numbers, but `guests` and `users` come back as **strings**. | | `data.topCountries.rows[]` | array | Ranked country rows. The final row is always an `Others` rollup with `countryCode: ""`. | | `data.topCountries.rows[].rank` | integer | 1-based rank. `Others` gets `limit+1`. | | `data.topCountries.rows[].countryName` | string | Human-readable name. `"Others"` on the rollup row. | | `data.topCountries.rows[].countryCode` | string | ISO 3166-1 alpha-2. Empty string for `Others`. | | `data.topCountries.rows[].viewsCount` | object | Per-country `{ total, guests, users, subscribers }` — all numeric. | ## Example response (200) ```json { "data": { "isAvailable": true, "hasStats": true, "topCountries": { "hasMore": true, "totals": { "total": 2581195, "guests": "22445", "users": "2558750", "subscribers": 0 }, "rows": [ { "rank": 1, "countryName": "United States", "countryCode": "US", "viewsCount": { "total": 1407253, "guests": 11635, "users": 1395618, "subscribers": 0 } }, { "rank": 4, "countryName": "Others", "countryCode": "", "viewsCount": { "total": 862812, "guests": 8972, "users": 853840, "subscribers": 0 } } ] } }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Profile Visitors Chart Section: API Reference › Reach. Page: https://api-docs.fansmetric.com/api-reference/reach/profile-visitors-chart Monthly timeseries of visitor count and total time-on-profile, plus the window total. **Endpoint:** `GET /v1/{account_id}/reach/profile-visitors/chart` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_reach_read_profile_visitors_chart` Returns the monthly visitors / duration chart for profile visitors. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `start_date` | query | no | | Window start. Default 2 years ago, UTC. | | `end_date` | query | no | | Window end. Default end of today, UTC. | | `by` | query | no | | Same bucket selector as the other Profile Visitors endpoints. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/users/me/profile/stats?…&filter[]=chart`. `hasStats` has been observed as `false` even on accounts with non-zero data — don't gate rendering on it. Trust the arrays. `duration` is in **seconds**. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.chart.visitors` | array | Monthly `{ date, count }` visitor count. `date` is the first-of-month timestamp (UTC). | | `data.chart.duration` | array | Monthly `{ date, count }` total time on profile, in **seconds**. | | `data.total.current` | string | Window-total visitor count. Returned as a **string** (e.g. `"2581195"`). | | `data.total.delta` | integer | Percent change vs the prior equal-length window. Saturates at `100`. | ## Example response (200) ```json { "data": { "isAvailable": true, "hasStats": false, "chart": { "visitors": [ { "date": "2025-09-01T00:00:00+00:00", "count": 19922 } ], "duration": [ { "date": "2025-09-01T00:00:00+00:00", "count": 116885 } ] }, "total": { "current": "2581195", "delta": 100 } }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Promotions Section: API Reference › Reach. Page: https://api-docs.fansmetric.com/api-reference/reach/list-promotions Returns the history of subscription promotions (discounted-price offers + free-trial bundles) the creator has run. Filterable by `createdAt` window. For aggregate promo earnings + a monthly chart, use Earnings Overview with `by=promo`. **Endpoint:** `GET /v1/{account_id}/reach/promotions` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_reach_list_promotions` Lists historical promotional offers with `createdAt` filtering and offset pagination. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `limit` | query | no | | Page size. Default 10. Min 1, max 100. | | `offset` | query | no | | Rows to skip. | | `start_date` | query | no | | Lower bound on `createdAt`. Default 2 years ago, UTC. | | `end_date` | query | no | | Upper bound on `createdAt`. Default end of today, UTC. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/promotions?offset=…&startDate=…&endDate=…&limit=…`. `start_date` / `end_date` filter on the promotion's `createdAt`, not `finishedAt`. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.items[].id` | integer | Promotion ID. Pass to `/reach/promotions/{promo_id}/subscribers` for the claim list. | | `data.items[].message` | string | Promo description shown to fans (HTML allowed; often empty). | | `data.items[].rawMessage` | string | Plain-text version of `message`. | | `data.items[].price` | number | Discounted subscription price during the promo. | | `data.items[].type` | string | Audience scope. Observed: `all`, `expired`. Other values may exist (`new`, `current`, …). | | `data.items[].canClaim` | boolean | `true` while the promo is still claimable. | | `data.items[].claimsCount` | integer | Number of fans who claimed/subscribed via this promo. | | `data.items[].subscribeDays` | integer | Subscribe-days bonus. `0` when the promo doesn't extend the term. | | `data.items[].createdAt` | string | ISO 8601 — when the promo was created. | | `data.items[].finishedAt` | string | ISO 8601 — when the promo expired/will expire. | | `data.items[].isFinished` | boolean | `true` once `finishedAt` has passed. | | `data.hasMore` | boolean | Whether more pages are available. | ## Example response (200) ```json { "data": { "hasMore": true, "items": [ { "id": 44934374, "message": "Half off your first month!", "rawMessage": "Half off your first month!", "hasRelatedPromo": false, "price": 4, "type": "all", "canClaim": false, "claimsCount": 3, "subscribeCounts": null, "subscribeDays": 0, "createdAt": "2025-02-21T05:53:48+00:00", "finishedAt": "2025-02-28T05:53:48+00:00", "isFinished": true } ] }, "_pagination": { "next_page": "/v1/100000002/reach/promotions?limit=10&offset=10" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Promotion Subscribers Section: API Reference › Reach. Page: https://api-docs.fansmetric.com/api-reference/reach/list-promotion-subscribers Returns the paginated list of subscribers who joined via a specific promotion. Each row is a full user profile with the discounted price, regular price, and lifetime spend totals. **Endpoint:** `GET /v1/{account_id}/reach/promotions/{promo_id}/subscribers` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_reach_list_promotion_subscribers` Lists subscribers who claimed a specific promotion. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `promo_id` | path | yes | | Promotion ID from `/reach/promotions`. | | `limit` | query | no | | Page size. Default 10. Min 1, max 100. | | `offset` | query | no | | Rows to skip. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/subscriptions/subscribers?limit=…&offset=…&format=infinite&filter[promoId]=…`. `format=infinite` and `filter[promoId]` are pinned server-side — callers can't accidentally drop the promo filter. `subscribedOnData.*Summ` totals are **lifetime**, not promo-attributed. To compute promo-attributable revenue, compare against `subscribeAt` and the promo's lifecycle. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[]` | array | Subscriber rows. Newest claims first. | | `data.list[].id` | integer | Subscriber user ID. | | `data.list[].username` | string | Subscriber username. | | `data.list[].subscribedOnData.price` | number | Discounted price the fan paid via this promo. | | `data.list[].subscribedOnData.regularPrice` | number | Normal subscription price (what they'd pay without the promo). | | `data.list[].subscribedOnData.subscribeAt` | string | When the fan subscribed (ISO 8601). | | `data.list[].subscribedOnData.expiredAt` | string | When their subscription expired. | | `data.list[].subscribedOnData.duration` | string | Human-readable subscription length (`"6 months"`, `"1 month"`, …). | | `data.list[].subscribedOnData.totalSumm` | number | Lifetime spend across tips, messages, posts, streams, subscriptions. | | `data.list[].promoOffers` | array | Other promos this user is eligible for. Often empty. | | `data.hasMore` | boolean | Whether more pages are available. | ## Example response (200) ```json { "data": { "hasMore": true, "list": [ { "id": 100000007, "username": "fan_XXXXX", "name": "Fan XX", "view": "x", "subscribedBy": true, "subscribedByExpireDate": "2035-10-08T02:34:38+00:00", "subscribedOnDuration": "6 months", "subscribedOnData": { "price": 9.99, "regularPrice": 14.99, "subscribeAt": "2025-10-08T02:34:37+00:00", "expiredAt": "2026-04-20T03:34:55+00:00", "duration": "6 months", "tipsSumm": 0, "subscribesSumm": 49.95, "messagesSumm": 25, "postsSumm": 0, "streamsSumm": 0, "totalSumm": 74.95, "lastActivity": "2026-03-20T03:34:55+00:00" }, "promoOffers": [] } ] }, "_pagination": { "next_page": "/v1/100000002/reach/promotions/52752862/subscribers?limit=10&offset=10" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Referred Users Section: API Reference › Referrals. Page: https://api-docs.fansmetric.com/api-reference/referrals/list-referred-users Returns users the creator has referred onto the platform. Toggle `only_performers` between referred creators (with per-creator `earnings`) and all referred users (creators + fans). **Endpoint:** `GET /v1/{account_id}/referrals` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_referrals_list_users` Lists referred users with optional `only_performers` narrowing. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `start_date` | query | no | | Lower bound on `joinDate`. Default 2 years ago, UTC. | | `end_date` | query | no | | Upper bound on `joinDate`. Default end of today, UTC. | | `offset` | query | no | | Rows to skip. Page size is set by OnlyFans. | | `only_performers` | query | no | | `1` (default) = referred creators only (rows include `earnings`). `0` = every referred user (creators + fans). | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/users/me/referrals?startDate=…&endDate=…&offset=…&onlyPerformers=…`. `earnings` is the **lifetime** referral commission — not scoped to the `start_date`/`end_date` window. The window only filters which referred users appear (by `joinDate`). Use [`/referrals/payouts`](https://api-docs.fansmetric.com/api-reference/referrals/list-payouts) for the time-windowed commission payouts. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[]` | array | Referred users in this page. | | `data.list[].id` | integer | OnlyFans user ID. | | `data.list[].username` | string | URL slug. | | `data.list[].name` | string | Display name (may include emoji). | | `data.list[].joinDate` | string | ISO 8601 — when this user signed up via the creator's referral link. | | `data.list[].earnings` | number | Only present when `only_performers=1`. Lifetime referral commission attributed to this referred creator. | | `data.list[].subscribedBy` | boolean | Whether the calling account currently subscribes to this referred creator. | | `data.list[].subscribedOn` | boolean | Whether this referred creator currently subscribes to the calling account. | | `data.list[].view` | string | `"ref"` for rows from this endpoint. | | `data.hasMore` | boolean | Whether more pages are available. | ## Example response (200) ```json { "data": { "list": [ { "id": 100000009, "name": "Creator XX", "username": "creator_XXXXX", "displayName": "", "isVerified": true, "isActive": true, "subscribePrice": 0, "currentSubscribePrice": 0, "subscribedBy": true, "subscribedOn": true, "subscribedOnDuration": "4 months", "subscribedByExpire": false, "subscribedByExpireDate": "2036-01-13T11:09:15+00:00", "subscribedByAutoprolong": true, "joinDate": "2025-12-18T15:17:18+00:00", "earnings": 412.5, "canEarn": true, "view": "ref", "listsStates": [] } ], "hasMore": false }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Referral Balance Section: API Reference › Referrals. Page: https://api-docs.fansmetric.com/api-reference/referrals/get-balance Returns the uncollected referral commission balance — earnings from referred creators that have accrued but not yet been disbursed as a referral payout. **Endpoint:** `GET /v1/{account_id}/referrals/balance` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_referrals_read_balance` Returns the pending referral commission balance. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/payments/referrals/balance`. This is the pending/uncollected total. For realized commission history, use [`/referrals/payouts`](https://api-docs.fansmetric.com/api-reference/referrals/list-payouts). For per-referred-creator totals, use [`/referrals?only_performers=1`](https://api-docs.fansmetric.com/api-reference/referrals/list-referred-users) and read `earnings` on each row. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.referralEarnings` | number | Accrued referral commission, in the account's payout currency. The pending amount that will be paid out at the next monthly referral disbursement. | ## Example response (200) ```json { "data": { "referralEarnings": 839.27 }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Referral Payouts Section: API Reference › Referrals. Page: https://api-docs.fansmetric.com/api-reference/referrals/list-payouts Returns the monthly referral commission payouts the creator has received — one row per disbursement. Same shape as `/payouts/requests` but scoped to referral commissions, not earnings withdrawals. **Endpoint:** `GET /v1/{account_id}/referrals/payouts` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_referrals_list_payouts` Lists referral commission disbursements with offset + marker pagination. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `start_date` | query | no | | Lower bound on `createdAt`. Default 2 years ago, UTC. | | `end_date` | query | no | | Upper bound on `createdAt`. Default end of today, UTC. | | `offset` | query | no | | Rows to skip. Page size is fixed at 10. | | `marker` | query | no | | Snapshot pin (unix seconds) from a prior response. Omit on the first page; pass back unchanged on subsequent pages. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/payouts/requests/referral?startDate=…&endDate=…&offset=…&marker=…`. Distinct from regular [`/payouts/requests`](https://api-docs.fansmetric.com/api-reference/payouts/list-requests) — that endpoint covers creator-earnings withdrawals; this one is the referral-commission disbursements. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[]` | array | Referral payouts in this page, newest first. | | `data.list[].invoiceId` | string | OnlyFans invoice ID for this referral payout. | | `data.list[].createdAt` | string | ISO 8601 timestamp of the payout. Referral commissions are paid monthly, so `createdAt` typically clusters on the 1st. | | `data.list[].amount` | number | Amount paid in `currency` units. | | `data.list[].currency` | string | ISO 4217 currency code. | | `data.list[].state` | string | Approval state. Observed: `approved`. Other expected values: `pending`, `rejected`, `processing`. | | `data.list[].rejectReason` | string\|null | Reject reason when `state == "rejected"`. `null` otherwise. | | `data.marker` | integer | Snapshot pin (unix seconds). Pass back on subsequent requests. | ## Example response (200) ```json { "data": { "list": [ { "invoiceId": "240825", "createdAt": "2026-05-01T15:58:51+00:00", "amount": 739, "currency": "USD", "state": "approved", "rejectReason": null } ], "marker": 1779974137 }, "_pagination": { "next_page": null }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Referral Payouts Chart Section: API Reference › Referrals. Page: https://api-docs.fansmetric.com/api-reference/referrals/payouts-chart Returns the referral-commission timeseries that backs the OnlyFans **Statements → Referrals** page — one $ series (`chartAmount`), one payout-count series (`chartCount`), net + gross totals, and OF's percent-change `delta` vs the previous equal-length window. Bucket granularity (daily vs monthly) is chosen by OnlyFans based on window length. **Endpoint:** `GET /v1/{account_id}/referrals/payouts/chart` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_referrals_read_chart` Returns referral commission $ and payout-count series with window net/gross totals and prior-period delta. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `start_date` | query | no | | Window start. Default 2 years ago, UTC. `YYYY-MM-DD HH:MM:SS` or ISO 8601 (the `T` separator is normalized to a space). | | `end_date` | query | no | | Window end. Default end of today, UTC. Same format as `start_date`. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/payouts/referrals/chart?startDate=…&endDate=…&withTotal=1&withChart=true&filter[chartAmount]=chartAmount&filter[chartCount]=chartCount`. Upstream quirk: this endpoint expects `withTotal=1` (not `true`) and is forwarded as-is. Field name `count` is shared by both series — it represents dollars in `chartAmount` and payout rows in `chartCount`. Bucket granularity is OF-controlled. Short windows return daily buckets; multi-month windows return monthly buckets aligned to the 1st-of-month UTC. For the combined (creator-earnings + referrals) chart, use [Get Payouts Chart](https://api-docs.fansmetric.com/api-reference/payouts/chart). For per-row referral payouts use [List Referral Payouts](https://api-docs.fansmetric.com/api-reference/referrals/list-payouts). ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.chartAmount[]` | array | One bucket per period in the window. `date` is midnight UTC ISO 8601 at the bucket start; `count` is the **net referral commission $** in that bucket (after platform fees), in the account's payout currency. | | `data.chartCount[]` | array | Same bucket alignment as `chartAmount`. `count` is the **number of referral payouts** in that bucket. | | `data.total` | number | **Net** referral commissions over the window — sum of `chartAmount[].count`. | | `data.gross` | number | **Gross** referral commissions over the window (before platform fees). | | `data.delta` | number | OF-computed change vs the immediately preceding equal-length window. Reported as a whole-number percent and saturates at `100` (treat ≥100 as "at least doubled"). | ## Example response (200) ```json { "data": { "chartAmount": [ { "date": "2025-09-01T00:00:00+00:00", "count": 0 }, { "date": "2025-10-01T00:00:00+00:00", "count": 482.31 } ], "chartCount": [ { "date": "2025-09-01T00:00:00+00:00", "count": 0 }, { "date": "2025-10-01T00:00:00+00:00", "count": 3 } ], "total": 4458.86, "gross": 5573.58, "delta": 100 }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Activity Streaks Section: API Reference › Streaks. Page: https://api-docs.fansmetric.com/api-reference/streaks/list-activity-streaks Returns the creator's activity streaks (consecutive-day runs of posting / streaming / messaging / story activity) that intersect a date window. The OF web UI calls this endpoint per calendar month — scan one month at a time to mirror that behavior. **Endpoint:** `GET /v1/{account_id}/streaks` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_streaks_list` Lists activity streaks overlapping the given window. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `start_date` | query | no | | Window start. Default first of current UTC month. | | `end_date` | query | no | | Window end. Default end of today, UTC. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/streaks?startDate=…&endDate=…`. The returned streak's `startDate`/`endDate` are **not** clipped to the requested window — they describe the full streak even if it extends outside the window. `daysCount`, `postsCount`, `storiesCount`, `chatsCount`, and `streamsDuration` are streak totals (lifetime of that streak), not window-scoped. `streamsDuration` is in seconds. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[]` | array | Streak records that overlap the window. Almost always 0 or 1. | | `data.list[].id` | integer | Upstream streak ID. | | `data.list[].startDate` | string | ISO 8601 — day the streak began. May predate `start_date` if the streak was already running when the window opened. | | `data.list[].endDate` | string | ISO 8601 — most recent day counted toward the streak. | | `data.list[].isActive` | boolean | `true` if the streak is still being maintained today. | | `data.list[].daysCount` | integer | Total number of days the streak has been active. | | `data.list[].postsCount` | integer | Posts published during the streak. | | `data.list[].storiesCount` | integer | Stories posted during the streak. | | `data.list[].chatsCount` | integer | Chat messages sent during the streak (DM activity counted toward the streak rules). | | `data.list[].streamsDuration` | integer | Total stream duration during the streak, in **seconds**. | | `data.list[].frozenDays` | array | Days the creator used a streak freeze to skip without breaking the streak. | | `data.hasMore` | boolean | Pagination flag from upstream. Observed `false` even on long windows — treat as a single-shot response. | ## Example response (200) ```json { "data": { "list": [ { "id": 614673203, "startDate": "2025-09-29T00:00:00+00:00", "endDate": "2026-05-27T00:00:00+00:00", "isActive": true, "postsCount": 5354, "daysCount": 241, "streamsDuration": 0, "storiesCount": 999, "chatsCount": 199152, "frozenDays": [] } ], "hasMore": false }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Top Streak Section: API Reference › Streaks. Page: https://api-docs.fansmetric.com/api-reference/streaks/get-top-streak Returns the creator's best streak — the longest run of activity, per OnlyFans's own ranking. Not date-windowed; always reports the single best streak of all time. **Endpoint:** `GET /v1/{account_id}/streaks/top` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_streaks_read_top` Returns the creator's best-ever activity streak. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/streaks/top`. No pagination, no date filter. If the returned streak is `isActive: true`, it's also the current streak; if not, it's the all-time best that has since been broken. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.id` | integer | Upstream streak ID. | | `data.startDate` | string | ISO 8601 — when the streak began. | | `data.endDate` | string | ISO 8601 — most recent day counted toward the streak. | | `data.isActive` | boolean | `true` if this streak is still being maintained today. | | `data.daysCount` | integer | Total days. | | `data.postsCount` | integer | Posts during the streak. | | `data.storiesCount` | integer | Stories during the streak. | | `data.chatsCount` | integer | DM messages during the streak. | | `data.streamsDuration` | integer | Total stream duration, in seconds. | | `data.frozenDays` | array | Streak-freeze days used. | ## Example response (200) ```json { "data": { "id": 614673203, "startDate": "2025-09-29T00:00:00+00:00", "endDate": "2026-05-27T00:00:00+00:00", "isActive": true, "postsCount": 5354, "daysCount": 241, "streamsDuration": 0, "storiesCount": 999, "chatsCount": 199152, "frozenDays": [] }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Payout Balances Section: API Reference › Payouts. Page: https://api-docs.fansmetric.com/api-reference/payouts/balances Returns the account's available and pending payout balances, currency, withdrawal limits, and the configured withdrawal cadence. **Endpoint:** `GET /v1/{account_id}/payouts/balances` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_payouts_read_balances` Returns payout balances and withdrawal limits. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/payouts/balances`. Pass-through from OnlyFans inside the standard `data` envelope. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.payoutAvailable` | number | Amount currently available to withdraw. | | `data.payoutPending` | number | Amount earned but not yet cleared for withdrawal. | | `data.currency` | string | ISO 4217 currency code (e.g. `USD`). | | `data.minPayoutSumm` | number | Minimum amount per withdrawal. | | `data.maxPayoutSumm` | number | Maximum amount per withdrawal (typically equals `payoutAvailable`). | | `data.withdrawalPeriodOptions[]` | array | Available payout cadences. Each entry has `code` and human-readable `name`. | | `data.manualPayoutPendingDays` | integer | Days a pending balance is held before clearing under the `manual` cadence. | | `data.withdrawalPeriod` | string | Currently selected cadence code: `manual`, `weekly`, or `monthly`. | ## Example response (200) ```json { "data": { "payoutAvailable": 8465.22, "payoutPending": 35176.26, "currency": "USD", "minPayoutSumm": 20, "maxPayoutSumm": 8465.22, "withdrawalPeriodOptions": [ { "code": "manual", "name": "Manual payouts" }, { "code": "weekly", "name": "Weekly payouts" }, { "code": "monthly", "name": "Monthly payouts" } ], "manualPayoutPendingDays": 7, "withdrawalPeriod": "manual" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Payout Eligibility Section: API Reference › Payouts. Page: https://api-docs.fansmetric.com/api-reference/payouts/eligibility Returns whether the creator can currently trigger a manual payout, and whether their banking details need updating before they can. **Endpoint:** `GET /v1/{account_id}/payouts/eligibility` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_payouts_read_eligibility` Returns manual-payout eligibility and banking-update status. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/payouts/check-receive`. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.isVerifiedReason` | boolean | `true` if the account is blocked from payouts for an identity-verification reason. | | `data.canReceiveManualPayout` | boolean | `true` if a manual payout can be requested right now. | | `data.needUpdateBanking` | boolean | `true` if banking details must be updated before a payout will succeed. | ## Example response (200) ```json { "data": { "isVerifiedReason": false, "canReceiveManualPayout": true, "needUpdateBanking": false }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Chargeback Ratio Section: API Reference › Payouts. Page: https://api-docs.fansmetric.com/api-reference/payouts/chargeback-ratio Returns the account's chargeback ratio (chargebacks divided by gross sales) over a date window. To compute the ratio over the entire account lifetime, pass `/me/start-date` as `start_date`. **Endpoint:** `GET /v1/{account_id}/payouts/chargebacks/ratio` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_payouts_read_chargebacks_ratio` Returns the chargeback ratio for the window. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `start_date` | query | no | | Window start. Default 2 years ago, UTC. | | `end_date` | query | no | | Window end. Default end of today, UTC. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/payouts/chargebacks/ratio?startDate=…&endDate=…`. For the underlying chargeback rows (with full original-transaction details), use [`/payouts/chargebacks`](https://api-docs.fansmetric.com/api-reference/payouts/list-chargebacks). ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.chargebacksRatio` | number | Chargeback ratio as a decimal (e.g. `0.14` = 14%) over the requested window. | ## Example response (200) ```json { "data": { "chargebacksRatio": 0.14 }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Chargebacks Chart Section: API Reference › Payouts. Page: https://api-docs.fansmetric.com/api-reference/payouts/chargebacks-chart Returns a daily timeseries of chargebacks over a date window — one series of summed chargeback amounts (`chartAmount`) and one series of row counts (`chartCount`) — alongside the window's `total` and the `delta` versus the prior equal-length window. Backs the line/bar chart on the OnlyFans **Statistics → Chargebacks** page. **Endpoint:** `GET /v1/{account_id}/payouts/chargebacks/chart` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_payouts_read_chargebacks_chart` Returns daily chargeback amount and count series with window total and prior-period delta. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `start_date` | query | no | | Window start. Default 2 years ago, UTC. `YYYY-MM-DD HH:MM:SS` or ISO 8601 (the `T` separator is normalized to a space). | | `end_date` | query | no | | Window end. Default end of today, UTC. Same format as `start_date`. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/payouts/chargebacks/chart?startDate=…&endDate=…&withTotal=true&withChart=true&filter[chartAmount]=chartAmount&filter[chartCount]=chartCount`. Both series are always requested together — the proxy forwards the same flags so callers don't have to. Dates filter on the chargeback's filing date (`createdAt`), matching [`/payouts/chargebacks`](https://api-docs.fansmetric.com/api-reference/payouts/list-chargebacks). To sanity-check the chart, sum `chartCount` over the window and compare to the row count returned by paginating the chargebacks list over the same range. Both arrays share the same length and date keys, so they zip 1:1 — each index represents the same UTC day in both series. For the aggregate ratio (chargebacks ÷ gross sales) over a window, use [`/payouts/chargebacks/ratio`](https://api-docs.fansmetric.com/api-reference/payouts/chargeback-ratio). ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.chartAmount[]` | array | One bucket per UTC day in the window (inclusive of `start_date` and `end_date`). Emitted even when `count` is `0`. | | `data.chartAmount[].date` | string | ISO 8601 midnight UTC for the bucket day. | | `data.chartAmount[].count` | number | Sum of chargeback **amounts** filed that day, in the account's payout currency. The field is named `count` upstream — it represents dollars here. | | `data.chartCount[]` | array | One bucket per UTC day in the window. Same length and date keys as `chartAmount`. | | `data.chartCount[].date` | string | ISO 8601 midnight UTC for the bucket day. | | `data.chartCount[].count` | number | Number of chargeback **rows** filed that day. | | `data.total` | number | Sum of `chartAmount[].count` over the window — total chargeback dollars in the period. | | `data.delta` | number | `total` minus the total of the immediately preceding window of the same length. Positive = chargebacks grew vs. prior period; negative = shrank. | ## Example response (200) ```json { "data": { "chartAmount": [ { "date": "2025-12-10T00:00:00+00:00", "count": 0 }, { "date": "2025-12-11T00:00:00+00:00", "count": 68.87 }, { "date": "2025-12-12T00:00:00+00:00", "count": 0 } ], "chartCount": [ { "date": "2025-12-10T00:00:00+00:00", "count": 0 }, { "date": "2025-12-11T00:00:00+00:00", "count": 1 }, { "date": "2025-12-12T00:00:00+00:00", "count": 0 } ], "total": 8398.35, "delta": 926.7 }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Payouts Chart Section: API Reference › Payouts. Page: https://api-docs.fansmetric.com/api-reference/payouts/chart Returns the payout-requests timeseries that backs the OnlyFans **Statements → Payout Requests** page — one $ series (`chartAmount`), one request-count series (`chartCount`), the window's `total`, and OF's percent-change `delta` vs the previous equal-length window. Bucket granularity (daily vs monthly) is chosen by OnlyFans based on window length. **Endpoint:** `GET /v1/{account_id}/payouts/chart` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_payouts_read_chart` Returns daily/monthly payout amount and request-count series with window total and prior-period delta. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `start_date` | query | no | | Window start. Default 2 years ago, UTC. `YYYY-MM-DD HH:MM:SS` or ISO 8601 (the `T` separator is normalized to a space). | | `end_date` | query | no | | Window end. Default end of today, UTC. Same format as `start_date`. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/payouts/chart?startDate=…&endDate=…&withTotal=true&withChart=true&filter[chartAmount]=chartAmount&filter[chartCount]=chartCount`. Field name `count` is shared by both series — it represents dollars in `chartAmount` and request rows in `chartCount`. Bucket granularity is OF-controlled. Short windows return daily buckets; multi-month windows return monthly buckets aligned to the 1st-of-month UTC. For the same view scoped to referral commissions only, use [`/referrals/payouts/chart`](https://api-docs.fansmetric.com/api-reference/referrals/payouts-chart). For chargebacks see [Get Chargebacks Chart](https://api-docs.fansmetric.com/api-reference/payouts/chargebacks-chart). ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.chartAmount[]` | array | One bucket per period in the window. `date` is midnight UTC ISO 8601 at the bucket start; `count` is the **$ paid out** in that bucket, in the account's payout currency. | | `data.chartCount[]` | array | Same bucket alignment as `chartAmount`. `count` is the **number of payout requests** in that bucket. | | `data.total` | number | Sum of `chartAmount[].count` over the window — total $ paid out in the period. | | `data.delta` | number | OF-computed change vs the immediately preceding equal-length window. Reported as a whole-number percent and saturates at `100` (treat ≥100 as "at least doubled"). | ## Example response (200) ```json { "data": { "chartAmount": [ { "date": "2025-09-01T00:00:00+00:00", "count": 0 }, { "date": "2025-10-01T00:00:00+00:00", "count": 150000 } ], "chartCount": [ { "date": "2025-09-01T00:00:00+00:00", "count": 0 }, { "date": "2025-10-01T00:00:00+00:00", "count": 12 } ], "total": 1362957, "delta": 100 }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Payout Requests Section: API Reference › Payouts. Page: https://api-docs.fansmetric.com/api-reference/payouts/list-requests Returns the history of withdrawal requests the creator has submitted — one row per request, with invoice ID, amount, currency, approval state, and reject reason. This is the payout-history view, not the per-transaction earnings feed. **Endpoint:** `GET /v1/{account_id}/payouts/requests` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_payouts_list_requests` Lists payout (withdrawal) requests with offset + marker pagination. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `start_date` | query | no | | Lower bound on `createdAt`. Default 2 years ago, UTC. | | `end_date` | query | no | | Upper bound on `createdAt`. Default end of today, UTC. | | `offset` | query | no | | Rows to skip. Page size is fixed at 10. | | `marker` | query | no | | Snapshot pin (unix seconds) from a prior response. Omit on the first page; pass back unchanged so the paged view stays stable. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/payouts/requests?startDate=…&endDate=…&offset=…&marker=…`. Page size is controlled by OnlyFans (10) and is not configurable. The endpoint does not return a `hasMore` flag or total count — `next_page` is emitted whenever the returned `list` length equals the page size. Stop when it shrinks. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[]` | array | Payout requests in this page. Newest first. | | `data.list[].invoiceId` | string | OnlyFans invoice ID for this payout request. | | `data.list[].createdAt` | string | ISO 8601 timestamp when the request was submitted. | | `data.list[].amount` | number | Amount requested, in `currency` units (whole units, same scale as `/payouts/balances`). | | `data.list[].currency` | string | ISO 4217 currency code. | | `data.list[].state` | string | Approval state. Observed: `approved`. Other expected values: `pending`, `rejected`, `processing`. | | `data.list[].rejectReason` | string\|null | Reject reason when `state == "rejected"`. `null` otherwise. | | `data.marker` | integer | Snapshot pin (unix seconds). Pass back on subsequent requests. | ## Example response (200) ```json { "data": { "list": [ { "invoiceId": "84452061", "createdAt": "2026-04-20T09:34:59+00:00", "amount": 20000, "currency": "USD", "state": "approved", "rejectReason": null } ], "marker": 1779973920 }, "_pagination": { "next_page": "/v1/100000001/payouts/requests?offset=10&marker=1779973920" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Chargebacks Section: API Reference › Payouts. Page: https://api-docs.fansmetric.com/api-reference/payouts/list-chargebacks Returns the chargeback history — disputes the fan's bank reversed against the creator. Each row carries the original transaction details under a nested `payment` object, so no cross-reference against the earnings feed is needed. **Endpoint:** `GET /v1/{account_id}/payouts/chargebacks` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_payouts_list_chargebacks` Lists chargebacks with offset + caller-controlled limit and a marker snapshot pin. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `start_date` | query | no | | Lower bound on the chargeback's `createdAt` (filing date, not original transaction). Default 2 years ago, UTC. | | `end_date` | query | no | | Upper bound on the chargeback's `createdAt`. Default end of today, UTC. | | `limit` | query | no | | Page size. Default 10. Min 1, max 100. | | `offset` | query | no | | Rows to skip. | | `marker` | query | no | | Snapshot pin (unix seconds) from a prior response. Omit on the first page; pass back unchanged on subsequent pages. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/payouts/chargebacks?limit=…&offset=…&startDate=…&endDate=…&marker=…`. `start_date` / `end_date` filter on the **chargeback** filing date (`row.createdAt`), not the original transaction date. A chargeback for a months-old transaction will appear in the window when the dispute landed. `payment.status: "undo"` marks the underlying earnings row as reversed; reconcile against [`/earnings`](https://api-docs.fansmetric.com/api-reference/earnings/list) using `payment.id`. For the aggregate ratio over a window, use [`/payouts/chargebacks/ratio`](https://api-docs.fansmetric.com/api-reference/payouts/chargeback-ratio). ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[]` | array | Chargebacks in this page, newest first by `createdAt` (filing date). | | `data.list[].id` | integer | Upstream chargeback ID. Currently always `0` in observed payloads — identify rows by `payment.id`. | | `data.list[].createdAt` | string | ISO 8601 timestamp the **chargeback** was filed (not the original transaction). | | `data.list[].paymentType` | string | Category of the reversed transaction. Values: `post`, `chat_messages`, `tips`, `subscribes`, `stream`. | | `data.list[].payment` | object | Original transaction that was reversed. Same shape as an earnings transaction (`id`, `amount`, `vatAmount`, `taxAmount`, `mediaTaxAmount`, `fee`, `net`, `currency`, `createdAt`, `description`, `status`, `user`). `payment.status: "undo"` marks the reversal. | | `data.marker` | integer | Snapshot pin (unix seconds). | ## Example response (200) ```json { "data": { "list": [ { "id": 0, "createdAt": "2026-05-15T03:15:33+00:00", "paymentType": "post", "payment": { "id": "aa6c984b86eaf11a07442042e711c7f9", "amount": 23.99, "vatAmount": 0, "taxAmount": 0, "mediaTaxAmount": 0, "net": 19.19, "fee": 4.8, "createdAt": "2026-05-10T03:46:25+00:00", "currency": "USD", "description": "Post purchase by Fan XX", "status": "undo", "user": { "id": 100000008, "name": "Fan XX", "username": "u100000008", "view": "t", "isVerified": false, "isDeleted": false, "isActive": false, "avatar": null, "avatarThumbs": null } } } ], "marker": 1779974073 }, "_pagination": { "next_page": "/v1/100000001/payouts/chargebacks?limit=10&offset=10&marker=1779974073" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Mass Message Chart Section: API Reference › Mass Messages. Page: https://api-docs.fansmetric.com/api-reference/mass-messages/chart Returns a daily timeseries for mass (group) messages over a date window — one series of **sent counts** (`group_messages.chart`) and one series of **$ purchased** from those messages (`group_messages_purchases.chart`), each with the window total and the delta vs. the prior equal-length window. Aggregate chart view; for per-message rows use [Mass Message Statistics](https://api-docs.fansmetric.com/api-reference/mass-messages/list-mass-messages). **Endpoint:** `GET /v1/{account_id}/mass-messages/chart` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_mass_messages_read_chart` Returns daily mass-message sent-count and purchases-$ series with window totals and prior-period deltas. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `start_date` | query | no | | Window start. Default 30 days ago, UTC. `YYYY-MM-DD HH:MM:SS` or ISO 8601 (the `T` separator is normalized to a space). | | `end_date` | query | no | | Window end. Default end of today, UTC. Same format as `start_date`. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/messages/queue/chart?startDate=…&endDate=…&withTotal=true&filter[group_messages]=group_messages&filter[group_messages_purchases]=group_messages_purchases`. Both series are always requested together so the full chart payload comes back in one round trip. Field name `count` is shared by both series — it represents row count in `group_messages` and dollars in `group_messages_purchases`. For the equivalent timeseries scoped to 1:1 DMs use [Direct Message Chart](https://api-docs.fansmetric.com/api-reference/direct-messages/chart). ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.group_messages.chart[]` | array | One bucket per UTC day inclusive of the window. `date` is midnight UTC ISO 8601; `count` is the **number of mass messages sent** that day. | | `data.group_messages.total` | number | Sum of `group_messages.chart[].count` over the window. | | `data.group_messages.delta` | number | `total` minus the total of the immediately preceding equal-length window. Positive = grew; negative = shrank. | | `data.group_messages_purchases.chart[]` | array | One bucket per UTC day in the window. `count` is the **$ purchased** from mass messages that day, in the account's payout currency. | | `data.group_messages_purchases.total` | number | Sum of `group_messages_purchases.chart[].count` over the window — total $ from mass-message purchases. | | `data.group_messages_purchases.delta` | number | `total` minus the prior equal-length window's total. | ## Example response (200) ```json { "data": { "group_messages": { "chart": [ { "date": "2026-05-09T00:00:00+00:00", "count": 50 }, { "date": "2026-05-10T00:00:00+00:00", "count": 49 } ], "total": 1446, "delta": -41.4 }, "group_messages_purchases": { "chart": [ { "date": "2026-05-09T00:00:00+00:00", "count": 385.54 }, { "date": "2026-05-10T00:00:00+00:00", "count": 282.56 } ], "total": 9469.9, "delta": -18.1 } }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Create Post Section: API Reference › Posts. Page: https://api-docs.fansmetric.com/api-reference/posts/create-post Composes and publishes a new post on the creator's feed. Supports plain text, attached media from the vault or freshly uploaded files, paid (PPV) posts, scheduled posts, auto-expiring posts, and release-form tags. **Endpoint:** `POST /v1/{account_id}/posts` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_posts_create` Creates a new feed post — text-only, media, paid, scheduled, or auto-expiring. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `text` | body | yes | | Post caption. HTML is preserved (`

`, ``, etc.). | | `mediaFiles` | body | no | | Array of OF vault media IDs (integer) to attach. Required if the post should include media. | | `price` | body | no | | If present and `> 0`, makes the post a paid (PPV) post, in USD. | | `preview` | body | no | | When `price > 0`, the subset of `mediaFiles` IDs to show as the free preview. | | `rfTag` | body | no | | Array of release-form tag IDs (string). | | `rfGuest` | body | no | | Array of tagged guest user IDs (integer). | | `rfPartner` | body | no | | Array of tagged partner user IDs (integer). | | `scheduledDate` | body | no | string | ISO 8601 timestamp (UTC) to publish the post at. Omit to publish immediately. The old name `scheduledTime` is still accepted. | | `isScheduled` | body | no | integer | Added as `1` for you when `scheduledDate` is set — OnlyFans ignores `scheduledDate` without it and publishes immediately. Send `1` with `isPublishedWithPeriod: 1` and no `scheduledDate` to save the post for later instead. | | `isPublishedWithPeriod` | body | no | integer | With `isScheduled: 1`, puts the post in OnlyFans' "Saved for later" queue instead of publishing it. | | `expireDays` | body | no | | Number of whole days (integer) after publishing before the post is automatically removed from the feed. Must be between 1 and 30. Omit for a post that never expires. | ## Request body example ```json { "text": "

New exclusive set 💖

", "mediaFiles": [1111111111, 2222222222, 3333333333], "preview": [1111111111], "price": 25, "expireDays": 3 } ``` ## Notes Upstream OnlyFans endpoint: `POST /api2/v2/posts`. `rfTag`, `rfGuest` and `rfPartner` default to `[]`, and `isScheduled: 1` is added whenever `scheduledDate` is set — send only the fields you need. `mediaFiles` takes vault media IDs — use [List Vault Media](https://api-docs.fansmetric.com/api-reference/vault/list-vault-media) to find them. Paid posts require a `price > 0` and at least one entry in `preview` (the free-preview subset of `mediaFiles`). Scheduled posts: send `{ "text": "…", "scheduledDate": "2026-10-25T15:00:00.000Z" }`. The response's `postedAt` is the scheduled time. To confirm the post was queued rather than published, look for it in [List Later Scheduled Posts](https://api-docs.fansmetric.com/api-reference/schedules/list-later-posts). Auto-expiring posts: set `expireDays` to have OnlyFans remove the post from the feed automatically. Whole days only, 1 to 30 — there is no hours-level granularity. Omitting the field publishes a post that never expires. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.id` | integer | OnlyFans post ID for the new post. | | `data.postedAt` | string | ISO timestamp when the post was published (or scheduled for). | | `data.text` | string | Rendered caption HTML. | | `data.rawText` | string | Plain-text version of the caption. | | `data.author` | object | Author summary (`id`, `_view`). | | `data.isMediaReady` | boolean | `true` once OnlyFans has finished transcoding all attached media. | | `data.canDelete` | boolean | Whether the caller can delete this post. | | `data.canEdit` | boolean | Whether the caller can edit this post. | ## Example response (200) ```json { "data": { "id": 9876543210, "postedAt": "2026-06-01T12:30:00+00:00", "text": "

Hello, fans!

", "rawText": "Hello, fans!", "author": { "id": 12345678, "_view": "a" }, "isMediaReady": true, "canDelete": true, "canEdit": true, "tipsAmount": "$0" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Delete Post Section: API Reference › Posts. Page: https://api-docs.fansmetric.com/api-reference/posts/delete-post Permanently deletes a post from the creator's feed. This cannot be undone — the post, its media references, and engagement counters are removed from the OnlyFans-side feed. **Endpoint:** `DELETE /v1/{account_id}/posts/{post_id}` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_posts_delete` Deletes a post from the creator's feed. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `post_id` | path | yes | | The post ID to delete. Numeric. | ## Notes Upstream OnlyFans endpoint: `DELETE /api2/v2/posts/{post_id}`. Returns `404` if the post is already deleted or does not belong to this account. Vault media referenced by the post is not deleted — only the post itself. ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Posts Section: API Reference › Posts. Page: https://api-docs.fansmetric.com/api-reference/posts/list-posts Returns the creator's own post feed — the same list the Posts tab shows inside OnlyFans. Filter by media type, label, caption text and pinned state, and sort by publish date, likes or tips. This feed pages by cursor rather than page number, so walk it by following `_pagination.next_page` instead of building a numbered pager. **Endpoint:** `GET /v1/{account_id}/posts` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_posts_list` Lists the creator's posts with label, media-type and search filters. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `limit` | query | no | | Page size. Default 10. Min 1, max 100 (anything higher is clamped to 100). | | `media_type` | query | no | | Only return posts that carry a media type: `photos`, `videos`, `audios`, or `medias` (any of the three). Omit to include text-only posts. | | `label` | query | no | | Only posts carrying this label. Takes a numeric label ID from [List Post Labels](https://api-docs.fansmetric.com/api-reference/post-labels/list-post-labels), or an archive bucket name: `archived` for the Archive, `private_archived` for the Private Archive. | | `exclude_label` | query | no | | The inverse of `label` — leave out posts carrying it. Accepts the same values. | | `query` | query | no | | Free-text search across post captions. | | `pinned` | query | no | boolean | `true` returns only pinned posts, `false` returns everything except them. Omit for the whole feed. | | `order` | query | no | | Sort order. One of `publish_date_desc` (default), `publish_date_asc`, `favorites_count_desc`, `tips_summ_desc`, `tips_summ_asc`. Any other value returns 400 rather than quietly falling back. | | `counters` | query | no | boolean | Include the `counters` block of account totals — useful for tab badges. Default `true`; send `false` to skip it. | | `before_publish_time` | query | no | | Cursor for continuing a descending feed. Pass the previous page's `tailMarker`. `_pagination.next_page` fills this in for you. | | `after_publish_time` | query | no | | Cursor for continuing an ascending feed. Pass the previous page's `tailMarker`. `_pagination.next_page` fills this in for you. | ## Notes Every media `url` is a FansMetric link that expires after 2 hours, not an OnlyFans address — see [Media URLs](https://api-docs.fansmetric.com/media-urls). Upstream OnlyFans endpoint: `GET /api2/v2/users/{self}/posts` (with `/photos`, `/videos`, `/audios` or `/medias` appended when `media_type` is set). **This feed pages by cursor, not by offset.** OnlyFans ignores an `offset` on post feeds. Each page reports a `tailMarker`; send it back as `before_publish_time` for descending orders or `after_publish_time` for ascending ones. `_pagination.next_page` does that for you and carries every filter across, so following it verbatim is the safest way to walk the feed. **Worth knowing for the tip- and like-ordered feeds.** OnlyFans pages every order on publish time, including `favorites_count_desc` and the `tips_summ_*` orders. So the cursor is still a publish time even when the sort key is a tip total, and a long walk through those orders is only stable while the underlying totals hold still. If you need a guaranteed-complete traversal, page `publish_date_desc` and sort your own copy. Archived posts are left out of the default feed. Reach them with `label=archived` or `label=private_archived`. Media URLs are signed and time-limited. Fetch them when you need them rather than storing them in your own database. - Default page size 10; max 100 (clamped) - Cursor-paginated — follow `_pagination.next_page` instead of counting offsets - An unknown `order` or `media_type` returns 400 rather than quietly falling back ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[]` | array | The posts on this page. | | `data.list[].id` | integer | OnlyFans post ID. Use it for every other Posts route. | | `data.list[].postedAt` | string | ISO timestamp the post was published — the one to show in a UI. | | `data.list[].postedAtPrecise` | string | The same publish time as a fractional epoch string. This is what `tailMarker` reports and what the two cursor parameters take. | | `data.list[].text` | string | Caption as HTML. | | `data.list[].rawText` | string | Caption as plain text — the safer field for list rows and search indexes. | | `data.list[].author` | object | Short author reference (`id`, `_view`). Always the account you queried; OnlyFans leaves out the full user object here because every row would repeat it. | | `data.list[].mediaCount` | integer | How many media items are attached. | | `data.list[].media[]` | array | Attached media. Each item carries a `files` object with `full`, `thumb`, `preview` and `squarePreview` URLs. | | `data.list[].tipsAmount` | string | Tip total for the post, pre-formatted for display, e.g. `$0`. | | `data.hasMore` | boolean | Whether another page exists. | | `data.tailMarker` | string | Publish time of the last row on this page — the value that seeds the next page's cursor. | | `data.headMarker` | string | Publish time of the first row on this page. | | `data.counters` | object | Account totals: `postsCount`, `photosCount`, `videosCount`, `audiosCount`, `mediasCount`, `streamsCount`, `archivedPostsCount`, `privateArchivedPostsCount`. Present only when `counters` is true. | ## Example response (200) ```json { "data": { "list": [ { "author": { "id": 12345678, "_view": "a" }, "responseType": "post", "id": 2678855749, "postedAt": "2026-08-16T16:33:27+00:00", "postedAtPrecise": "1786898007.000000", "text": "

behind the scenes from today's shoot 💖

", "rawText": "behind the scenes from today's shoot 💖", "canDelete": true, "canComment": true, "canEdit": true, "mediaCount": 1, "isMediaReady": true, "canToggleFavorite": true, "tipsAmount": "$0", "canViewMedia": true, "media": [ { "id": 987654321, "type": "photo", "canView": true, "isReady": true, "duration": 0, "files": { "full": { "url": "https://public-api.fansmetric.com/media-proxy?url=...&exp=...&sig=..." }, "thumb": { "url": "https://public-api.fansmetric.com/media-proxy?url=...&exp=...&sig=..." }, "preview": { "url": "https://public-api.fansmetric.com/media-proxy?url=...&exp=...&sig=..." }, "squarePreview": { "url": "https://public-api.fansmetric.com/media-proxy?url=...&exp=...&sig=..." } } } ] } ], "hasMore": true, "headMarker": "1786898007.000000", "tailMarker": "1786872300.000000", "counters": { "audiosCount": 0, "photosCount": 278, "videosCount": 18, "mediasCount": 296, "postsCount": 279, "streamsCount": 0, "archivedPostsCount": 1, "privateArchivedPostsCount": 77 } }, "_pagination": { "next_page": "/v1/12345678/posts?limit=10&order=publish_date_desc&before_publish_time=1786872300.000000" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Post Section: API Reference › Posts. Page: https://api-docs.fansmetric.com/api-reference/posts/get-post Returns one post in full — caption, attached media, like count, expiry, and which parts can still be edited. Use it behind a post detail view: [List Posts](https://api-docs.fansmetric.com/api-reference/posts/list-posts) returns the same shape but leaves out `favoritesCount` and the edit flags. **Endpoint:** `GET /v1/{account_id}/posts/{post_id}` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_posts_read` Returns one post with full detail. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `post_id` | path | yes | | The post ID. Numeric. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/posts/{post_id}`. Same object shape as a row of [List Posts](https://api-docs.fansmetric.com/api-reference/posts/list-posts), plus `favoritesCount`, `expiredAt` and the `canEdit*` flags that only appear on the detail view. Returns `404` if the post has been deleted or belongs to a different account. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.id` | integer | OnlyFans post ID. | | `data.favoritesCount` | integer | Total likes. Detail view only — the list view leaves this out. | | `data.expiredAt` | string \| null | When the post expires, if an expiry was set. `null` otherwise. | | `data.canEditText` | boolean | Whether the caption can still be changed — use it to enable or disable an edit button. | | `data.canEditMedia` | boolean | Whether attachments can still be changed. | | `data.canEditExpire` | boolean | Whether the expiry can still be changed. | | `data.media[].videoSources` | object | Playback sources. Present on video media only. | ## Example response (200) ```json { "data": { "id": 2676873092, "postedAt": "2026-08-15T12:04:11+00:00", "postedAtPrecise": "1786872300.000000", "text": "

Hello, fans!

", "rawText": "Hello, fans!", "author": { "id": 12345678, "_view": "a" }, "favoritesCount": 42, "mediaCount": 3, "isMediaReady": true, "canDelete": true, "canEdit": true, "canEditText": true, "canEditMedia": false, "tipsAmount": "$0" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Post Statistics Section: API Reference › Posts. Page: https://api-docs.fansmetric.com/api-reference/posts/get-post-statistics Returns the per-post analytics OnlyFans shows in a post's stats drawer — views, unique viewers, likes, comments, tips and unlocks, each with a time series you can chart. Set `with_chart=false` when you only need the headline numbers. **Endpoint:** `GET /v1/{account_id}/posts/{post_id}/stats` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_posts_read_stats` Returns views, likes, comments, tips and purchase stats for one post. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `post_id` | path | yes | | The post ID. Numeric. | | `with_chart` | query | no | boolean | Include the time-series arrays. Default `true`; send `false` for the totals only, which makes the response much smaller. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/posts/{post_id}/stats?withChart=`. Chart buckets are hourly for recent posts and widen as a post gets older. OnlyFans picks the bucket size — it is not something you can set. Every chart array is aligned to its own dates, so read `date` from each point rather than assuming the arrays line up index-for-index. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.hasStats` | boolean | `false` when OnlyFans has not gathered data for this post yet. The counters are still present, just zero — show an empty state rather than a row of zeroes. | | `data.lookCount` | integer | Total views. | | `data.uniqueLookCount` | integer | Distinct viewers. | | `data.lookDurationAverage` | integer | Mean view duration in seconds. Meaningful on video posts. | | `data.likeCount` | integer | Total likes. | | `data.commentCount` | integer | Total comments. | | `data.tipCount` | integer | Number of tips received on the post. | | `data.tipSum` | integer | Total tipped amount. | | `data.purchasedCount` | integer | Unlocks, on paid posts. | | `data.purchasedSumm` | integer | Revenue from those unlocks. | | `data.lookChart` | array | Time series of `{date, count}` objects. The sibling arrays follow the same shape: `uniqueLookChart`, `likeChart`, `commentChart`, `tipChart`, `tipSumChart`, `purchasesChart`. Present only when `with_chart` is true. | ## Example response (200) ```json { "data": { "isAvailable": true, "hasStats": true, "hasVideo": false, "hasAudio": false, "lookCount": 535, "uniqueLookCount": 0, "lookDuration": 0, "lookDurationAverage": 0, "likeCount": 5, "commentCount": 0, "tipCount": 0, "tipSum": 0, "purchasedCount": 0, "purchasedSumm": 0, "lookChart": [ { "date": "2026-08-16T10:00:00+00:00", "count": 73 }, { "date": "2026-08-16T11:00:00+00:00", "count": 100 } ], "uniqueLookChart": [ { "date": "2026-08-16T10:00:00+00:00", "count": 48 } ], "likeChart": [ { "date": "2026-08-16T10:00:00+00:00", "count": 1 } ], "commentChart": [], "tipChart": [], "tipSumChart": [], "purchasesChart": [] }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Post Comments Section: API Reference › Posts. Page: https://api-docs.fansmetric.com/api-reference/posts/list-post-comments Returns fan comments on one of the creator's posts, newest first by default. Unlike the post feed itself, this one is offset-paginated — follow `_pagination.next_page` or step `offset` yourself. **Endpoint:** `GET /v1/{account_id}/posts/{post_id}/comments` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_posts_list_comments` Lists comments on a post. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `post_id` | path | yes | | The post ID. Numeric. | | `limit` | query | no | | Page size. Default 10. Min 1, max 100. | | `offset` | query | no | | Rows to skip. Default 0. | | `sort` | query | no | | Sort direction. `desc` (default) or `asc`. Newest comments come first with `desc`. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/posts/{post_id}/comments`. Offset-paginated. `_pagination.next_page` carries your `sort` across, and is `null` on the last page. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[]` | array | Comments on this page. Empty when the post has none. | | `data.hasMore` | boolean | Whether another page exists. | | `data.nextOffset` | integer | Offset to request for the next page. | ## Example response (200) ```json { "data": { "list": [], "hasMore": false, "nextOffset": 0 }, "_pagination": { "next_page": null }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Like Post Section: API Reference › Posts. Page: https://api-docs.fansmetric.com/api-reference/posts/like-post Adds the creator's own like to one of their posts — or takes it away. **This endpoint is a toggle**: OnlyFans has no separate unlike route, so a second call reverses the first. Drive your button state from `isFavorite` in the response rather than assuming the call added a like. **Endpoint:** `POST /v1/{account_id}/posts/{post_id}/like` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_posts_like` Toggles the creator's like on a post. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `post_id` | path | yes | | The post ID. Numeric. | ## Notes Upstream OnlyFans endpoint: `POST /api2/v2/posts/{post_id}/favorites/{account_id}`. **This endpoint toggles.** OnlyFans exposes no unlike route for posts, so there is deliberately no `DELETE .../like` here — it would have to call the same upstream toggle, which means it could just as easily *like* a post. Because it toggles, it is not safe to blindly retry. If a request times out, read `isFavorite` back before sending it again — a retry may undo what the first call did. - Toggles — a second call reverses the first - Not safe to retry blindly; confirm with `isFavorite` ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.id` | integer | The post ID. | | `data.isFavorite` | boolean | Whether the post is liked **after** this call. Read this to set your button state — do not assume. | | `data.favoritesCount` | integer | Total likes after this call. | ## Example response (200) ```json { "data": { "id": 2677887003, "isFavorite": true, "favoritesCount": 6 }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Pin Post Section: API Reference › Posts. Page: https://api-docs.fansmetric.com/api-reference/posts/pin-post Pins a post to the top of the creator's profile, or unpins it. **This endpoint is a toggle** — a second call reverses the first. The response only confirms success, so read the resulting state back from [List Posts](https://api-docs.fansmetric.com/api-reference/posts/list-posts) with `pinned=true`. **Endpoint:** `POST /v1/{account_id}/posts/{post_id}/pin` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_posts_pin` Toggles a post's pinned state. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `post_id` | path | yes | | The post ID. Numeric. | ## Notes Upstream OnlyFans endpoint: `POST /api2/v2/posts/{post_id}/pin?format=status`. OnlyFans caps how many posts a profile may pin. Going over the cap surfaces as a `502`. - Toggles — a second call reverses the first - Response does not report the resulting state; read it back with `pinned=true` ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.success` | boolean | Confirms the call went through. It does not tell you whether the post ended up pinned or unpinned — list `pinned=true` to find out. | ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Archive Post Section: API Reference › Posts. Page: https://api-docs.fansmetric.com/api-reference/posts/archive-post Moves a post out of the live feed and into the Archive, or into the Private Archive that subscribers cannot see. Archived posts stay retrievable and can be restored, so prefer this over [Delete Post](https://api-docs.fansmetric.com/api-reference/posts/delete-post) whenever the post might be wanted again. The response returns refreshed archive counts, so tab badges can be updated without a second call. **Endpoint:** `POST /v1/{account_id}/posts/{post_id}/archive` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_posts_archive` Archives a post, optionally into the Private Archive. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `post_id` | path | yes | | The post ID. Numeric. | | `private` | query | no | boolean | Send `true` to move the post to the Private Archive, which subscribers cannot see, instead of the regular Archive. Default `false`. | ## Notes Upstream OnlyFans endpoint: `POST /api2/v2/posts/{post_id}/archive` (plus `?action=private_archive` when `private` is true). Archived posts stay readable through [List Posts](https://api-docs.fansmetric.com/api-reference/posts/list-posts) with `label=archived` or `label=private_archived`. Restore a post with [Unarchive Post](https://api-docs.fansmetric.com/api-reference/posts/unarchive-post). ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.labelStates[]` | array | The resulting state of both archive buckets, each with `id`, `name`, `type` and `postsCount`. | | `data.counters` | object | Refreshed account totals — the same block [List Posts](https://api-docs.fansmetric.com/api-reference/posts/list-posts) returns, so a tab bar can be updated straight from this response. | ## Example response (200) ```json { "data": { "labelStates": [ { "id": "private_archived", "name": "Private Archive", "type": "private_archived", "isClearInProgress": false, "postsCount": 77 }, { "id": "archived", "name": "Archive", "type": "archived", "isClearInProgress": false, "postsCount": 1 } ], "counters": { "audiosCount": 0, "photosCount": 278, "videosCount": 18, "mediasCount": 296, "postsCount": 279, "streamsCount": 0, "archivedPostsCount": 1, "privateArchivedPostsCount": 77 } }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Unarchive Post Section: API Reference › Posts. Page: https://api-docs.fansmetric.com/api-reference/posts/unarchive-post Returns an archived post to the live feed. Set `private=true` if the post sits in the Private Archive — sending the wrong value leaves the post exactly where it is. **Endpoint:** `POST /v1/{account_id}/posts/{post_id}/unarchive` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_posts_unarchive` Restores an archived post to the live feed. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `post_id` | path | yes | | The post ID. Numeric. | | `private` | query | no | boolean | Set to `true` if the post currently sits in the Private Archive rather than the regular Archive. Sending the wrong value leaves the post where it is. | ## Notes Upstream OnlyFans endpoint: `POST /api2/v2/posts/{post_id}/unarchive` (plus `?action=private_archive`). `private` has to match the archive the post is actually in. If you are not sure, list [List Posts](https://api-docs.fansmetric.com/api-reference/posts/list-posts) with `label=private_archived` and check whether the post is there. Returns the same `labelStates` and `counters` shape as [Archive Post](https://api-docs.fansmetric.com/api-reference/posts/archive-post). ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.labelStates[]` | array | The resulting state of both archive buckets, each with `id`, `name`, `type` and `postsCount`. | | `data.counters` | object | Refreshed account totals, so a tab bar can be updated straight from this response. | ## Example response (200) ```json { "data": { "labelStates": [ { "id": "private_archived", "name": "Private Archive", "type": "private_archived", "isClearInProgress": false, "postsCount": 76 }, { "id": "archived", "name": "Archive", "type": "archived", "isClearInProgress": false, "postsCount": 1 } ], "counters": { "audiosCount": 0, "photosCount": 279, "videosCount": 18, "mediasCount": 297, "postsCount": 280, "streamsCount": 0, "archivedPostsCount": 1, "privateArchivedPostsCount": 76 } }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Bookmark Post Section: API Reference › Posts. Page: https://api-docs.fansmetric.com/api-reference/posts/bookmark-post Saves a post to the creator's Saved for later collection. Unlike [Like Post](https://api-docs.fansmetric.com/api-reference/posts/like-post) and [Pin Post](https://api-docs.fansmetric.com/api-reference/posts/pin-post), this is a plain add rather than a toggle — undo it with [Remove Post Bookmark](https://api-docs.fansmetric.com/api-reference/posts/remove-post-bookmark). **Endpoint:** `POST /v1/{account_id}/posts/{post_id}/bookmark` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_posts_bookmark` Saves a post for later. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `post_id` | path | yes | | The post ID. Numeric. | ## Notes Upstream OnlyFans endpoint: `POST /api2/v2/posts/{post_id}/bookmarks`. Bookmarks are a proper add/remove pair upstream, so unlike Like and Pin this is **not** a toggle — calling it twice leaves the post saved once. Read the collection back with [List Bookmarks](https://api-docs.fansmetric.com/api-reference/bookmarks/list-bookmarks). ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.success` | boolean | Confirms the post was saved. | ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Remove Post Bookmark Section: API Reference › Posts. Page: https://api-docs.fansmetric.com/api-reference/posts/remove-post-bookmark Takes a post out of the creator's Saved for later collection. Safe to call on a post that was never saved — it still comes back successful. **Endpoint:** `DELETE /v1/{account_id}/posts/{post_id}/bookmark` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_posts_unbookmark` Removes a post from Saved for later. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `post_id` | path | yes | | The post ID. Numeric. | ## Notes Upstream OnlyFans endpoint: `DELETE /api2/v2/posts/{post_id}/bookmarks`. Safe to repeat — removing a post that was not bookmarked still returns `success: true`, so you do not need to check first. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.success` | boolean | Confirms the call went through, whether or not the post was saved to begin with. | ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Post Labels Section: API Reference › Post Labels. Page: https://api-docs.fansmetric.com/api-reference/post-labels/list-post-labels Returns every label on the account, each with a strip of preview thumbnails. Labels are OnlyFans's name for what the web app calls collections — named buckets a creator drops posts into to organise their feed, which double as filter chips on their public profile. Use a label's `id` as the `label` filter on [List Posts](https://api-docs.fansmetric.com/api-reference/posts/list-posts). **Endpoint:** `GET /v1/{account_id}/post-labels` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_post_labels_list` Lists the creator's post labels with preview thumbnails. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `limit` | query | no | | Page size. Default 10. Min 1, max 100. | | `offset` | query | no | | Rows to skip. Default 0. | ## Notes Every media `url` is a FansMetric link that expires after 2 hours, not an OnlyFans address — see [Media URLs](https://api-docs.fansmetric.com/media-urls). Upstream OnlyFans endpoint: `GET /api2/v2/labels`. Labels live at their own top-level path rather than under `/posts/` — `/post-labels`, not `/posts/labels`. Nesting them would have made `/posts/{post_id}/stats` and `/posts/labels/{label_id}` ambiguous for any request that fits both. For a filter bar over a post feed, use [List Post Label Filters](https://api-docs.fansmetric.com/api-reference/post-labels/list-post-label-filters) instead. It skips the thumbnails and adds the two archive buckets. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[].id` | integer | Label ID. Pass it as `label` or `exclude_label` on [List Posts](https://api-docs.fansmetric.com/api-reference/posts/list-posts). | | `data.list[].name` | string | The name the creator chose. Often contains emoji, so allow for that in your UI. | | `data.list[].type` | string | `custom` for labels the creator made. | | `data.list[].postsCount` | integer | How many posts are on the label right now. | | `data.list[].posts` | array | Up to 3 preview thumbnails for the label tile. The URLs are signed and expire. | | `data.list[].isClearInProgress` | boolean | `true` while OnlyFans is still emptying the label in the background. Counts will keep moving until it flips back to `false`. | | `data.hasMore` | boolean | Whether another page exists. | | `data.nextOffset` | integer | Offset to request for the next page. | ## Example response (200) ```json { "data": { "list": [ { "id": 9844743, "name": "Behind the scenes", "type": "custom", "isClearInProgress": false, "postsCount": 5, "posts": [ { "type": "photo", "canViewMedia": true, "postId": "2676873092", "url": "https://public-api.fansmetric.com/media-proxy?url=...&exp=...&sig=..." } ] } ], "order": "asc", "sort": "custom", "hasMore": true, "nextOffset": 10, "hashSort": "c9113837f826c2b87d503bd5798cb343" }, "_pagination": { "next_page": "/v1/12345678/post-labels?limit=10&offset=10" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Post Label Filters Section: API Reference › Post Labels. Page: https://api-docs.fansmetric.com/api-reference/post-labels/list-post-label-filters Returns the same labels as [List Post Labels](https://api-docs.fansmetric.com/api-reference/post-labels/list-post-labels), but shaped for a filter bar: no preview thumbnails, and the Archive and Private Archive buckets included. One thing to watch — `id` is a number for the creator's own labels and a word for the two archive buckets, so check its type before treating it as a number. **Endpoint:** `GET /v1/{account_id}/post-labels/filters` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_post_labels_list_filters` Lists labels usable as post-feed filters, including the archive buckets. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `limit` | query | no | | Page size. Default 10. Min 1, max 100. | | `offset` | query | no | | Rows to skip. Default 0. | | `non_empty` | query | no | boolean | Leave out labels holding no posts. Default `true` — send `false` to include empty ones. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/users/{self}/labels?non-empty=`. **`id` comes back as a number or a string here.** It is passed through exactly as OnlyFans sends it, because forcing it to one type would break feeding the value straight back into `label` on [List Posts](https://api-docs.fansmetric.com/api-reference/posts/list-posts). In a typed language, model it as a union and branch on it. Cheaper than [List Post Labels](https://api-docs.fansmetric.com/api-reference/post-labels/list-post-labels) because no preview thumbnails are fetched — a good default for a filter bar. The two archive buckets are filters only. They cannot be fetched through [Get Post Label](https://api-docs.fansmetric.com/api-reference/post-labels/get-post-label). - `id` is a number for custom labels and a string for the archive buckets — type-check before use ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[].id` | integer \| string | **Can be either type.** A number for the creator's own labels, and the words `archived` or `private_archived` for the two archive buckets. Both work as a `label` value on [List Posts](https://api-docs.fansmetric.com/api-reference/posts/list-posts), but check the type before doing arithmetic or using it as a numeric key. | | `data.list[].name` | string | Display name for the filter chip, e.g. `Private Archive`. | | `data.list[].type` | string | `custom`, `archived`, or `private_archived`. | | `data.list[].postsCount` | integer | How many posts are on the label. | | `data.hasMore` | boolean | Whether another page exists. | | `data.nextOffset` | integer | Offset to request for the next page. | ## Example response (200) ```json { "data": { "list": [ { "id": 9844743, "name": "Behind the scenes", "type": "custom", "isClearInProgress": false, "postsCount": 5 }, { "id": "private_archived", "name": "Private Archive", "type": "private_archived", "isClearInProgress": false, "postsCount": 77 } ], "order": "asc", "sort": "custom", "hasMore": true, "nextOffset": 10, "hashSort": "c9113837f826c2b87d503bd5798cb343" }, "_pagination": { "next_page": "/v1/12345678/post-labels/filters?limit=10&non_empty=true&offset=10" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Post Label Section: API Reference › Post Labels. Page: https://api-docs.fansmetric.com/api-reference/post-labels/get-post-label Returns one label with its post count and a short strip of preview thumbnails. The strip is a preview, not the full membership — to page through everything on a label, use [List Posts](https://api-docs.fansmetric.com/api-reference/posts/list-posts) with `label={label_id}`. **Endpoint:** `GET /v1/{account_id}/post-labels/{label_id}` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_post_labels_read` Returns one post label. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `label_id` | path | yes | | The label ID. Numeric — only the creator's own labels can be fetched here, not the archive buckets. | ## Notes Every media `url` is a FansMetric link that expires after 2 hours, not an OnlyFans address — see [Media URLs](https://api-docs.fansmetric.com/media-urls). Upstream OnlyFans endpoint: `GET /api2/v2/labels/{label_id}`. `posts` is a **preview strip, not the full membership** — OnlyFans caps it no matter how large `postsCount` is. To page every post on the label, use `GET /v1/{account_id}/posts?label={label_id}`. The `archived` and `private_archived` buckets are not valid here and return `400`. Reach them through [List Posts](https://api-docs.fansmetric.com/api-reference/posts/list-posts) instead. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.id` | integer | Label ID. | | `data.name` | string | The name the creator chose. | | `data.type` | string | `custom` for labels the creator made. | | `data.postsCount` | integer | How many posts are on the label. This can exceed the length of `posts` — that array is only a preview. | | `data.posts` | array | A short preview strip of thumbnails, capped by OnlyFans regardless of `postsCount`. | | `data.isClearInProgress` | boolean | `true` while OnlyFans is still emptying the label in the background. | ## Example response (200) ```json { "data": { "id": 9895427, "name": "Photo sets", "type": "custom", "isClearInProgress": false, "postsCount": 2, "posts": [ { "type": "photo", "canViewMedia": true, "postId": "2676873092", "url": "https://public-api.fansmetric.com/media-proxy?url=...&exp=...&sig=..." }, { "type": "photo", "canViewMedia": true, "postId": "2661473796", "url": "https://public-api.fansmetric.com/media-proxy?url=...&exp=...&sig=..." } ] }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Add Posts to Label Section: API Reference › Post Labels. Page: https://api-docs.fansmetric.com/api-reference/post-labels/add-posts-to-label Adds one or more posts to a label in a single call. Re-adding a post that is already on the label is harmless, and a post can carry several labels at once — so you do not need to check membership first. **Endpoint:** `POST /v1/{account_id}/post-labels/{label_id}/posts` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_post_labels_add_posts` Adds posts to a label. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `label_id` | path | yes | | The label to add to. Numeric. | | `post_ids` | body | yes | | Array of post IDs to add. Must contain at least one entry. | ## Request body example ```json { "post_ids": [2676873092, 2661473796] } ``` ## Notes Every media `url` is a FansMetric link that expires after 2 hours, not an OnlyFans address — see [Media URLs](https://api-docs.fansmetric.com/media-urls). Upstream OnlyFans endpoint: `POST /api2/v2/labels/{label_id}/posts`. Adding a post that is already on the label is not an error — the response reports the resulting state either way. To take one back off, use [Remove Post from Label](https://api-docs.fansmetric.com/api-reference/post-labels/remove-post-from-label). ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.label` | object | The label after the change, including its refreshed `postsCount` and preview strip — enough to update a label tile without a second call. | | `data.success` | boolean | Confirms the call went through. | ## Example response (200) ```json { "data": { "label": { "id": 9844743, "name": "Behind the scenes", "type": "custom", "isClearInProgress": false, "postsCount": 6, "posts": [ { "type": "photo", "canViewMedia": true, "postId": "2676873092", "url": "https://public-api.fansmetric.com/media-proxy?url=...&exp=...&sig=..." } ] }, "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Remove Post from Label Section: API Reference › Post Labels. Page: https://api-docs.fansmetric.com/api-reference/post-labels/remove-post-from-label Takes one post off a label. The post itself is untouched — only the association goes. There is no bulk remove, so this is one post per call. **Endpoint:** `DELETE /v1/{account_id}/post-labels/{label_id}/posts/{post_id}` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_post_labels_remove_post` Removes a post from a label. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `label_id` | path | yes | | The label to remove from. Numeric. | | `post_id` | path | yes | | The post to remove. Numeric. | ## Notes Every media `url` is a FansMetric link that expires after 2 hours, not an OnlyFans address — see [Media URLs](https://api-docs.fansmetric.com/media-urls). Upstream OnlyFans endpoint: `DELETE /api2/v2/labels/{label_id}/post/{post_id}`. One post per call — OnlyFans offers no bulk remove. To clear several, loop over them. The post keeps every other label it carries, and is not deleted or archived. Returns the label's resulting state, so a label tile can be updated straight from the response. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data` | object | The label after the change — `id`, `name`, `type`, the refreshed `postsCount` and its preview strip. | ## Example response (200) ```json { "data": { "id": 9895427, "name": "Photo sets", "type": "custom", "isClearInProgress": false, "postsCount": 1, "posts": [ { "type": "photo", "canViewMedia": true, "postId": "2661473796", "url": "https://public-api.fansmetric.com/media-proxy?url=...&exp=...&sig=..." } ] }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Bookmarks Section: API Reference › Bookmarks. Page: https://api-docs.fansmetric.com/api-reference/bookmarks/list-bookmarks Returns the creator's Saved for later collection. Saved posts and saved chat messages come back in the same feed, so branch on `responseType` before rendering a row — saved messages carry chat fields that saved posts do not. Narrow to one kind with `entity_type`. **Endpoint:** `GET /v1/{account_id}/bookmarks` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_bookmarks_list` Lists saved posts and messages. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `limit` | query | no | | Page size. Default 10. Min 1, max 100. | | `offset` | query | no | | Rows to skip. Default 0. | | `category` | query | no | | Media bucket to return: `all` (default), `photos`, `videos`, `audios`, `other`, `locked`. `other` holds text-only items; `locked` holds items whose paywall can no longer be opened. | | `entity_type` | query | no | | What to include: `posts`, `messages`, or `all` (default) for both. | | `filter` | query | no | | Restrict by age: `date_last_1_week`, `date_last_1_month`, `date_last_3_months`. Omit for all time. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/posts/bookmarks/{category}/`. **Two different row shapes share this feed.** Saved messages carry `chatUserId`, `fromUser`, `price` and `canPurchase`; saved posts do not. Always branch on `responseType` rather than probing for fields. Add and remove entries with [Bookmark Post](https://api-docs.fansmetric.com/api-reference/posts/bookmark-post) and [Remove Post Bookmark](https://api-docs.fansmetric.com/api-reference/posts/remove-post-bookmark). Offset-paginated. `_pagination.next_page` carries `category`, `entity_type` and `filter` across. - Mixed feed — branch on `responseType` (`post` or `message`) before rendering a row ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[].responseType` | string | `post` or `message`. Both kinds are mixed together when `entity_type=all`, so branch on this before reading the rest of the row. | | `data.list[].id` | integer | Post or message ID, depending on `responseType`. | | `data.list[].text` | string | Caption or message body, as HTML. | | `data.list[].price` | integer | Price. Saved messages only. | | `data.list[].chatUserId` | integer | The fan on the other side of the chat. Saved messages only. | | `data.list[].fromUser` | object | Who sent the message. Saved messages only. | | `data.list[].isAddedToBookmarks` | boolean | Always `true` in this feed — every row here is saved by definition. | | `data.hasMore` | boolean | Whether another page exists. | ## Example response (200) ```json { "data": { "list": [ { "responseType": "message", "id": 10256279613051, "text": "

saved this one for later

", "price": 0, "isFree": true, "isOpened": true, "isLiked": false, "isPinned": false, "isAddedToBookmarks": true, "mediaCount": 0, "isMediaReady": true, "media": [], "previews": [], "createdAt": "2026-07-02T09:14:22+00:00", "changedAt": "2026-07-02T09:14:22+00:00", "chatUserId": 987654321, "fromUser": { "id": 987654321, "_view": "c" }, "canPurchase": false, "canPurchaseReason": "free" } ], "hasMore": false }, "_pagination": { "next_page": null }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Bookmark Categories Section: API Reference › Bookmarks. Page: https://api-docs.fansmetric.com/api-reference/bookmarks/list-bookmark-categories Returns the creator's saved-item categories, plus an `all` summary with total saved post and message counts and a preview strip — enough to build category tabs without fetching each bucket. An empty `list` alongside a non-zero count is normal: it means items are saved but no custom categories exist. **Endpoint:** `GET /v1/{account_id}/bookmarks/categories` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_bookmarks_list_categories` Lists bookmark categories with totals. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `limit` | query | no | | Page size. Default 10. Min 1, max 100. | | `offset` | query | no | | Rows to skip. Default 0. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/posts/bookmarks/categories`. An empty `list` next to a non-zero `all.messageCount` is the normal case, not a bug — it means the creator has saved things but never sorted them into categories, so everything lives under `all`. Fetch the items themselves with [List Bookmarks](https://api-docs.fansmetric.com/api-reference/bookmarks/list-bookmarks). ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list` | array | Categories the creator has made. Empty when they have not made any — that is not an error. | | `data.all.postCount` | integer | Total saved posts across the whole collection. | | `data.all.messageCount` | integer | Total saved chat messages across the whole collection. | | `data.all.posts` | array | Preview strip across the whole collection, for an "All" tab thumbnail. | | `data.hasMore` | boolean | Whether another page of categories exists. | ## Example response (200) ```json { "data": { "list": [], "hasMore": false, "order": "asc", "sort": "recent", "all": { "postCount": 0, "messageCount": 5, "posts": [ { "type": "text", "canViewMedia": true, "postId": "10256279613051" }, { "type": "text", "canViewMedia": true, "postId": "10260665407480" } ] } }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Vault Media Section: API Reference › Vault. Page: https://api-docs.fansmetric.com/api-reference/vault/list-vault-media Returns media items stored in the creator's vault — the personal library used to compose posts, stories, and chat messages. Includes uploaded photos, videos, GIFs, and audio along with engagement counters and per-item state across the post/story/message/stream/uploads lists. **Endpoint:** `GET /v1/{account_id}/vault/media` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_vault_list_media` Lists vault media items with optional filtering by list, type, or search. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `limit` | query | no | | Page size. Default 24. Min 1, max 100. | | `offset` | query | no | | Rows to skip. Default 0. | | `field` | query | no | | Sort key. One of `recent`, `most-liked`, `highest-tips`. Default `recent`. | | `sort` | query | no | | Sort direction. `desc` (default) or `asc`. | | `list` | query | no | | Restrict to a vault list (category). Use `all` (default) for everything, or pass a list `id` from [List Vault Lists](https://api-docs.fansmetric.com/api-reference/vault/list-vault-lists). | | `type` | query | no | | Filter by media type: `photo`, `gif`, `video`, `audio`. Omit for all. | | `query` | query | no | | Text search across media metadata. | | `before_publish_date` | query | no | | ISO timestamp; only return media added before this date. Useful for backfilling. | ## Notes Every media `url` is a FansMetric link that expires after 2 hours, not an OnlyFans address — see [Media URLs](https://api-docs.fansmetric.com/media-urls). Upstream OnlyFans endpoint: `GET /api2/v2/vault/media`. Offset-based pagination — `_pagination.next_page` is pre-built with the next `offset` when more results exist. Use the returned `id` values directly in `POST /posts.mediaFiles`, mass-message `mediaFiles`, or chat `mediaFiles`. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[]` | array | Vault media items on this page. | | `data.list[].id` | integer | Vault media ID. Use in `mediaFiles` of `POST /posts`, mass messages, or `mediaIds` of vault list operations. | | `data.list[].type` | string | `photo`, `video`, `gif`, or `audio`. | | `data.list[].createdAt` | string | ISO timestamp when the media was added to the vault. | | `data.list[].isReady` | boolean | `true` once OnlyFans has finished transcoding the file. | | `data.list[].counters` | object | Lifetime engagement counters across all surfaces the media has appeared on (likes, tips). | | `data.list[].files` | object | Per-variant URL set: `full`, `thumb`, `preview`, `squarePreview`. Each variant carries `url`, `width`, `height`, and (for `full`) `size`. | | `data.list[].duration` | number | Duration in seconds (videos / audio). `0` for photos and GIFs. | | `data.list[].listStates[]` | array | Per-list membership state — one entry per system list (`posts`, `stories`, `messages`, etc.) with `hasMedia` and `canAddMedia`. | | `data.hasMore` | boolean | Whether more pages remain. | ## Example response (200) ```json { "data": { "list": [ { "id": 123456789, "type": "photo", "createdAt": "2026-05-14T10:30:00+00:00", "isReady": true, "canView": true, "hasError": false, "counters": { "likesCount": 12, "tipsSumm": 50 }, "files": { "full": { "url": "https://public-api.fansmetric.com/media-proxy?url=...&exp=...&sig=...", "width": 1080, "height": 1920, "size": 234567 }, "thumb": { "url": "https://public-api.fansmetric.com/media-proxy?url=...&exp=...&sig=...", "width": 300, "height": 533 }, "preview": { "url": "https://public-api.fansmetric.com/media-proxy?url=...&exp=...&sig=...", "width": 1080, "height": 1920 }, "squarePreview": { "url": "https://public-api.fansmetric.com/media-proxy?url=...&exp=...&sig=...", "width": 600, "height": 600 } }, "duration": 0, "hasPosts": true, "listStates": [ { "id": 1, "type": "posts", "name": "Posts", "hasMedia": true, "canAddMedia": false }, { "id": 2, "type": "stories", "name": "Stories", "hasMedia": false, "canAddMedia": true }, { "id": 3, "type": "messages", "name": "Messages", "hasMedia": false, "canAddMedia": true } ] } ], "hasMore": true }, "_pagination": { "next_page": "/v1/12345678/vault/media?limit=24&offset=24" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Vault Media Section: API Reference › Vault. Page: https://api-docs.fansmetric.com/api-reference/vault/get-vault-media Returns one vault media item by ID — the same object you see inside List Vault Media. Use it to get fresh media links for an item you already know, without paging the whole vault again. **Endpoint:** `GET /v1/{account_id}/vault/media/{media_id}` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_vault_list_media` Returns a single vault media item, with freshly signed media links. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `media_id` | path | yes | | Vault media ID, as returned by [List Vault Media](https://api-docs.fansmetric.com/api-reference/vault/list-vault-media). | | `refresh` | query | no | | Pass any value to skip the cache and ask OnlyFans directly. Use it to renew [media links](https://api-docs.fansmetric.com/media-urls) that have expired. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/vault/media/{media_id}`. Served from a 1-hour cache that every [List Vault Media](https://api-docs.fansmetric.com/api-reference/vault/list-vault-media) page fills in advance, so opening an item straight after browsing usually costs no OnlyFans call at all. Pass `refresh=1` to bypass that cache. Do this when a media link has expired — you get a brand-new set of links that expire 2 hours from then. The media links in `files` expire after 2 hours. Store this `id`, not the links; see [Media URLs](https://api-docs.fansmetric.com/media-urls). - `400` if `media_id` is not numeric ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.id` | integer | Vault media ID. | | `data.type` | string | `photo`, `video`, `gif`, or `audio`. | | `data.createdAt` | string | ISO timestamp when the media was added to the vault. | | `data.isReady` | boolean | `true` once OnlyFans has finished transcoding the file. | | `data.counters` | object | Lifetime engagement counters across every surface the media has appeared on. | | `data.files` | object | Per-variant link set: `full`, `thumb`, `preview`, `squarePreview`. Each `url` is a FansMetric media link that expires after 2 hours — see [Media URLs](https://api-docs.fansmetric.com/media-urls). | | `data.duration` | number | Duration in seconds (videos / audio). `0` for photos and GIFs. | ## Example response (200) ```json { "data": { "id": 123456789, "type": "photo", "createdAt": "2026-05-14T10:30:00+00:00", "isReady": true, "canView": true, "counters": { "likesCount": 12, "tipsSumm": 50 }, "files": { "full": { "url": "https://public-api.fansmetric.com/media-proxy?url=...&exp=...&sig=...", "width": 1080, "height": 1920, "size": 234567 }, "thumb": { "url": "https://public-api.fansmetric.com/media-proxy?url=...&exp=...&sig=...", "width": 300, "height": 533 } }, "duration": 0 }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Vault Lists Section: API Reference › Vault. Page: https://api-docs.fansmetric.com/api-reference/vault/list-vault-lists Returns the vault's categories — system lists (Posts, Stories, Messages, Streams, Uploads) plus any custom folders the creator has created. Drives the parent dropdown for vault picker UIs. **Endpoint:** `GET /v1/{account_id}/vault/lists` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_vault_list_lists` Lists vault categories (system + custom folders). ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `limit` | query | no | | Page size. Default 24. Min 1, max 100. | | `offset` | query | no | | Rows to skip. Default 0. | | `query` | query | no | | Find custom lists by name. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/vault/lists`. System lists (`stories`, `media_stickers`, `posts`, `messages`, `streams`) are managed by OnlyFans — only `custom` lists can be created, renamed, or deleted via this API. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[]` | array | Vault categories on this page. | | `data.list[].id` | integer | Vault list ID. Pass as the `list` filter on [List Vault Media](https://api-docs.fansmetric.com/api-reference/vault/list-vault-media). | | `data.list[].type` | string | One of `stories`, `streams`, `media_stickers`, `posts`, `messages`, `custom`. | | `data.list[].name` | string | Display name. Custom folders use the creator-chosen name. | | `data.list[].canUpdate` | boolean | `true` for custom folders that can be renamed; `false` for system lists. | | `data.list[].canDelete` | boolean | `true` for custom folders that can be deleted; `false` for system lists. | | `data.list[].videosCount` | integer | Number of videos in the list. | | `data.list[].photosCount` | integer | Number of photos in the list. | | `data.list[].gifsCount` | integer | Number of GIFs in the list. | | `data.list[].audiosCount` | integer | Number of audio items in the list. | | `data.list[].medias` | array | Small preview strip of items — used for UI thumbnails. | | `data.all` | object | Aggregate counts across every list (`videosCount`, `photosCount`, `gifsCount`, `audiosCount`). | | `data.canCreateVaultLists` | boolean | Whether the account can create new custom folders. | ## Example response (200) ```json { "data": { "list": [ { "id": 1, "type": "stories", "name": "Stories", "canUpdate": false, "canDelete": false, "videosCount": 0, "photosCount": 0, "gifsCount": 0, "audiosCount": 0, "medias": [] }, { "id": 2, "type": "media_stickers", "name": "Uploads", "canUpdate": false, "canDelete": false, "videosCount": 0, "photosCount": 0, "gifsCount": 0, "audiosCount": 0, "medias": [] }, { "id": 3, "type": "posts", "name": "Posts", "canUpdate": false, "canDelete": false, "videosCount": 0, "photosCount": 5, "gifsCount": 0, "audiosCount": 0, "medias": [{ "type": "photo", "url": "..." }] }, { "id": 4, "type": "messages", "name": "Messages", "canUpdate": false, "canDelete": false, "videosCount": 1, "photosCount": 4, "gifsCount": 0, "audiosCount": 2, "medias": [] }, { "id": 9, "type": "custom", "name": "Favourites", "canUpdate": true, "canDelete": true, "videosCount": 3, "photosCount": 6, "gifsCount": 0, "audiosCount": 0, "medias": [] } ], "all": { "videosCount": 4, "photosCount": 15, "gifsCount": 0, "audiosCount": 2, "medias": [] }, "hasMore": false, "canCreateVaultLists": true, "order": "asc", "sort": "default" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Vault Media Processing Section: API Reference › Vault. Page: https://api-docs.fansmetric.com/api-reference/vault/list-vault-media-processing Returns the media items the OnlyFans converter is currently transcoding for this account. Each one disappears once `isReady` flips to `true`. Mirrors the "Processing" strip the OnlyFans vault UI polls — useful as a progress feed during bulk uploads. **Endpoint:** `GET /v1/{account_id}/vault/media/processing` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_vault_list_processing` Lists vault media items currently being transcoded by OnlyFans. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/vault/media/processing`. Poll this during bulk uploads to render a per-file progress strip. Cross-reference returned `id`s with the upload-side IDs to track each file's transcoding status. Once an item leaves this list, fetch it via [List Vault Media](https://api-docs.fansmetric.com/api-reference/vault/list-vault-media) — it will be there with `isReady: true` and full file URLs. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[]` | array | In-flight media items. Empty when no uploads are processing. | | `data.list[].id` | integer | Vault media ID — already assigned even though transcoding is still in progress. | | `data.list[].type` | string | `photo`, `video`, `gif`, or `audio`. | | `data.list[].isReady` | boolean | Always `false` while the item is in this list; flips to `true` when transcoding completes and the item moves into the main vault listing. | | `data.list[].hasError` | boolean | `true` if OnlyFans rejected the file during processing. | | `data.list[].files` | object | Variant URL set. While processing, most URLs are `null`. | ## Example response (200) ```json { "data": { "list": [ { "id": 4067402434, "type": "video", "createdAt": "2026-05-30T08:00:00+00:00", "isReady": false, "canView": false, "hasError": false, "files": { "full": { "url": null }, "thumb": null, "preview": null, "squarePreview": null }, "duration": 0 } ] }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Vault Media Types Section: API Reference › Vault. Page: https://api-docs.fansmetric.com/api-reference/vault/get-vault-media-types Returns the catalog of supported vault media types (`photo`, `gif`, `video`, `audio`) along with per-type counts and feature flags. Same reference data the OnlyFans vault filter dropdown shows. Safe to cache client-side — counts change with vault writes but the type catalog itself is static. **Endpoint:** `GET /v1/{account_id}/vault/media/types` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_vault_read_types` Returns the supported vault media types with per-type counts. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/vault/media/types`. Use the `type` value as the `type` filter on [List Vault Media](https://api-docs.fansmetric.com/api-reference/vault/list-vault-media). ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.list[]` | array | One entry per supported media type. | | `data.list[].type` | string | `photo`, `gif`, `video`, or `audio`. | | `data.list[].count` | integer | Number of vault items of this type. | ## Example response (200) ```json { "data": { "list": [ { "type": "photo", "count": 1234 }, { "type": "gif", "count": 12 }, { "type": "video", "count": 56 }, { "type": "audio", "count": 7 } ] }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Sort Vault Lists Section: API Reference › Vault. Page: https://api-docs.fansmetric.com/api-reference/vault/sort-vault-lists Persists the creator's preferred ordering for vault lists. The chosen sort applies the next time [List Vault Lists](https://api-docs.fansmetric.com/api-reference/vault/list-vault-lists) is called. Pass one of the named sorts (`media`, `recent`, `name`, `default`) with a direction, or `custom` with an explicit `customOrder` array of list IDs. **Endpoint:** `POST /v1/{account_id}/vault/lists/sort` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_vault_lists_sort` Persists the vault list ordering preference. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `sort` | body | yes | | One of `media` (item count), `recent` (last modified), `name` (alphabetical), `default` (OF default order), or `custom`. | | `order` | body | no | | `asc` or `desc`. Required for named sorts. Ignored when `sort` is `custom`. | | `customOrder` | body | no | | Array of vault list IDs in the exact order to persist. Required when `sort` is `custom`; must include every custom list the account owns. | ## Request body example ```json { "sort": "media", "order": "asc" } ``` ## Notes Upstream OnlyFans endpoint: `POST /api2/v2/vault/lists/sort`. Two request shapes: named sort `{ "sort": "media", "order": "asc" }`, or custom order `{ "sort": "custom", "customOrder": [25689099, 25689097, 25812512] }`. When `sort` is `custom`, `customOrder` must cover every custom list — OnlyFans rejects partial orderings. ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Vault Media Release Forms Section: API Reference › Vault. Page: https://api-docs.fansmetric.com/api-reference/vault/get-release-forms Returns the release form(s) attached to a vault media item. A release form is the contract/consent record OnlyFans requires when other people appear in the content. Use this to display signing status, tagged users, and form metadata. **Endpoint:** `GET /v1/{account_id}/vault/media/{media_id}/release-forms` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_vault_read_release_forms` Returns release forms attached to a vault media item. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `media_id` | path | yes | | The vault media ID. Numeric. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/vault/media/{media_id}/release-forms`. Returns `404` if the media item does not exist in this account's vault. Returns an empty array when the media has no release form attached — not an error. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data[]` | array | Release forms attached to the media. Empty array if none. | | `data[].id` | integer | Release form ID. | | `data[].name` | string | Display name of the release form template. | | `data[].status` | string | Signing status — typically `signed`, `pending`, or `declined`. | | `data[].users[]` | array | Users tagged on the form with their individual signing status. | ## Example response (200) ```json { "data": [ { "id": 42, "name": "Standard Model Release", "status": "signed", "createdAt": "2026-04-01T12:00:00+00:00", "users": [ { "id": 987, "username": "guest_model", "status": "signed" } ] } ], "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Attach Tags To Vault Media Section: API Reference › Vault. Page: https://api-docs.fansmetric.com/api-reference/vault/attach-tags Tags the people who appear in a vault item — creators, guests and partners. Use it after uploading to tag the creators in a new file: see [Uploading Media](https://api-docs.fansmetric.com/uploading-media#vault). **Endpoint:** `PUT /v1/{account_id}/vault/media/{media_id}/attach` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_media_upload` Sets the creator, guest and partner tags on a vault item. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `media_id` | path | yes | | The vault media ID. | | `rfTag` | body | no | array | OnlyFans user IDs of the creators to tag. | | `rfGuest` | body | no | array | Release-form guest IDs. | | `rfPartner` | body | no | array | Release-form partner IDs. | ## Request body example ```json { "rfTag": [12345, 67890], "rfGuest": [], "rfPartner": [] } ``` ## Notes Upstream OnlyFans endpoint: `PUT /api2/v2/vault/media/{media_id}/attach`. Send at least one list. Each list you send replaces that kind of tag on the item, so an empty list removes them. A list you leave out is not sent. A file that was only just sent can take a few seconds to reach the vault. If this fails right after sending, wait and try again — the FansMetric app waits 3 seconds and tries up to 3 times. To see who is tagged now, use [Get Vault Media Release Forms](https://api-docs.fansmetric.com/api-reference/vault/get-release-forms). It uses the upload permission, `api_media_upload`, because tagging creators is part of uploading. - `400` when no list is sent, or a list holds anything but whole-number IDs ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Lookup Vault Media by Hash Section: API Reference › Vault. Page: https://api-docs.fansmetric.com/api-reference/vault/lookup-hash Checks whether the creator already has a vault media item matching the given MD5 hash + size. Returns the existing vault media object when there is a match, `404` otherwise. Step 1 of [Uploading Media](https://api-docs.fansmetric.com/uploading-media), which also explains how to work out the hash. **Endpoint:** `GET /v1/{account_id}/vault/media/hash` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_media_upload` Resolves a content hash to an existing vault media item, or 404 if absent. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `h` | query | yes | | The file's MD5, as 32 lowercase letters and digits. Files over 5 MB use a different fingerprint — [Uploading Media](https://api-docs.fansmetric.com/uploading-media#duplicates) shows how to work it out. | | `size` | query | yes | integer | File size in bytes. | ## Notes Every media `url` is a FansMetric link that expires after 2 hours, not an OnlyFans address — see [Media URLs](https://api-docs.fansmetric.com/media-urls). Upstream OnlyFans endpoint: `GET /api2/v2/vault/media/hash?h=…&size=…`. When the file does not exist in the vault, OnlyFans returns `404`. Treat that as "proceed with the upload" rather than as an error. On a match, put the item's `id` in `mediaFiles` and skip the upload. On a `404`, carry on with [Create Signed Upload](https://api-docs.fansmetric.com/api-reference/media-upload/create-signed-upload). ## Response fields | Field | Type | Description | | --- | --- | --- | | `data` | object | Existing vault media object — same shape as entries in [List Vault Media](https://api-docs.fansmetric.com/api-reference/vault/list-vault-media). | ## Example response (200) ```json { "data": { "id": 1234567890, "type": "photo", "createdAt": "2026-04-12T08:00:00+00:00", "isReady": true, "files": { "full": { "url": "https://public-api.fansmetric.com/media-proxy?url=...&exp=...&sig=...", "width": 1080, "height": 1920, "size": 234567 }, "thumb": { "url": "https://public-api.fansmetric.com/media-proxy?url=...&exp=...&sig=...", "width": 300, "height": 533 } }, "duration": 0 }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Delete Vault Media Section: API Reference › Vault. Page: https://api-docs.fansmetric.com/api-reference/vault/delete-media Removes one or more media items from the creator's vault, the same as **Remove** in the OnlyFans vault. To take media out of a custom list but keep it in the vault, use [Remove Media From Vault List](https://api-docs.fansmetric.com/api-reference/vault/remove-media-from-list). **Endpoint:** `DELETE /v1/{account_id}/vault/media` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_vault_delete_media` Removes media items from the vault. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `mediaIds` | body | yes | array | Vault media IDs to remove, as numbers or strings of digits. At least one. | ## Request body example ```json { "mediaIds": ["123456789", "987654321"] } ``` ## Notes Upstream OnlyFans endpoint: `PUT /api2/v2/vault/media/hidden`. IDs can be numbers or strings of digits. - `400` when `mediaIds` is missing, empty, or holds anything but vault media IDs ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Create Vault List Section: API Reference › Vault. Page: https://api-docs.fansmetric.com/api-reference/vault/create-list Creates a new custom vault list (folder). Built-in lists (Stories, Posts, Messages, Streams, Uploads) are managed by OnlyFans and cannot be created via this API — only custom folders. **Endpoint:** `POST /v1/{account_id}/vault/lists` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_vault_lists_create` Creates a new custom vault folder. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `name` | body | yes | | Display name for the new folder. | ## Request body example ```json { "name": "VIP Content" } ``` ## Notes Upstream OnlyFans endpoint: `POST /api2/v2/vault/lists`. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data` | object | Created vault list — same shape as entries in [List Vault Lists](https://api-docs.fansmetric.com/api-reference/vault/list-vault-lists). `type: "custom"`, `canUpdate: true`, `canDelete: true`. | ## Example response (200) ```json { "data": { "id": 1234, "type": "custom", "name": "VIP Content", "canUpdate": true, "canDelete": true, "videosCount": 0, "photosCount": 0, "gifsCount": 0, "audiosCount": 0, "medias": [] }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Rename Vault List Section: API Reference › Vault. Page: https://api-docs.fansmetric.com/api-reference/vault/rename-list Renames a custom vault list. Only lists where `canUpdate` is `true` (custom folders) may be renamed — system lists return `403` from OnlyFans. **Endpoint:** `PATCH /v1/{account_id}/vault/lists/{list_id}` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_vault_lists_rename` Renames a custom vault folder. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `list_id` | path | yes | | The vault list ID to rename. | | `name` | body | yes | | New display name for the folder. | ## Request body example ```json { "name": "Renamed Folder" } ``` ## Notes Upstream OnlyFans endpoint: `PATCH /api2/v2/vault/lists/{list_id}`. The OnlyFans web client uses `PATCH`; using `PUT` upstream silently fails to persist the rename. ## Example response (200) ```json { "data": { "id": 1234, "type": "custom", "name": "Renamed Folder", "canUpdate": true, "canDelete": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Delete Vault List Section: API Reference › Vault. Page: https://api-docs.fansmetric.com/api-reference/vault/delete-list Deletes a custom vault list. Media inside the list is **not** deleted from the vault — only the list itself. Only lists where `canDelete` is `true` may be deleted. **Endpoint:** `DELETE /v1/{account_id}/vault/lists/{list_id}` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_vault_lists_delete` Deletes a custom vault folder. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `list_id` | path | yes | | The vault list ID to delete. | ## Notes Upstream OnlyFans endpoint: `DELETE /api2/v2/vault/lists/{list_id}`. The media in the list stays in the vault. OnlyFans can also remove it when you delete a list in OnlyFans, but this endpoint never does. To remove media, use [Delete Vault Media](https://api-docs.fansmetric.com/api-reference/vault/delete-media). - `400` when the body sets `clearMedia` to anything but `false` ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Add Media To Vault List Section: API Reference › Vault. Page: https://api-docs.fansmetric.com/api-reference/vault/add-media-to-list Adds one or more existing vault media items to a custom vault list. **Endpoint:** `POST /v1/{account_id}/vault/lists/{list_id}/media` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_vault_lists_add_media` Adds vault media to a custom folder. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `list_id` | path | yes | | The vault list ID to add media to. | | `mediaIds` | body | yes | array | Vault media IDs to add, as numbers or strings of digits. At least one. | ## Request body example ```json { "mediaIds": ["123456789", "987654321"] } ``` ## Notes Upstream OnlyFans endpoint: `POST /api2/v2/vault/lists/{list_id}/media`. IDs can be numbers or strings of digits. Adding media that's already in the list is a no-op — OnlyFans does not return an error for duplicates. - `400` when `mediaIds` is missing, empty, or holds anything but vault media IDs ## Example response (200) ```json { "data": { "id": 1234, "type": "custom", "name": "VIP Content", "canUpdate": true, "canDelete": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Remove Media From Vault List Section: API Reference › Vault. Page: https://api-docs.fansmetric.com/api-reference/vault/remove-media-from-list Removes one or more vault media items from a custom list. The media is **not** deleted from the vault — only removed from the list. Use [Delete Vault Media](https://api-docs.fansmetric.com/api-reference/vault/delete-media) to remove the file from the vault. **Endpoint:** `DELETE /v1/{account_id}/vault/lists/{list_id}/media` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_vault_lists_remove_media` Removes vault media from a custom folder (does not delete the media). ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `list_id` | path | yes | | The vault list ID to remove media from. | | `mediaIds` | body | yes | array | Vault media IDs to take out of the list, as numbers or strings of digits. At least one. | ## Request body example ```json { "mediaIds": ["123456789", "987654321"] } ``` ## Notes Upstream OnlyFans endpoint: `DELETE /api2/v2/vault/lists/{list_id}/media`. IDs can be numbers or strings of digits. - `400` when `mediaIds` is missing, empty, or holds anything but vault media IDs ## Example response (200) ```json { "data": { "id": 1234, "type": "custom", "name": "VIP Content", "canUpdate": true, "canDelete": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Create Signed Upload Section: API Reference › Media Upload. Page: https://api-docs.fansmetric.com/api-reference/media-upload/create-signed-upload Gets the addresses to upload one file to. Step 2 of [Uploading Media](https://api-docs.fansmetric.com/uploading-media), which walks through every step from checking the vault to attaching the file to a message. **Endpoint:** `POST /v1/{account_id}/upload/signed/create` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_media_upload` Returns the addresses to upload one file to. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `fileName` | body | yes | string | The file's name, such as `photo.jpg`. | | `size` | body | yes | integer | The file's size in bytes. Files over 5 MB (5,242,880 bytes) go up in 5 MB pieces. | | `contentType` | body | yes | string | The file's type, such as `image/jpeg` or `video/mp4`. | ## Request body example ```json { "fileName": "photo.jpg", "size": 3014607, "contentType": "image/jpeg" } ``` ## Notes Upstream OnlyFans endpoint: `POST /api2/v2/upload/signed/create`. Files of 5 MB or less go up in one piece, and the answer has `putUrl`. Bigger files go up in 5 MB pieces, and the answer has `uploadId` plus one `putUrl` per piece in `keys[]`. Asking for one piece always gets a one-piece answer, even for a video. What to do with the answer: [Uploading Media](https://api-docs.fansmetric.com/uploading-media#upload). - `400` when `fileName`, `size` or `contentType` is missing, or a field has the wrong type — the message says which ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.key` | string | The name OnlyFans stored the file under. Every later step uses it. | | `data.uploadToken` | string | Proof of this upload. [Convert Upload](https://api-docs.fansmetric.com/api-reference/media-upload/convert-upload) needs it. | | `data.putUrl` | string | One-piece uploads only. Send the whole file here. | | `data.uploadId` | string | Uploads in pieces only. Pass it to [Finish Multipart Upload](https://api-docs.fansmetric.com/api-reference/media-upload/finish-multipart-upload). | | `data.keys[]` | array | Uploads in pieces only. One `{ part, putUrl }` per piece — send each piece to its own `putUrl`. | | `data.getUrl` | string | Where OnlyFans will serve the file from. No later step needs it. | ## Example response (200) ```json { "data": { "key": "upload/111222333/8a3d4c2e-7f1b-4c5d-9e8f-1a2b3c4d5e6f/529838163914/photo.jpg", "uploadToken": "def456...", "putUrl": "https://of2transcoder.s3-accelerate.amazonaws.com/upload/111222333/8a3d4c2e-.../529838163914/photo.jpg?X-Amz-Signature=...", "getUrl": "https://upload.onlyfans.com/upload/111222333/8a3d4c2e-.../529838163914/photo.jpg?Policy=..." }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Finish Multipart Upload Section: API Reference › Media Upload. Page: https://api-docs.fansmetric.com/api-reference/media-upload/finish-multipart-upload Joins the pieces of a file that went up in pieces. Step 4 of [Uploading Media](https://api-docs.fansmetric.com/uploading-media). Only needed when [Create Signed Upload](https://api-docs.fansmetric.com/api-reference/media-upload/create-signed-upload) answered with `uploadId` and `keys[]` — a file sent in one piece is complete as soon as it arrives. **Endpoint:** `POST /v1/{account_id}/upload/signed/finish` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_media_upload` Joins an upload's pieces into one file. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `key` | body | yes | string | The `key` from the [Create Signed Upload](https://api-docs.fansmetric.com/api-reference/media-upload/create-signed-upload) answer. | | `uploadId` | body | yes | string | `uploadId` from the Create Signed Upload answer. | | `parts` | body | yes | array | One `{ ETag, PartNumber }` per piece, in `PartNumber` order. `ETag` is the header each piece's upload answered with — keep its double quotes. | ## Request body example ```json { "key": "upload/111222333/8a3d4c2e-7f1b-4c5d-9e8f-1a2b3c4d5e6f/529838163914/video.mp4", "uploadId": "abc123...", "parts": [ { "ETag": "\"d41d8cd98f00b204e9800998ecf8427e\"", "PartNumber": 1 }, { "ETag": "\"098f6bcd4621d373cade4e832627b4f6\"", "PartNumber": 2 } ] } ``` ## Notes Upstream OnlyFans endpoint: `POST /api2/v2/upload/signed/finish`. List the pieces in `PartNumber` order. Out of order, joining fails with `400`. Next: [register the file](https://api-docs.fansmetric.com/uploading-media#register). - `400` when `key`, `uploadId` or `parts` is missing, or a piece has no `ETag` or `PartNumber` — the message says which ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.ETag` | string | The joined file's fingerprint. Send it as `ETag` to [Convert Upload](https://api-docs.fansmetric.com/api-reference/media-upload/convert-upload). | ## Example response (200) ```json { "data": { "ETag": "\"098f6bcd4621d373cade4e832627b4f6-2\"" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Convert Upload Section: API Reference › Media Upload. Page: https://api-docs.fansmetric.com/api-reference/media-upload/convert-upload Registers an uploaded file with OnlyFans and returns it ready to attach to a message. The account's upload settings and watermark are applied for you. Step 5 of [Uploading Media](https://api-docs.fansmetric.com/uploading-media). **Endpoint:** `POST /v1/{account_id}/upload/convert` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_media_upload` Registers an uploaded file and returns it ready to attach. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `key` | body | yes | string | The `key` from the [Create Signed Upload](https://api-docs.fansmetric.com/api-reference/media-upload/create-signed-upload) answer. | | `uploadToken` | body | yes | string | `uploadToken` from the Create Signed Upload answer. | | `putUrl` | body | yes | string | The address you sent the file to. For a file in pieces, the first piece's `putUrl`. | | `ETag` | body | yes | string | One piece: the `ETag` header from sending the file, which is also the file's MD5. Pieces: the `ETag` from [Finish Multipart Upload](https://api-docs.fansmetric.com/api-reference/media-upload/finish-multipart-upload). Double quotes are optional. | | `contentType` | body | yes | string | The file type you gave Create Signed Upload, such as `image/jpeg`. It decides which of the account's watermark settings applies. | | `name` | body | no | string | The file name OnlyFans keeps. Defaults to the name at the end of `key`. | ## Request body example ```json { "key": "upload/111222333/8a3d4c2e-7f1b-4c5d-9e8f-1a2b3c4d5e6f/529838163914/photo.jpg", "uploadToken": "def456...", "putUrl": "https://of2transcoder.s3-accelerate.amazonaws.com/upload/111222333/8a3d4c2e-.../529838163914/photo.jpg?X-Amz-Signature=...", "ETag": "\"d41d8cd98f00b204e9800998ecf8427e\"", "contentType": "image/jpeg" } ``` ## Notes Upstream OnlyFans endpoint: `POST https://convert.onlyfans.com/file/upload`. Registering doesn't put the file in the vault — it gets there once it's sent in a message. See [Uploading Media](https://api-docs.fansmetric.com/uploading-media#vault). Where this fits: [Uploading Media](https://api-docs.fansmetric.com/uploading-media#register). - `400` when a field is missing or has the wrong type — the message says which - `400` with `Invalid input.` when `key` or `uploadToken` doesn't match the upload — use the `key` from the Create Signed Upload answer ## Response fields | Field | Type | Description | | --- | --- | --- | | `data` | object | The file, ready to attach: put it in `mediaFiles` of [Send Message](https://api-docs.fansmetric.com/api-reference/messages/send-message) or [Send Mass Message](https://api-docs.fansmetric.com/api-reference/mass-messages/send) as it is. | | `data.processId` | string | OnlyFans's reference for the file while it is processed. Pass it back unchanged. | | `data.host` | string | Pass it back unchanged. | | `data.name` | string | The file name. | | `data.extra` | string | Pass it back unchanged. | ## Example response (200) ```json { "data": { "processId": "abc123...", "host": "def456...", "name": "photo.jpg", "extra": "ghi789..." }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Create Promotion Section: API Reference › Promotions. Page: https://api-docs.fansmetric.com/api-reference/promotions/create-promotion Creates a new promotion (discount offer or free trial) on the creator's profile. Promotions can target new subscribers, expired subscribers, or both (`new_and_expired` creates two OF-side promotions in one call). For free-trial **links** specifically, prefer the `/v1/{account_id}/trial-links` endpoints — this is the lower-level OF-native primitive. **Endpoint:** `POST /v1/{account_id}/promotions` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_promotions_create` Creates a promotion (discount or free trial) targeting new and/or expired fans. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `type` | body | yes | | Audience. One of `new`, `expired`, `new_and_expired`. `new_and_expired` creates **two** OF promotions in a single call. | | `discount` | body | yes | | Discount percentage applied to the subscription. Range `1`–`100`. Set to `100` to turn the promotion into a Free Trial — `freeTrialDays` then becomes required. | | `subscribeCounts` | body | yes | | Limit on how many subscribers can claim. Set to `0` for unlimited. Max: `100`. | | `subscribeDays` | body | yes | | Days the discount remains in effect for a redeeming subscriber. Range `1`–`30`. | | `finishDays` | body | yes | | Days before the promotion expires. Range `0`–`30`. `0` means open-ended. | | `message` | body | no | | Optional message shown to subscribers (max 500 chars). | | `freeTrialDays` | body | no | | Required when `discount == 100`. Length of the free trial in days. Range `1`–`30`. | ## Request body example ```json { "type": "new", "discount": 50, "subscribeCounts": 100, "subscribeDays": 30, "finishDays": 7, "message": "Half off your first month! 🎉" } ``` ## Notes Upstream OnlyFans endpoint: `POST /api2/v2/promotions`. OnlyFans returns an array because `type=new_and_expired` produces two promotions. Single-audience calls still return an array of length 1. For a 100% discount (free trial), `freeTrialDays` is required and replaces the regular discount semantics. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data[]` | array | Created promotions. Length 1 for `new`/`expired`, length 2 for `new_and_expired`. | | `data[].id` | integer | OnlyFans promotion ID. Pass to [Finish Promotion](https://api-docs.fansmetric.com/api-reference/promotions/finish-promotion) to stop it early. | | `data[].type` | string | `new` or `expired` (the per-row audience, not the request `type`). | | `data[].canClaim` | boolean | Whether the promo is currently claimable by eligible fans. | | `data[].claimsCount` | integer | Number of subscribers who have already redeemed. | | `data[].createdAt` | string | ISO timestamp when the promo was created. | | `data[].finishedAt` | string | ISO timestamp when the promo expires (`createdAt + finishDays`). | | `data[].isFinished` | boolean | `true` once the promo has expired or been finished early. | ## Example response (200) ```json { "data": [ { "id": 123, "message": "Half off your first month!", "rawMessage": "Half off your first month!", "hasRelatedPromo": false, "price": 0, "type": "new", "canClaim": true, "claimsCount": 0, "subscribeCounts": 100, "subscribeDays": 30, "createdAt": "2026-06-01T12:00:00+00:00", "finishedAt": "2026-06-08T12:00:00+00:00", "isFinished": false } ], "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Finish Promotion Section: API Reference › Promotions. Page: https://api-docs.fansmetric.com/api-reference/promotions/finish-promotion Stops an active promotion immediately. The promotion is marked `isFinished: true` and stops accepting new claims; subscribers who already redeemed keep their existing discount duration. **Endpoint:** `POST /v1/{account_id}/promotions/{promo_id}/finish` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_promotions_finish` Ends an active promotion early. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `promo_id` | path | yes | | OnlyFans promotion ID — from the [Create Promotion](https://api-docs.fansmetric.com/api-reference/promotions/create-promotion) response or [List Promotions](https://api-docs.fansmetric.com/api-reference/reach/list-promotions). | ## Notes Upstream OnlyFans endpoint: `POST /api2/v2/promotions/{promo_id}/finish`. Idempotent — calling on an already-finished promo is a no-op rather than an error. Existing redemptions are not refunded or shortened; only future claims are blocked. ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # List Promotions & Trials Section: API Reference › Promotions. Page: https://api-docs.fansmetric.com/api-reference/promotions/list-promotions-trials Returns a single chronological feed that interleaves promotions and free-trial-link items — the same view that powers the OnlyFans "Promotions & Trials" tab. Each item is either a `promo` or a `trial` object — never both. **Endpoint:** `GET /v1/{account_id}/promotions-trials` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_promotions_trials_list` Lists promotions and free-trial links in a single chronological feed. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `limit` | query | no | | Page size. Default 100. Min 1, max 200. | | `offset` | query | no | | Rows to skip. Default 0. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/promotions-trials`. To filter to just promotions or just trials, branch on which key (`promo` or `trial`) is present on each item. For the trial-only feed (claim counts, subscribers, charts) use [`/v1/{account_id}/trial-links`](https://api-docs.fansmetric.com/api-reference/trial-links/list) and its companion endpoints. The `promotions-trials` payload is intentionally minimal — it powers the combined OF tab and is not a substitute for the per-trial endpoints. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.items[]` | array | Feed entries, newest first. Each entry has either a `promo` or a `trial` key — discriminate on which is present. | | `data.items[].promo` | object | Present for promotion entries. Same shape as [Create Promotion](https://api-docs.fansmetric.com/api-reference/promotions/create-promotion) response items. | | `data.items[].trial` | object | Present for trial-link entries — `id`, `url`, `trialLinkName`, `subscribeDays`, `subscribeCounts`, `claimCounts`, `createdAt`, `expiredAt`, `isFinished`. | | `data.hasMore` | boolean | Whether more pages remain. | ## Example response (200) ```json { "data": { "items": [ { "promo": { "id": 123, "message": "Half off your first month!", "rawMessage": "Half off your first month!", "hasRelatedPromo": false, "price": 0, "type": "new", "canClaim": true, "claimsCount": 12, "subscribeCounts": 100, "subscribeDays": 30, "createdAt": "2026-06-01T12:00:00+00:00", "finishedAt": "2026-06-08T12:00:00+00:00", "isFinished": false } }, { "trial": { "id": 4567, "url": "https://onlyfans.com/action/trial/4567/...", "trialLinkName": "Reddit June", "subscribeDays": 7, "subscribeCounts": 50, "claimCounts": 18, "createdAt": "2026-05-20T08:00:00+00:00", "expiredAt": "2026-07-20T08:00:00+00:00", "isFinished": false } } ], "hasMore": true }, "_pagination": { "next_page": "/v1/12345678/promotions-trials?limit=100&offset=100" }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Send Typing Indicator Section: API Reference › Chats. Page: https://api-docs.fansmetric.com/api-reference/chats/send-typing-indicator Shows the recipient a "Model is typing…" indicator in their chat for ~4 seconds. Call repeatedly while the model is actively typing — each call resets the indicator. **Endpoint:** `POST /v1/{account_id}/chats/{user_id}/typing` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_chats_typing` Surfaces the typing indicator in a fan's chat for ~4 seconds. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `user_id` | path | yes | | Fan/user ID of the conversation. | ## Notes Upstream OnlyFans endpoint: `POST /api2/v2/chats/{user_id}/typing`. Free on the OnlyFans side — does not consume upstream rate-limit credits. The indicator auto-expires after roughly 4 seconds. Throttle calls to at most one every ~3 seconds while typing is active. ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Mark Chat As Read Section: API Reference › Chats. Page: https://api-docs.fansmetric.com/api-reference/chats/mark-chat-as-read Marks a single chat as read without fetching its messages. Clears the unread badge for a conversation without paging through the message list. For the account-wide bulk version (mark every chat as read at once), see [Mark Chats as Read](https://api-docs.fansmetric.com/api-reference/chats/mark-as-read). **Endpoint:** `POST /v1/{account_id}/chats/{user_id}/mark-as-read` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_chats_mark_read` Clears the unread badge on a chat. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `user_id` | path | yes | | Fan/user ID of the conversation. | ## Notes Upstream OnlyFans endpoint: `POST /api2/v2/chats/{user_id}/mark-as-read`. Idempotent — calling on an already-read chat returns success. ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Mark Chat As Unread Section: API Reference › Chats. Page: https://api-docs.fansmetric.com/api-reference/chats/mark-chat-as-unread Marks a single chat as unread. Useful to flag a conversation for later follow-up — restores the unread badge in the OF chat list. **Endpoint:** `POST /v1/{account_id}/chats/{user_id}/mark-as-unread` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_chats_mark_unread` Restores the unread badge on a chat for follow-up. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `user_id` | path | yes | | Fan/user ID of the conversation. | ## Notes Upstream OnlyFans endpoint: `POST /api2/v2/chats/{user_id}/mark-as-unread`. ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Chat Message Section: API Reference › Messages. Page: https://api-docs.fansmetric.com/api-reference/messages/get-chat-message Returns a single message by ID from a chat — same per-message shape as entries in [List Chat Messages](https://api-docs.fansmetric.com/api-reference/messages/list-messages). Returns `404` when the message does not exist in this chat. **Endpoint:** `GET /v1/{account_id}/chats/{user_id}/messages/{message_id}` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_messages_read` Fetches a single chat message by ID. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `user_id` | path | yes | | Fan/user ID of the conversation. | | `message_id` | path | yes | | The message ID to fetch. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/chats/{user_id}/messages/{message_id}`. Returns the same per-message shape as the list endpoint — use this when you already have a `message_id` and don't want to re-paginate. ## Example response (200) ```json { "data": { "id": 9999999999, "text": "thanks for the tip!", "createdAt": "2026-05-30T12:00:00+00:00", "fromUser": { "id": 12345678 }, "isFree": true, "price": 0, "media": [] }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Attach Tags To Message Section: API Reference › Messages. Page: https://api-docs.fansmetric.com/api-reference/messages/attach-tags Attaches release-form tags (creator IDs, partner IDs, guest IDs) to a message that has already been sent. Used by automated workflows that upload media, send it, then attach the correct release-form tags after the fact. **Endpoint:** `POST /v1/{account_id}/messages/{message_id}/attach-tags` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_messages_attach_tags` Syncs release-form tags on an already-sent message. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `message_id` | path | yes | | The message ID to attach tags to. | | `rfTag` | body | no | | Array of OnlyFans creator user IDs to tag. Empty array clears existing creator tags. Omit the key entirely to leave creator tags unchanged. | | `rfPartner` | body | no | | Array of release-form partner IDs. Empty array clears existing partner tags. | | `rfGuest` | body | no | | Array of release-form guest IDs. Empty array clears existing guest tags. | ## Request body example ```json { "rfTag": [12345, 67890], "rfPartner": [], "rfGuest": [111222] } ``` ## Notes Upstream OnlyFans endpoint: `POST /api2/v2/messages/{message_id}/attach-tags`. **Sync semantics**: passing an empty array for a kind removes all existing tags of that kind. Omit the key entirely to leave that kind unchanged. To tag media in the vault rather than a message, use [Attach Tags To Vault Media](https://api-docs.fansmetric.com/api-reference/vault/attach-tags). ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get User List Section: API Reference › User Lists. Page: https://api-docs.fansmetric.com/api-reference/user-lists/get-user-list Returns metadata for a single custom user list — name, type, members count, sort. **Endpoint:** `GET /v1/{account_id}/user-lists/{list_id}` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_user_lists_read` Fetches a single custom user list by ID. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `list_id` | path | yes | | Custom list ID. | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/lists/{list_id}`. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data.id` | integer | List ID. | | `data.type` | string | `custom` for user-created lists; system lists use type-specific values. | | `data.name` | string | Display name. | | `data.postsCount` | integer | Members count (OF reuses the `postsCount` field name). | | `data.createdAt` | string | ISO timestamp when the list was created. | | `data.canUpdate` | boolean | Whether the list can be renamed. | | `data.canDelete` | boolean | Whether the list can be deleted. | ## Example response (200) ```json { "data": { "id": 47382, "type": "custom", "name": "VIP Fans", "postsCount": 15, "createdAt": "2026-01-12T08:00:00+00:00", "canUpdate": true, "canDelete": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Bulk Add Users To List Section: API Reference › User Lists. Page: https://api-docs.fansmetric.com/api-reference/user-lists/bulk-add-users Adds many fans to a single custom list in one round trip. Prefer this over calling [Add User to List](https://api-docs.fansmetric.com/api-reference/user-lists/add-member) in a loop — one OF call instead of N. **Endpoint:** `POST /v1/{account_id}/user-lists/{list_id}/users` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_user_lists_bulk_add_members` Adds many fans to a list in a single round trip. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `list_id` | path | yes | | Custom list ID. | | `user_ids` | body | yes | | Array of OnlyFans user IDs (integer) to add. Must contain at least one entry. | ## Request body example ```json { "user_ids": [12345678, 87654321, 11223344] } ``` ## Notes Upstream OnlyFans endpoint: `POST /api2/v2/lists/users`. The server rewrites the payload to OF's wire format (`{ "": [] }`) before forwarding — callers only send the canonical shape above. Partial-failure semantics: per-user errors are returned in `data.errors`. The overall request still succeeds (200) even when some adds fail. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data` | object | Empty success object when every user was added. If some adds fail (e.g. user deleted or blocked), `data.errors` is an object keyed by list ID with per-user-ID error arrays. | ## Example response (200) ```json { "data": { "errors": { "47382": { "999999999": ["User not found"] } } }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Clear User List Section: API Reference › User Lists. Page: https://api-docs.fansmetric.com/api-reference/user-lists/clear-user-list Removes every user from a list in a single call. The list itself is not deleted — use [Delete User List](https://api-docs.fansmetric.com/api-reference/user-lists/delete) for that. **Endpoint:** `DELETE /v1/{account_id}/user-lists/{list_id}/users` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_user_lists_clear_members` Empties a list (without deleting the list). ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `list_id` | path | yes | | Custom list ID. | ## Notes Upstream OnlyFans endpoint: `DELETE /api2/v2/lists/{list_id}/users`. The server sends `{}` as the body to OF as required by the upstream contract. ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Subscribe To User Section: API Reference › User Actions. Page: https://api-docs.fansmetric.com/api-reference/user-actions/subscribe-to-user Subscribes the authenticated account to another creator's profile. Useful for automated follow flows and reconnecting expired follows. If the target has a paid subscription price, OnlyFans charges the configured payment method. **Endpoint:** `POST /v1/{account_id}/users/{user_id}/subscribe` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_users_subscribe` Subscribes (or re-subscribes) the account to another creator. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID — the subscriber. | | `user_id` | path | yes | | OnlyFans user ID of the creator to subscribe to. | ## Notes Upstream OnlyFans endpoint: `POST /api2/v2/users/{user_id}/subscribe`. Returns `402` if OnlyFans declines payment (paid subscription, payment method failed). When re-subscribing after an expired follow, OnlyFans applies the current price — promo prices from the previous subscription are not retained. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data` | object | Updated OF user object for the target — reflects `subscribedBy: true`, `subscribedByExpireDate`, `subscribedByAutoprolong`, and the resolved `currentSubscribePrice`. | ## Example response (200) ```json { "data": { "id": 987654321, "username": "another_creator", "subscribedBy": true, "subscribedByExpireDate": "2026-07-01T12:00:00+00:00", "subscribedByAutoprolong": true, "currentSubscribePrice": 9.99 }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Get Notification Message Settings Section: API Reference › Notifications. Page: https://api-docs.fansmetric.com/api-reference/notifications/get-message-settings Returns the in-site notification preferences for the "Messages" group — the per-event toggles shown under OnlyFans → Settings → Notifications → Site → Messages. Use the returned `{code, value}` pairs as input to [Update Notification Settings](https://api-docs.fansmetric.com/api-reference/notifications/update-settings). **Endpoint:** `GET /v1/{account_id}/notifications/settings/message` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_notifications_read_settings` Reads per-event notification toggles for the Messages group. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `group` | query | no | | OF notification group. Default `1` (the standard Messages group used by every account). | ## Notes Upstream OnlyFans endpoint: `GET /api2/v2/notifications/settings/message?group=…`. ## Response fields | Field | Type | Description | | --- | --- | --- | | `data[]` | array | Notification sections. Each section has `code`, `name`, and an `items[]` array of `{code, name, value}` toggles. | | `data[].items[].code` | string | Toggle code — pass to [Update Notification Settings](https://api-docs.fansmetric.com/api-reference/notifications/update-settings) to flip it. | | `data[].items[].value` | boolean | Current state — `true` if the notification is enabled. | ## Example response (200) ```json { "data": [ { "code": "messages", "name": "Messages", "items": [ { "code": "new_message", "name": "New message", "value": true }, { "code": "tip_received", "name": "Tip received", "value": true }, { "code": "ppv_unlocked", "name": "Paid message unlocked", "value": false } ] } ], "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # Update Notification Settings Section: API Reference › Notifications. Page: https://api-docs.fansmetric.com/api-reference/notifications/update-settings Toggles one or more in-site notification preferences. The body mirrors OnlyFans's shape — pass any subset of toggles and only those are updated. **Endpoint:** `PATCH /v1/{account_id}/notifications/settings` **Base URL:** `https://public-api.fansmetric.com` **Permission:** `api_notifications_update_settings` Flips per-event notification toggles. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `account_id` | path | yes | | OnlyFans numeric account ID. | | `notifications` | body | yes | | Container keyed by notification channel (e.g. `message`). Each channel maps to an array of `{ code, value }` toggle updates. | ## Request body example ```json { "notifications": { "message": [ { "code": "new_message", "value": true }, { "code": "tip_received", "value": true } ] } } ``` ## Notes Upstream OnlyFans endpoint: `PATCH /api2/v2/notifications/settings`. Get the current toggle codes via [Get Notification Message Settings](https://api-docs.fansmetric.com/api-reference/notifications/get-message-settings) before flipping — sending an unknown `code` returns `400` from OnlyFans. Only the toggles you include in the body are touched; others are left alone. ## Example response (200) ```json { "data": { "success": true }, "_meta": { "_credits": { "used": 1 }, "_rate_limits": { "limit_minute": 1000, "remaining_minute": 999, "limit_day": 50000, "remaining_day": 49999 } } } ``` --- # November 16, 2026 Section: Release Notes › Release. Page: https://api-docs.fansmetric.com/release-notes/2026-11-16 **Send new photos and videos** in messages, with a step-by-step [Uploading Media](https://api-docs.fansmetric.com/uploading-media) guide. **Scheduled posts now wait** for their time. And these docs can now be read by AI assistants. > Uploading now uses one permission, **Upload Media**, in place of three. Roles that had Create Signed Media Upload have been given it. If an upload step answers `403`, ask an admin to tick **Upload Media** on your key's role under `Public API → Roles`. ## Send new photos and videos Every step of sending a new photo or video, in a message or a mass message, now goes through the API, except sending the file itself, which goes straight to the upload address you're given. The new [Uploading Media](https://api-docs.fansmetric.com/uploading-media) guide walks through them all, from checking whether the vault already has the file to tagging the creators in it. Each step below links to its own page. - **Check the vault first.** [Lookup Vault Media by Hash](https://api-docs.fansmetric.com/api-reference/vault/lookup-hash) tells you whether the vault already has the file, so you never upload it twice. - **Upload it.** [Create Signed Upload](https://api-docs.fansmetric.com/api-reference/media-upload/create-signed-upload) now needs just the file's name, size and type. Files over 5 MB go up in pieces, which [Finish Multipart Upload](https://api-docs.fansmetric.com/api-reference/media-upload/finish-multipart-upload) joins. - **Get it ready.** New: [Convert Upload](https://api-docs.fansmetric.com/api-reference/media-upload/convert-upload) makes the file ready to send, with the account's upload settings and watermark applied. - **Send it.** Put the file in `mediaFiles` of [Send Message](https://api-docs.fansmetric.com/api-reference/messages/send-message) or [Send Mass Message](https://api-docs.fansmetric.com/api-reference/mass-messages/send). New files and vault files can go in the same message. - **Keep it in the vault.** A new file reaches the vault only once it's sent. To store files without leaving them in a chat, send them in a free message, then [unsend](https://api-docs.fansmetric.com/api-reference/messages/delete-message) it. The guide shows how. - **Tag creators.** New: [Attach Tags To Vault Media](https://api-docs.fansmetric.com/api-reference/vault/attach-tags) tags the creators, guests and partners who appear in a vault file. - **Uploads that stopped working in October.** OnlyFans changed how uploads work in October. If yours started failing, follow the steps in the guide: get each file ready with [Convert Upload](https://api-docs.fansmetric.com/api-reference/media-upload/convert-upload), using the `key` and `uploadToken` from Create Signed Upload. ## One permission for uploading Every upload step now needs one permission: **Upload Media**, in the Media group under `Public API → Roles` in the FansMetric app. It covers checking the vault, uploading, joining pieces, getting the file ready and tagging creators. - It replaces three old permissions: Lookup Media by Hash, Create Signed Media Upload and Finish Signed Media Upload. Those are gone from the role form. - Roles that had Create Signed Media Upload have been given **Upload Media**, so most keys need no change. - A role that had only Lookup Media by Hash has no upload permission now, and gets `403` on every upload step. An organization admin fixes it by ticking **Upload Media** on that role. - Every upload page names the permission it needs, as `api_media_upload`. ## Scheduled posts wait for their time A post meant for later could go out straight away. Now it waits for its time. Send `scheduledDate` to [Create Post](https://api-docs.fansmetric.com/api-reference/posts/create-post): the time in UTC, such as `2026-11-20T15:00:00.000Z`. `scheduledTime`, the name that page used to give, now works too, so if you used it, nothing needs changing. - `scheduledDate` is all you need to send. Nothing else has to be set to schedule a post. - **Save for later.** To put a post in OnlyFans' Saved for later queue instead, send `isScheduled: 1` and `isPublishedWithPeriod: 1`, with no `scheduledDate`. - **Check it's queued.** The answer's `postedAt` is the time you chose. To be sure the post is waiting and not live, find it in [List Later Scheduled Posts](https://api-docs.fansmetric.com/api-reference/schedules/list-later-posts). ## Use these docs with an AI assistant These docs now come in a plain-text form that AI assistants and coding tools read well. Give your assistant one of these links, then ask it about the API or have it help write a request. - [llms.txt](https://api-docs.fansmetric.com/llms.txt): a short map of every page, with a link to each. - [llms-full.txt](https://api-docs.fansmetric.com/llms-full.txt): every page in one file. - One page on its own: put `/md` before its address and `.md` after, such as [/md/uploading-media.md](https://api-docs.fansmetric.com/md/uploading-media.md). - Search engines and AI tools can now find every page of these docs. ## Docs improvements These change the pages only. - **Endpoint notes are back.** Each endpoint's notes, such as its limits, defaults and what to watch for, had been hidden. They now show under **Behavior** on every endpoint page that has them. - **Easier to read.** The text under each page title stands out more, and the endpoint notes match its size. - [Send Mass Message](https://api-docs.fansmetric.com/api-reference/mass-messages/send) now gives each field's default, so you can see what happens when you leave one out. It no longer says guests and partners can't be tagged: they always could, with `rfGuest` and `rfPartner`. - [Send Message](https://api-docs.fansmetric.com/api-reference/messages/send-message) and [Create Post](https://api-docs.fansmetric.com/api-reference/posts/create-post) no longer list fields you never need to send. - Broken links fixed on [Get Chat Message](https://api-docs.fansmetric.com/api-reference/messages/get-chat-message), [Bulk Add Users To List](https://api-docs.fansmetric.com/api-reference/user-lists/bulk-add-users) and [Clear User List](https://api-docs.fansmetric.com/api-reference/user-lists/clear-user-list). --- # September 22, 2026 Section: Release Notes › Release. Page: https://api-docs.fansmetric.com/release-notes/2026-09-22 **Twelve new endpoints** opening up the fan surface: the filterable spender list, per-fan lifetime stats, a filterable transaction feed with a companion counts endpoint, and the Fan Info sidebar records — custom name, metadata, note, claimed links and chat summary. All FansMetric-backed and badged **FM**. Separately, **every photo and video link now expires after two hours**, with [Get Vault Media](https://api-docs.fansmetric.com/api-reference/vault/get-vault-media) added so you can ask for a fresh one. > The fan endpoints are entirely additive. The media change is not: photo and video links are FansMetric addresses now, and they expire two hours after you receive them. If you save media links anywhere, save the media `id` instead — start with [Media URLs](https://api-docs.fansmetric.com/media-urls). ## Photo and video links now expire OnlyFans does not let anyone else open its photo and video addresses, so one copied out of a response never worked for you anyway. We now swap those addresses out before you see them. What arrives instead is a FansMetric link that fetches the file for you — an ordinary web address you can open or show on a page, with no API key needed. The trade is that a link which opens without a password cannot live long, so each one expires two hours after it is created. That makes a link not worth saving: save the item's `id` and ask for the file again when you next need to show it. The full rules live on [Media URLs](https://api-docs.fansmetric.com/media-urls). - **Which files.** Swapped: photos, videos, GIFs and audio from posts, the vault, chats, stories and mass messages. Untouched: profile pictures and cover photos, Giphy results, and the upload addresses you get back when uploading. - **Getting a fresh link.** [Get Vault Media](https://api-docs.fansmetric.com/api-reference/vault/get-vault-media) returns one vault item with new links, so you can refresh a single file instead of paging the whole vault. Add `refresh=1` for a brand-new two-hour window. It uses the same permission as List Vault Media, so nothing needs granting. For anything outside the vault, ask the same endpoint for it again. - **If a link fails**, ask for the item again — that fixes all four cases. `403` expired or altered, `404` the account was disconnected or removed, `429` that account loaded too many files this minute, `502` OnlyFans refused. - **Limits.** Each connected account can load up to 300 files a minute. Videos play and skip around normally, and showing the same file again within the hour is free. Do not edit a link — changing a single character breaks it. - **Treat a link like the file.** Anyone holding one can see that media until it expires, so do not post them anywhere public. ## What this opens up Until now every `/fans` route relayed OnlyFans. None of the fan data FansMetric computes — lifetime spend aggregates, the per-account breakdown, the transaction history, or anything in the Fan Info sidebar — was reachable through the API. These twelve endpoints close that gap. Because they read our own database rather than proxying, they keep answering when a connection's OnlyFans session has lapsed. That makes them the reliable half of the fan surface: the relays can fail on an expired session, these cannot. ## New endpoints Twelve, in two groups split by what the data actually is. - **The spender list.** [List Fans](https://api-docs.fansmetric.com/api-reference/fans/list-fans) is the filterable fan table — lifetime spend, purchase count, average purchase, average weekly spend, days active and last purchase — with four `{min, max}` range filters, a `last_purchase_within_days` window, and an allowlisted sort. Filtering happens in the database, so narrowing to "spent over $100 and bought this month" does not mean paging the whole set. - **Per-fan analytics.** [Get Fan Stats](https://api-docs.fansmetric.com/api-reference/fans/get-fan-stats) breaks lifetime spend down per account — the detail the list deliberately sums away — returning a row for every account you name, so one they never bought from comes back at zero rather than missing. [Get Fan Transactions](https://api-docs.fansmetric.com/api-reference/fans/get-fan-transactions) pages their transactions newest-first, each row carrying `amount`, `fee`, `vat_amount`, `net` and `currency`, with optional `categories`, `statuses` and `from`/`to` filters; [Get Fan Transaction Counts](https://api-docs.fansmetric.com/api-reference/fans/get-fan-transaction-counts) takes the identical body and returns counts instead of rows. - **Fan Info sidebar records.** Your organisation's private annotations, each keyed to one account: custom [name](https://api-docs.fansmetric.com/api-reference/fans/get-fm-name) ([write](https://api-docs.fansmetric.com/api-reference/fans/update-fm-name)), [metadata](https://api-docs.fansmetric.com/api-reference/fans/get-fm-metadata) ([write](https://api-docs.fansmetric.com/api-reference/fans/update-fm-metadata)) for timezone / birthday / city, [note](https://api-docs.fansmetric.com/api-reference/fans/get-fm-note) ([write](https://api-docs.fansmetric.com/api-reference/fans/update-fm-note)), the [links the fan claimed](https://api-docs.fansmetric.com/api-reference/fans/get-fm-links), and the [AI chat summary](https://api-docs.fansmetric.com/api-reference/fans/get-fm-chat-summary). - New permissions: `api_fans_list`, `api_fans_read_stats`, `api_fans_read_transactions`, and `api_fm_fans_{read,update}_name`, `api_fm_fans_{read,update}_metadata`, `api_fm_fans_{read,update}_note`, `api_fm_fans_read_links`, `api_fm_fans_read_chat_summary`. A role missing one gets 403, so grant them before switching traffic across. ## The note and name collision — read this one FansMetric keeps its own note and its own display name for a fan, and OnlyFans keeps its own of each. All four are now reachable, at URLs a character apart. Editing one does not affect the other. - **Notes.** [`PATCH /v1/{account_id}/fm/fans/{fan_id}/note`](https://api-docs.fansmetric.com/api-reference/fans/update-fm-note) writes FansMetric's note. [`PUT /v1/{account_id}/fans/{user_id}/notes`](https://api-docs.fansmetric.com/api-reference/fans/update-notes) writes OnlyFans' subscriber notice. The differences are the `/fm/` segment and the singular `note`. - **Names.** [`PATCH …/fm/fans/{fan_id}/name`](https://api-docs.fansmetric.com/api-reference/fans/update-fm-name) sets your private label. [`PUT …/fans/{user_id}/display-name`](https://api-docs.fansmetric.com/api-reference/fans/update-display-name) sets the name OnlyFans shows. [Get Fan Details](https://api-docs.fansmetric.com/api-reference/fans/get-fan) relays the OnlyFans one; the `/fm/` route returns yours. Both being populated with different values is normal, not a bug. - If you are migrating from the web app's behaviour: the sidebar's note and name fields are the FansMetric ones, i.e. the `/fm/` paths. ## Filtering the transaction feed All four filters are optional and compose: omit them and the endpoint returns every transaction over all time, chargebacks included. - **AND across fields, OR within one.** `{"categories":["message","tip"],"statuses":["undo"]}` means "refunded message-or-tip purchases". The category vocabulary is `tip`, `message`, `recurring_subscription`, `new_subscription`, `unlock`, `unknown`; statuses are `done`, `undo`, `pending_return`, `loading`. - **Unknown values are a 400, never an empty result.** Sending `"categories":["boost"]` returns an error naming `boost` and listing the six valid values. A typo that silently returned zero rows would be the worst possible failure here, so it cannot happen. An empty array is not a typo and is treated as no filter. - **`from`/`to` accept the same vocabulary as the rest of the API** — `2026-01-01`, `2026-01-01 15:04:05`, RFC 3339, `now`, and relative shorthand like `-30days`. Both bounds are inclusive; either may be omitted. A date bound excludes rows with a null timestamp, which is correct but worth knowing if your totals shift when you add a window. - **Re-send the filters when paging.** `_pagination.next_page` is a bare offset, so page two needs the same body with a new `offset` — filters included. Dropping them pages a different set. - **Counts follow the filter.** [Get Fan Transaction Counts](https://api-docs.fansmetric.com/api-reference/fans/get-fan-transaction-counts) counts the filtered set, not the whole history: filter to `undo` and `all` equals the chargeback count while every other status reads `0`. Both breakdowns always sum to `all`. ## Quirks worth knowing before you integrate Five places where the obvious assumption is wrong. - **Transaction rows carry both gross and net, and only one reconciles.** `amount` is what the fan paid, and it is the figure [List Fans](https://api-docs.fansmetric.com/api-reference/fans/list-fans) and [Get Fan Stats](https://api-docs.fansmetric.com/api-reference/fans/get-fan-stats) total — so summing it reproduces `total_spend`. `net` is what the creator kept once `fee` and `vat_amount` came out, and summing that will not. All four are nullable: an older imported row can report `net` with no breakdown behind it. - **Every id on the wire is an OnlyFans id.** A transaction's `id` is OnlyFans' own transaction id, and `account_id` on both the feed and the stats is the numeric account id you sent in — not FansMetric's internal UUIDs. Inputs and outputs speak the same vocabulary, so a row can be traced straight back to what you see in OnlyFans. - **The transaction feed includes refunds; nothing else does.** `status: "undo"` rows are filtered out of every aggregate but are rows in [Get Fan Transactions](https://api-docs.fansmetric.com/api-reference/fans/get-fan-transactions), so a fan with a chargeback returns more transaction rows than their `purchases_count`. That is deliberate — a reversal is only legible next to the charge it reverses. Pass `"statuses":["done"]` if you want the aggregate-matching view, or `["undo"]` for chargebacks alone. - **Blank versus unset differs by field.** On the custom name and the note, `""` round-trips as `""`. On metadata's `timezone` and `city` it reads back as `null`, because historic records were seeded with empty strings and "unset" has to mean one thing. Send an explicit `null` when you intend to clear a metadata field. - **`average_weekly_spend` is 0 for fans active a week or less.** Not missing data: projecting a weekly rate from a two-day window produces a number nobody should act on, so it is suppressed rather than extrapolated. ## Scoping Two scopes, and the URL shape tells you which. - `POST /v1/fans…` takes `account_ids` in the body and aggregates **across** them. That is why the account set is an input rather than part of the path: the figures are sums across the accounts you name, not per-account results you merge yourself. Naming an account you do not own returns 404. - `GET /v1/{account_id}/fm/fans/{fan_id}/…` serves records belonging to exactly one account. The same fan carries independent notes, names and metadata under each of your creators, and one creator's records are not reachable through another's `account_id` — including inside the same organisation. - Reads never create. A fan you have never annotated returns nulls and writes nothing; `PATCH` creates the record on first write. ## Docs improvements Two fixes to the reference itself. The API did not change — the site did. - **Code spans inside bold copy render as code.** A phrase written as **`average_weekly_spend` is 0 for fans active a week or less** used to print its backticks literally, on this page and a dozen others going back to the August release. Bold and code were matched as alternatives, so whichever opened first swallowed the rest of the run; bold now parses the text inside it. - **Parameters can declare their wire type.** The **Try it** panel used to guess a type from the parameter name, which landed on `string` for anything unusual — so [List Fans](https://api-docs.fansmetric.com/api-reference/fans/list-fans)' `{min, max}` range filters were posted as raw text instead of JSON and came back `400`. Each one now declares its type and ships a worked example, so Send works straight off the page. --- # September 2, 2026 Section: Release Notes › Release. Page: https://api-docs.fansmetric.com/release-notes/2026-09-02 **Thirteen new endpoints** — metadata updates, FansMetric-attributed claimers and public share links across tracking and trial links, buyer attribution for PPV mass messages — plus a trial lifecycle filter. **This release contains three breaking changes**, the first since dated releases began. > Unusually for us, this release changes responses you may already be reading. Three changes are breaking: the create endpoints return a different shape, `include_hidden` is gone, and the stats payload lost its click fields and gained cumulative ones. Each is listed below with the exact migration. Everything else is additive. ## Breaking changes Three, all on tracking and trial links. Nothing else in the API changed meaning. - **Create responses changed shape.** `POST /tracking-links` and `POST /trial-links` used to return the raw OnlyFans object with `fmTags`, `fmCustomSourceUrl` and (for tracking) `fmTrackingLinkUrl` grafted on. They now return the same canonical item as the matching GET — camelCase, with nested `revenue` / `cost` / `tags` / `links` objects and every metric zeroed, because a link created a moment ago has no claims yet. If you read `fmTags`, read `tags`; if you read `fmCustomSourceUrl`, read `customSourceUrl`; `fmTrackingLinkUrl` is now `campaignUrl`. - **`include_hidden` was removed.** Replaced by `visibility`, which takes `visible` (the default), `hidden` or `all`. The old parameter is no longer parsed, so it is now ignored like any unknown query string — a caller still sending `include_hidden=true` silently gets **visible-only** results rather than an error. Send `visibility=all` to restore the previous behaviour, or `visibility=hidden` for the hidden-only view that was not previously possible. - **Stats dropped clicks and gained cumulatives.** `summary.clicks_total` and the per-bucket `clicks` field are gone from both stats endpoints. There was never per-day click data — for trial links the fields were always `null`, and for tracking links `clicks_total` was a lifetime counter that is still available as `countTransitions` on the list and get endpoints. In their place: `cumulative_subs_total` and `cumulative_revenue_total` in the summary, and `cumulative_subs` / `cumulative_revenue` on every bucket. ## How the new cumulative fields window Worth reading once before you plot them, because the date window is applied three different ways in the same response — deliberately. - `subs_total`, `revenue_total` and `spenders_total` respect `date_start` / `date_end` exactly, unchanged from before. - `cumulative_subs_total` and `cumulative_revenue_total` run from the link's inception to `date_end` and **ignore `date_start`** — a running total restarted at the window edge would not be a cumulative. - Buckets are sliced on whole boundaries, so a `date_start` in the middle of a day returns that entire day's value rather than a partial one. A consequence: the first bucket you get back can show a `cumulative_revenue` larger than its own `revenue`, because it carries pre-window activity forward. - Buckets are UTC and sparse — only buckets with activity are emitted, with no zero-filling. The web app buckets in the viewer's timezone and zero-fills, so comparing the two across a timezone boundary can look like a one-day shift. - On an unwindowed call, `subs_total == cumulative_subs_total` and the last daily bucket's `cumulative_revenue` equals `cumulative_revenue_total`. Handy as a self-check. ## New endpoints Thirteen. Twelve are on tracking and trial links — six per type, all FansMetric-backed and badged **FM** — plus one live OnlyFans relay on mass messages. - **Metadata updates.** [Update Tracking Link](https://api-docs.fansmetric.com/api-reference/tracking-links/update) and [Update Trial Link](https://api-docs.fansmetric.com/api-reference/trial-links/update) partially update the five FansMetric-side fields — `custom_name`, `note`, `custom_source_url`, `promo_cost` and `is_hidden` — without touching OnlyFans. Merge-patch: an absent key is left alone, an explicit `null` clears the column, a value is validated and set. `is_hidden` is the one field that cannot be `null`. - **FansMetric-attributed claimers.** [Tracking](https://api-docs.fansmetric.com/api-reference/tracking-links/list-claimers-fm) and [trial](https://api-docs.fansmetric.com/api-reference/trial-links/list-claimers-fm) — the data behind the web app's Claims modal. - **Public share links.** List, create, update and delete for [tracking links](https://api-docs.fansmetric.com/api-reference/tracking-links/list-shares) and [trial links](https://api-docs.fansmetric.com/api-reference/trial-links/list-shares). The share's UUID is the public token, and the response hands you the ready-to-send URL — do not assemble it yourself, because the origin differs per deployment. Delete is a hard delete: the page 404s immediately and the token cannot be revived. - **Mass-message buyer attribution.** [List Mass Message Buyers](https://api-docs.fansmetric.com/api-reference/mass-messages/buyers) returns the fans who purchased a specific PPV mass message — the drill-down behind a queue row. [Mass Message Statistics](https://api-docs.fansmetric.com/api-reference/mass-messages/list-mass-messages) reports `sentCount` and `viewedCount` but carries no purchaser attribution; this is where it lives. Only meaningful for paid sends — a free message returns an empty list. Rows are ID-only stubs, so hydrate with [Get Fan Details](https://api-docs.fansmetric.com/api-reference/fans/get-fan); pagination is offset-based with a marker snapshot pin, the same scheme as [List Payout Requests](https://api-docs.fansmetric.com/api-reference/payouts/list-requests). - New permissions accompany these: `api_{tracking,trial}_links_update`, `api_{tracking,trial}_links_{list_shares,create_share,update_share,delete_share}`, and `api_mass_messages_list_buyers` for the buyers endpoint. The claimers endpoints reuse the existing `api_tracking_links_list_claimers` and `api_trial_links_list_subscribers`. A role missing a permission returns 403, so grant them before switching traffic over. ## Smaller additions Additive; nothing to migrate. - **`visibility` on both FansMetric lists.** `visible` (default), `hidden` or `all`. The `hidden` value is new capability — previously there was no way to ask for only hidden links. - **`status` on the trial list.** `all` (the default, so existing calls are unaffected), `active` or `finished`. This is the trial analogue of tracking links' `with_deleted`: OnlyFans finishes trials rather than deleting them, so `isFinished` — not a date — is the lifecycle signal. `visibility` and `status` combine freely. - Sorting the FansMetric lists by claim count without a date window is now materially faster on large accounts. No API change; the same request just returns sooner. ## Docs corrections Two claims on [Earnings Overview](https://api-docs.fansmetric.com/api-reference/earnings/overview) were corrected against captured traffic. The API did not change — the page did. - `by` takes `messages`, not `massMessages` — that is the **response** key, not the input value. The page now notes where the `by` vocabulary and the response keys diverge. - `chartData` bucket granularity is window-dependent, not fixed monthly — a 90-day window returns daily buckets. Read each point's `date` rather than assuming a period. --- # August 17, 2026 Section: Release Notes › Release. Page: https://api-docs.fansmetric.com/release-notes/2026-08-17 **32 new endpoints** across posts, post labels, bookmarks, chat and chatter analytics, and tracking and trial links. Nothing you already call was removed, and no existing response field changed meaning. > Releases are dated rather than numbered — there is no `v2` to migrate to, and nothing to pin a request to. They reach every organization at the same time and are additive by default: we add endpoints and fields rather than change the ones you already read. Read responses loosely, because new fields turn up without a release of their own, and a parser that rejects unknown keys will fail on a change meant to be invisible. ## What's new The largest release since the API opened up. In practice it unlocks three things: a posts surface complete enough to browse and act on, messaging analytics per account and per chatter, and revenue, cost and tags attached to individual tracking and trial links instead of stitched together on your side. - **Posts** — 10 endpoints. Browse the creator's feed, open a single post, read its stats and comments, and like, pin, archive or bookmark it. - **Post Labels** — 5 endpoints. Read the creator's own labels and move posts in and out of them. - **Bookmarks** — 2 endpoints. Read the Saved for later collection and the categories it is filed under. - **Chat** — 2 endpoints. Per-account messaging KPIs, as a headline card and as a chart. - **Chatters** — 3 endpoints. Organization-wide chatter performance: a ranked list, a side-by-side comparison, and a totals table. - **Tracking and trial links** — 10 endpoints. Per-link stats, per-link tags, and a FansMetric-backed list carrying revenue, cost and tags. ## Posts, labels and bookmarks Enough to build a posts tab end to end. [List Posts](https://api-docs.fansmetric.com/api-reference/posts/list-posts) returns the creator's own feed with filters for media type, label, caption text and pinned state; [Get Post](https://api-docs.fansmetric.com/api-reference/posts/get-post) opens a single one; [Get Post Statistics](https://api-docs.fansmetric.com/api-reference/posts/get-post-statistics) and [List Post Comments](https://api-docs.fansmetric.com/api-reference/posts/list-post-comments) fill in a detail panel. The action endpoints write back to OnlyFans — [Like Post](https://api-docs.fansmetric.com/api-reference/posts/like-post), [Pin Post](https://api-docs.fansmetric.com/api-reference/posts/pin-post), [Archive Post](https://api-docs.fansmetric.com/api-reference/posts/archive-post), [Unarchive Post](https://api-docs.fansmetric.com/api-reference/posts/unarchive-post), [Bookmark Post](https://api-docs.fansmetric.com/api-reference/posts/bookmark-post) and [Remove Post Bookmark](https://api-docs.fansmetric.com/api-reference/posts/remove-post-bookmark). Labels are what OnlyFans calls collections: named buckets a creator drops posts into, which double as filter chips on their public profile. [List Post Labels](https://api-docs.fansmetric.com/api-reference/post-labels/list-post-labels) returns them with preview thumbnails, [List Post Label Filters](https://api-docs.fansmetric.com/api-reference/post-labels/list-post-label-filters) returns the same set shaped for a filter bar, and [Get Post Label](https://api-docs.fansmetric.com/api-reference/post-labels/get-post-label), [Add Posts to Label](https://api-docs.fansmetric.com/api-reference/post-labels/add-posts-to-label) and [Remove Post from Label](https://api-docs.fansmetric.com/api-reference/post-labels/remove-post-from-label) cover the rest. [List Bookmarks](https://api-docs.fansmetric.com/api-reference/bookmarks/list-bookmarks) returns the Saved for later collection and [List Bookmark Categories](https://api-docs.fansmetric.com/api-reference/bookmarks/list-bookmark-categories) returns the buckets it is filed under. - Like and Pin are toggles. OnlyFans has no separate unlike or unpin for posts, so a second call reverses the first — drive your button state from what the response says, not from what you assume the call did. - The post feed pages by cursor, not by page number. Follow `_pagination.next_page` instead of building a numbered pager. - A label `id` is a number for the creator's own labels and a word for the two archive buckets, so check its type before treating it as a number. - Bookmarks mix saved posts and saved chat messages in one feed. Branch on `responseType` before rendering a row, or narrow to one kind with `entity_type`. ## Chat and chatter analytics [Chat Overview](https://api-docs.fansmetric.com/api-reference/chat/overview) returns an 11-stat headline for one connected account over a date window, each stat carrying the previous window's value and the percent change — so a comparison tile costs one call rather than two. [Chat Chart](https://api-docs.fansmetric.com/api-reference/chat/chart) returns the same measures bucketed over time for a trend line. The chatter endpoints work organization-wide. [List Chatters](https://api-docs.fansmetric.com/api-reference/chatters/list) is the ranked list you would populate a selector from, [Compare Chatters](https://api-docs.fansmetric.com/api-reference/chatters/compare) puts up to five of them side by side across the same 11 stats, and [Chatter Report](https://api-docs.fansmetric.com/api-reference/chatters/report) returns that data as a table with a totals row. - The 11 stats always come back in the same order, so a dashboard tile bound to a position stays put. - Compare puts every chatter on the same bucket axis, so their series overlay without you padding them first. - The totals row on Chatter Report spans every chatter matching your filter, not just the page you are looking at — don't rebuild it by summing pages. ## Tracking and trial links Both resources are now served two ways, and the URL picks which. The bare path relays OnlyFans live; the same path under `/fm/` serves the FansMetric database with revenue, cost and tags attached. The pair sits together in the sidebar, badged **OF** for the live relay and **FM** for the FansMetric view. [Get Tracking Link Stats](https://api-docs.fansmetric.com/api-reference/tracking-links/get-stats) and [Get Trial Link Stats](https://api-docs.fansmetric.com/api-reference/trial-links/get-stats) return cumulative totals plus daily and monthly series for a single link — enough for a per-link detail page without pulling the whole list first. Six endpoints manage tags on an individual link: list, add and remove for [tracking links](https://api-docs.fansmetric.com/api-reference/tags/list-tracking-link) and the same three for [trial links](https://api-docs.fansmetric.com/api-reference/tags/list-trial-link). Tags are addressed by name, and adding preserves the ones already there. - The FansMetric lists — [tracking](https://api-docs.fansmetric.com/api-reference/tracking-links/list-fm), [trial](https://api-docs.fansmetric.com/api-reference/trial-links/list-fm) — carry `revenue`, `cost` and `tags`, plus `search`, `tag_ids` and hidden-link filters the live relay does not have. - Freshness is the trade. The relay is live; the FansMetric view is refreshed by our scraper, roughly every 30 minutes for tracking links and every 2 hours for trial links. - `limit` on both link lists is capped at 25. - [Get Earnings Chart](https://api-docs.fansmetric.com/api-reference/earnings/chart) gained five more `by` values — `tips_profile`, `tips_post`, `tips_chat`, `tips_stream` and `tips_story` — so tips can be split by where they came from. ## Renamed in the docs Naming only. Every path and permission stayed exactly where it was, and no request you send today behaves differently. - The `Campaigns` section folded into `Tracking Links`. `GET /v1/{account_id}/campaigns` still answers as before and is documented as an alias on [List Tracking Links](https://api-docs.fansmetric.com/api-reference/tracking-links/list). - `Get Campaigns Chart` and `Get Campaigns Overview` are now [Get Tracking Links Chart](https://api-docs.fansmetric.com/api-reference/tracking-links/get-chart) and [Get Tracking Links Overview](https://api-docs.fansmetric.com/api-reference/tracking-links/get-overview). Their paths still read `/campaigns/...` because that is what the API serves; the retired documentation URLs redirect. ## Docs improvements The reference passed 160 endpoints in this release, so most of the work went into finding things inside it. - A filter box under **API Reference** in the sidebar. Type part of a title or a path and the tree collapses to matches, each carrying its method and its section — titles repeat across sections, so both matter. - Search no longer matches the HTTP method. Typing `get` used to return every GET endpoint in the reference; it now returns the routes actually named `Get …`. - Cross-references and emphasis in the copy render as links and bold text instead of printing raw markdown. - **Try it** now sends a request body on `DELETE` endpoints. Five of them take one — per-link tag removal for tracking and trial links, unlike message, delete media, and remove media from list — and Send used to come back `400` on all five even though the sample beside it was correct. - Every navigation group and section has an icon, and the sidebar scrolls the active route into view when you land on a deep link. ## Before you call the new endpoints Each new endpoint ships with its own per-route permission, and keys you already issued do not pick those up on their own. - An organization admin needs to add the new permissions to the role your key uses, under `Public API → Roles` in the FansMetric app. Until that happens the new endpoints answer `403` even though the key itself is valid. - Every reference page names the permission slug it needs, so you can check a role against the pages you plan to call. - Nothing else is required. No field changed meaning and no endpoint was removed, so anything already in production keeps working untouched. - This page is the summary of what moved. The endpoint pages stay the source of truth for parameters, payloads and permissions.