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. Requires permission api_fans_list.

https://public-api.fansmetric.com

POST/v1/fans

API keyBearer

Authorization

default

AuthorizationBearer <token>

Send your FansMetric API key as a Bearer token in the Authorization header.

In: header

Request Body

application/json

account_ids*array
Array of OnlyFans numeric account IDs. Aggregates are summed across them, not returned per account. An ID you do not own returns 404.
sort_bystring
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_dirstring
asc or desc (default), case-insensitive. Any other value returns 400.
limitinteger
Default 25, min 1, max 100.
offsetinteger
Default 0.
total_spendobject
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_countobject
Same {min, max} shape, on the number of non-refunded purchases.
average_purchaseobject
Same {min, max} shape, on total_spend ÷ purchases_count.
average_weekly_spendobject
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_daysinteger
A whole number of days, not a range — keep only fans whose most recent purchase falls within this many days. Must be ≥ 1.

Response Fields

data.fans[].idstring | 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[].namestring | null
OnlyFans display name.
data.fans[].usernamestring | null
OnlyFans username.
data.fans[].avatar_urlstring | null
Avatar URL.
data.fans[].total_spendnumber
Gross lifetime spend across the named accounts. Gross, not net — this is what the fan paid, not what the creator received.
data.fans[].average_purchasenumber
total_spend ÷ purchases_count.
data.fans[].average_weekly_spendnumber
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_activenumber
Days between the fan's first and last transaction. 0 for a fan with a single purchase.
data.fans[].purchases_countinteger
Number of non-refunded transactions.
data.fans[].last_purchase_atstring | null
Most recent transaction timestamp (RFC 3339, UTC).
_pagination.next_pagestring | null
The offset to send for the next page. Absent when this is the last page.
dataobject | array
Endpoint-specific payload. See the fields below for this route.
_meta._credits.usedinteger
Credits consumed by this request (currently always 1).
_meta._rate_limits.limit_minuteinteger
Maximum requests per minute for the organization.
_meta._rate_limits.remaining_minuteinteger
Remaining requests in the current minute window.
_meta._rate_limits.limit_dayinteger
Maximum requests per day for the organization.
_meta._rate_limits.remaining_dayinteger
Remaining requests in the current day window.

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.
data	object \| array	Endpoint-specific payload. See the fields below for this route.
_meta._credits.used	integer	Credits consumed by this request (currently always `1`).
_meta._rate_limits.limit_minute	integer	Maximum requests per minute for the organization.
_meta._rate_limits.remaining_minute	integer	Remaining requests in the current minute window.
_meta._rate_limits.limit_day	integer	Maximum requests per day for the organization.
_meta._rate_limits.remaining_day	integer	Remaining requests in the current day window.

curl --request POST "https://public-api.fansmetric.com/v1/fans" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "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
}'

Response

200

{"data":{"fans":[0:{"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
}
}
}

Delete Fan Notes

Get Fan StatsFM