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

https://public-api.fansmetric.com

GET/v1/{account_id}/stories/{story_id}/viewers

API keyBearer

Authorization

default

AuthorizationBearer <token>

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

In: header

Path Parameters

account_id*integer
OnlyFans numeric account ID.
story_id*integer
Story ID (from engagement/stories/{by} or highlights/story).

Query Parameters

limitinteger
Page size. Default 10. Min 1, max 100.
offsetinteger
Rows to skip.
only_with_tipsstring
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.

Response Fields

data.list[]array
Viewer rows.
data.list[].idinteger
Viewer user ID.
data.list[].usernamestring
Viewer username.
data.list[].namestring
Display name.
data.list[].viewstring
"s" — viewer-scoped projection.
data.list[].isStoryLikedboolean
Whether this viewer liked the story.
data.list[].isStoryBlockedUserboolean
Whether the creator has blocked this user from viewing stories.
data.list[].hasStoryTipsboolean
Whether this viewer tipped on the story.
data.list[].hasTopStoryTipsboolean
Whether this viewer is among the top tippers on the story.
data.list[].subscribedByboolean
Whether the calling account subscribes to this viewer.
data.list[].subscribedOnboolean
Whether the viewer subscribes to the calling account.
data.list[].lastSeenstring|null
Last-seen timestamp on the platform (not story-specific).
data.hasMoreboolean
Whether more pages are available.
dataobject | array
Endpoint-specific payload. See the fields below for this route.
_pagination.next_pagestring
Relative URL for the next page, with the cursor or offset already applied. Append it to the API base URL and send it as-is. Omitted entirely on the last page.
_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.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.
data	object \| array	Endpoint-specific payload. See the fields below for this route.
_pagination.next_page	string	Relative URL for the next page, with the cursor or offset already applied. Append it to the API base URL and send it as-is. Omitted entirely on the last page.
_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 GET "https://public-api.fansmetric.com/v1/100000001/stories/sample_story_id/viewers?limit=20&offset=0&only_with_tips=sample_only_with_tips" \
  --header "Authorization: Bearer YOUR_API_KEY"

Response

200

{"data":{"hasMore":true
"list":[0:{"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
}
}
}

List Top Stories by Engagement

Get Profile Visitors Overview