Synced and live reads
Reads come from synced data by default. Use fresh=true on the three routes that support it when the answer must be current.
BetterFans Link keeps a synced copy of each linked account. Reads come from that synced data by default. They are fast, they do not use the creator's OnlyFans session, and they keep working when OnlyFans asks the creator to sign in again.
How old is the data
Every response says where its data came from in meta.
meta.source | Meaning | meta.asOf |
|---|---|---|
synced | Read from the synced copy. | When the data was last synced from OnlyFans, or null for data that is not synced from OnlyFans, such as actions and links. |
live | Read straight from OnlyFans for this request. | null |
sandbox | Test mode data from the sandbox creators. | See test mode. |
An account also has lastSyncedAt. Check it, or meta.asOf, before you tell someone that nothing happened recently.
Reading live with fresh=true
Three routes take fresh=true and read straight from OnlyFans instead of synced data.
| Route | MCP tool | Use it when |
|---|---|---|
| List messages | get_chat | You are about to reply and need the last few messages. |
| Get fan | get_fan | You need the fan's current subscription or profile. |
| Online fans | online_fans | You want to know who is online right now. |
Live reads are slower and each one calls OnlyFans with the creator's session. Use them for the one answer that must be current, not for bulk reads or reports. Other routes ignore fresh.
A live read can fail where a synced read would not.
- If the account's status stops live calls, the read fails with
409account_unavailable. Read withoutfresh=trueto get the synced copy. - If OnlyFans errors or is slow, the read fails with
502onlyfans_errororonlyfans_timeout. Retry after a short wait, or read withoutfresh=true.
Chats stay unread
On OnlyFans, opening a chat marks it read, which would hide a new message from the creator. A live read of a chat's messages keeps the thread's unread state as it was. In the rare case that BetterFans Link cannot restore it, the response says so:
"meta": {
"source": "live",
"asOf": null,
"requestId": "req_7Hq2LmX9pRt4VbN8cKe3WzYa",
"sideEffects": ["thread_marked_read"]
}sideEffects is absent when nothing changed. If you see thread_marked_read, tell the creator that the chat may look read in OnlyFans.
Presence
Online status is a best guess. A fan missing from Online fans is not known to be offline, and a fan's presence of unknown does not mean offline. Do not tell anyone a fan is offline unless presence is offline.
Calling OnlyFans directly
Call OnlyFans always reads live, so its responses have meta.source set to live. Prefer the routes above; use it only for data they do not cover.
A newly linked account
An account in syncing status was linked in the last 30 minutes. Its history is still filling in, so totals and lists can be short. See account status.