Engagement

List Top Stories by Engagement

Paginated leaderboard of top-performing stories by a single engagement metric. Parallel to List Top Posts — same shape, same pagination, but for stories. Stories aren't purchasable, so by=purchases is not valid here. Requires permission api_engagement_list_stories.

https://public-api.fansmetric.com

GET/v1/{account_id}/engagement/stories/{by}

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.
by*string
Ranking metric. One of tips, views, likes, comments.

Query Parameters

start_datestring
Window start. Default 2 years ago, UTC.
end_datestring
Window end. Default end of today, UTC.
offsetinteger
Rows to skip. Page size is fixed at 10.

Response Fields

data.items[]array
Story objects, ranked by {by} descending.
data.items[].idinteger
OnlyFans story ID.
data.items[].userIdinteger
The creator's user ID (always the queried account).
data.items[].createdAtstring
ISO 8601 publish time.
data.items[].mediaarray
Story media (typically 1 entry). Same media shape as posts.
data.items[].tipsAmountstring
Formatted total tips (e.g. "$200").
data.items[].tipsAmountRawnumber
Numeric total tips.
data.items[].tipsCountinteger
Number of distinct tippers.
data.items[].likesCountinteger
Likes.
data.items[].commentsCountinteger
Comments.
data.items[].viewersCountinteger
Total viewers.
data.items[].viewersarray
Preview of viewer user objects (first 4-5). Use List Story Viewers for the full paginated list.
data.items[].isHighlightCoverboolean
true if this story is the cover of a saved highlight.
data.items[].isLastInHighlightboolean
true if this is the final story in its highlight.
data.hasMoreboolean
Whether more pages are available.
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.items[]	array	Story objects, ranked by `{by}` descending.
data.items[].id	integer	OnlyFans story ID.
data.items[].userId	integer	The creator's user ID (always the queried account).
data.items[].createdAt	string	ISO 8601 publish time.
data.items[].media	array	Story media (typically 1 entry). Same media shape as posts.
data.items[].tipsAmount	string	Formatted total tips (e.g. `"$200"`).
data.items[].tipsAmountRaw	number	Numeric total tips.
data.items[].tipsCount	integer	Number of distinct tippers.
data.items[].likesCount	integer	Likes.
data.items[].commentsCount	integer	Comments.
data.items[].viewersCount	integer	Total viewers.
data.items[].viewers	array	Preview of viewer user objects (first 4-5). Use List Story Viewers for the full paginated list.
data.items[].isHighlightCover	boolean	`true` if this story is the cover of a saved highlight.
data.items[].isLastInHighlight	boolean	`true` if this is the final story in its highlight.
data.hasMore	boolean	Whether more pages are available.
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 GET "https://public-api.fansmetric.com/v1/100000001/engagement/stories/sample_by?start_date=2026-01-01%2000%3A00%3A00&end_date=2026-01-31%2023%3A59%3A59&offset=0" \
  --header "Authorization: Bearer YOUR_API_KEY"

Response

200

{"data":{"hasMore":true
"items":[0:{"id":94660491
"userId":100000001
"createdAt":"2026-05-27T13:00:00+00:00"
"media":[]
"tipsAmount":"$200"
"tipsAmountRaw":200
"tipsCount":8
"likesCount":412
"commentsCount":17
"viewersCount":9821
"viewers":[]
"isHighlightCover":false
"isLastInHighlight":false
}
]
}
"_meta":{"_credits":{"used":1
}
"_rate_limits":{"limit_minute":1000
"remaining_minute":999
"limit_day":50000
"remaining_day":49999
}
}
}

List Top Posts by Engagement

List Story Viewers