curl --request GET \
--url https://api.onlyx.ai/v1/fans \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.onlyx.ai/v1/fans"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.onlyx.ai/v1/fans', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"data": [
{
"avatarUrl": null,
"conversationId": "cnv_3d9e7b1a5c2f4e8d6a0b",
"createdAt": "2026-03-02T18:21:07.000Z",
"creatorId": "cre_8f2c1a9b0d7e4c3f2a1b",
"customName": "Mike (birthday 14 May)",
"displayName": "Mike",
"id": "fan_6b2e8d4a1c9f3e7b5d0a",
"lastActiveAt": "2026-09-25T21:40:12.000Z",
"lastPurchaseAt": "2026-09-24T22:03:55.000Z",
"lists": [
{
"id": "lst_9c1d2e3f4a5b6c7d8e9f",
"name": "VIP"
}
],
"muted": false,
"notes": "Likes lingerie sets. Tips on Fridays.",
"paidMessagesCents": 36500,
"renewOn": true,
"salesOptOut": false,
"subscribed": true,
"subscribedAt": "2026-03-02T18:21:07.000Z",
"subscriptionExpiresAt": "2026-10-02T18:21:07.000Z",
"subscriptionPriceCents": 999,
"tipsCents": 12000,
"totalSpentCents": 48500,
"username": null
}
],
"hasMore": true,
"nextCursor": "eyJrIjoiY3JlYXRvcnMiLCJwIjp7ImkiOiJjcmVfOGYyYzFhOWIwZDdlNGMzZjJhMWIifX0.Yp3k0Qm7T2vX9aLc4R8sWg"
}List fans
Lists fans across every creator the credential can see, or one creator’s with creatorId. Segments give you ready-made groups: whales ($200 or more spent), spenders, never_spent, new (subscribed in the last 7 days), recent_buyer (bought in the last 30 days), lapsing (auto-renew off, subscription ending within 7 days) and winback (subscription ended in the last 30 days). Combine a segment with status, sort and order — for example lapsing fans by spend — to build call lists for your team. The default order is biggest spenders first. A creatorId the credential cannot see is 404 CREATOR_NOT_FOUND, never an empty list.
Scope: requires fans:read.
Rate limit: the general limit of 120 requests per 60 seconds per credential.
curl --request GET \
--url https://api.onlyx.ai/v1/fans \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.onlyx.ai/v1/fans"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.onlyx.ai/v1/fans', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"data": [
{
"avatarUrl": null,
"conversationId": "cnv_3d9e7b1a5c2f4e8d6a0b",
"createdAt": "2026-03-02T18:21:07.000Z",
"creatorId": "cre_8f2c1a9b0d7e4c3f2a1b",
"customName": "Mike (birthday 14 May)",
"displayName": "Mike",
"id": "fan_6b2e8d4a1c9f3e7b5d0a",
"lastActiveAt": "2026-09-25T21:40:12.000Z",
"lastPurchaseAt": "2026-09-24T22:03:55.000Z",
"lists": [
{
"id": "lst_9c1d2e3f4a5b6c7d8e9f",
"name": "VIP"
}
],
"muted": false,
"notes": "Likes lingerie sets. Tips on Fridays.",
"paidMessagesCents": 36500,
"renewOn": true,
"salesOptOut": false,
"subscribed": true,
"subscribedAt": "2026-03-02T18:21:07.000Z",
"subscriptionExpiresAt": "2026-10-02T18:21:07.000Z",
"subscriptionPriceCents": 999,
"tipsCents": 12000,
"totalSpentCents": 48500,
"username": null
}
],
"hasMore": true,
"nextCursor": "eyJrIjoiY3JlYXRvcnMiLCJwIjp7ImkiOiJjcmVfOGYyYzFhOWIwZDdlNGMzZjJhMWIifX0.Yp3k0Qm7T2vX9aLc4R8sWg"
}Authorizations
An API key (onx_sk_…) created in OnlyX under Settings → API & MCP, or an OAuth access token (onx_at_…) issued to a connected app. Send it as Authorization: Bearer <credential>. API keys may also be sent as X-API-Key: <key>.
Query Parameters
Only this creator's fans.
40Search by name (OnlyFans name or your custom name).
100A ready-made group of fans (see above).
whales, spenders, never_spent, new, recent_buyer, lapsing, winback active (subscribed now) or expired.
active, expired Sort key. Default spend.
spend, subscribed, last_active, last_purchase, name Sort direction. Default desc, except asc for name.
asc, desc Page size, 1-100. Default 25.
1 <= x <= 100Opaque cursor from the previous page's nextCursor. Omit for the first page.
1024