curl --request GET \
--url https://api.fanvue.com/v1/insights/fans/{userUuid} \
--header 'Authorization: Bearer <token>' \
--header 'X-Fanvue-API-Version: <x-fanvue-api-version>'import requests
url = "https://api.fanvue.com/v1/insights/fans/{userUuid}"
headers = {
"X-Fanvue-API-Version": "<x-fanvue-api-version>",
"Authorization": "Bearer <token>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {
'X-Fanvue-API-Version': '<x-fanvue-api-version>',
Authorization: 'Bearer <token>'
}
};
fetch('https://api.fanvue.com/v1/insights/fans/{userUuid}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"status": "subscriber",
"spending": {
"lastPurchaseAt": "2024-01-14T00:00:00.000Z",
"lastValidPurchaseAt": "2024-01-14T00:00:00.000Z",
"total": {
"gross": 25700,
"total": 25700,
"netTotal": 25700
},
"maxSinglePayment": {
"gross": 5000,
"total": 5000
},
"sources": {
"message": {
"gross": 15000,
"total": 15000,
"netTotal": 13000,
"count": 6,
"netCount": 5,
"average": 2500,
"netAverage": 2600
},
"post": {
"gross": 8500,
"total": 8500,
"netTotal": 8500,
"count": 5,
"netCount": 5,
"average": 1700,
"netAverage": 1700
},
"referral": {
"gross": 4200,
"total": 4200,
"netTotal": 4200,
"count": 2,
"netCount": 2,
"average": 2100,
"netAverage": 2100
}
}
},
"subscription": {
"createdAt": "2024-01-01T12:00:00.000Z",
"renewsAt": "2024-02-01T00:00:00.000Z",
"autoRenewalEnabled": true
}
}{
"error": "<string>",
"message": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"message": "<string>"
}{
"error": "<string>",
"message": "<string>",
"nextVersion": "<string>"
}{
"error": "<string>"
}Get fan insights
Returns detailed insights about a specific fan for the authenticated creator, including spending statistics, subscription status, and fan engagement metrics.
Each money field comes as a gross value and a net one, net meaning refunded and charged-back purchases removed: total and netTotal, count and netCount, average and netAverage. spending.total.total has always been net of reversals, so the gross per-source figures can add up to more than it and the gap is exactly the reversals, which are not returned as a source of their own; the per-source netTotal values add up to spending.total.netTotal. spending.maxSinglePayment drops reversed purchases entirely, which is why it carries no net variant.
A reversal is normally a separate invoice for the full original amount: there are no partial refunds, and the original payment is never rewritten, so the original still appears on /insights/earnings. Pair the two through reversedTransactionOrderId on the refund/chargeback rows of that endpoint. A payment marked refunded or charged back without a linked reversal invoice is the exception: there is no negative row for spending.total.total to subtract so it does not come down, while every net figure drops the purchase. That is why the net total is aggregated over the surviving purchases rather than derived from the gross one.
Every figure here is computed on each request with no caching — the spending fields from live invoice data, status and the subscription block from the subscription, follow and payment-method records — so two reads seconds apart can legitimately differ.
curl --request GET \
--url https://api.fanvue.com/v1/insights/fans/{userUuid} \
--header 'Authorization: Bearer <token>' \
--header 'X-Fanvue-API-Version: <x-fanvue-api-version>'import requests
url = "https://api.fanvue.com/v1/insights/fans/{userUuid}"
headers = {
"X-Fanvue-API-Version": "<x-fanvue-api-version>",
"Authorization": "Bearer <token>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {
'X-Fanvue-API-Version': '<x-fanvue-api-version>',
Authorization: 'Bearer <token>'
}
};
fetch('https://api.fanvue.com/v1/insights/fans/{userUuid}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"status": "subscriber",
"spending": {
"lastPurchaseAt": "2024-01-14T00:00:00.000Z",
"lastValidPurchaseAt": "2024-01-14T00:00:00.000Z",
"total": {
"gross": 25700,
"total": 25700,
"netTotal": 25700
},
"maxSinglePayment": {
"gross": 5000,
"total": 5000
},
"sources": {
"message": {
"gross": 15000,
"total": 15000,
"netTotal": 13000,
"count": 6,
"netCount": 5,
"average": 2500,
"netAverage": 2600
},
"post": {
"gross": 8500,
"total": 8500,
"netTotal": 8500,
"count": 5,
"netCount": 5,
"average": 1700,
"netAverage": 1700
},
"referral": {
"gross": 4200,
"total": 4200,
"netTotal": 4200,
"count": 2,
"netCount": 2,
"average": 2100,
"netAverage": 2100
}
}
},
"subscription": {
"createdAt": "2024-01-01T12:00:00.000Z",
"renewsAt": "2024-02-01T00:00:00.000Z",
"autoRenewalEnabled": true
}
}{
"error": "<string>",
"message": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"message": "<string>"
}{
"error": "<string>",
"message": "<string>",
"nextVersion": "<string>"
}{
"error": "<string>"
}read:insights— Access analytics, metrics, and insights data for performance tracking.read:fan— Access fan-related data and information within the platform.
Authorizations
OAuth 2.0 access token, presented as a JWT bearer token in the Authorization header. Obtain a token via the authorization-code flow; the scopes granted to the token determine which operations it may call.
Headers
API version to use for the request
"2025-06-26"
Path Parameters
Fan's UUID
Response
Fan insights data
Current fan status. subscriber has a current subscription, expired had one that ended, follower follows without subscribing, and not_contactable is none of those but has paid this creator before or has a conversation in their inbox (for example a fan who tipped and then unfollowed). A fan with no subscription, no follow, no purchase and no conversation with this creator is not connected, so the single-fan endpoints return 404, GET /insights/fans returns a null result plus a NOT_FOUND entry in errors, and POST /insights/fans/batch maps the fan to { "error": "not_found" }.
subscriber, expired, follower, not_contactable Show child attributes
Show child attributes
Show child attributes
Show child attributes
Was this page helpful?