API Documentation
Access Bluesky user rankings and statistics programmatically.
Overview
The BlueFacts API provides access to Bluesky user rankings and statistics.
Terms of Use
By using this API, you agree to the following terms:
- Attribution required: You must include a visible backlink tobluefacts.appon any page or application that displays data from this API.
- Contact us: Please let us know what you are building with the API, just send us a message on Bluesky at@bluefacts.app. Also feedback is welcome!
Base URL
The base URL for all endpoints is https://bluefacts.app.
Top Users Lists
/json/lists/{type}Returns a paginated list of users for the specified ranking type.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
type | string | The ranking type (see available types below) |
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
p | integer | 1 | Page number (1-indexed) |
limit | integer | 100 | Results per page (max: 100) |
Available Types
top-followersMost Followed
Users ranked by total follower count
top-followers-1dTrending (24h)
Users with the most new followers in the last 24 hours
top-growth-1dFastest Growing (24h)
Users with the highest follower growth rate in the last 24 hours
top-reachMost Reach
Users with the highest engagement and reach metrics
top-newTop New Users
Newly registered users who have quickly gained followers
Example Request
curl "https://bluefacts.app/json/lists/top-followers-1d?p=1&limit=50"Example Response
{
"type": "top-followers-1d",
"total": 1000,
"page": 1,
"pageSize": 100,
"lastPage": 10,
"users": [
{
"rank": 1,
"did": "did:plc:example123",
"handle": "popular.bsky.social",
"displayName": "Popular User",
"avatar": "https://cdn.bsky.app/img/avatar/...",
"description": "An example user profile",
"followersCount": 150000,
"followsCount": 500,
"postsCount": 2500,
"followerIncrease": 5000,
"followerIncreaseDay": 5000,
"followerIncreaseDayPct": 3.45,
"yesterdayRank": 3,
"rankChange": 2
}
]
}Response Fields
Root Object
| Field | Type | Description |
|---|---|---|
type | string | The requested ranking type |
total | integer | Total number of users in the ranking |
page | integer | Current page number |
pageSize | integer | Number of results per page |
lastPage | integer | Total number of pages |
users | array | Array of user objects |
User Object
| Field | Type | Description |
|---|---|---|
rank | integer | Current position in the ranking |
did | string | Decentralized Identifier (unique user ID) |
handle | string | User's handle (e.g., user.bsky.social) |
displayName | string | null | User's display name |
avatar | string | null | URL to avatar image |
description | string | null | User's bio/description |
followersCount | integer | null | Number of followers |
followsCount | integer | null | Number of accounts followed |
postsCount | integer | null | Number of posts |
followerIncrease | integer | null | Total follower increase (for trending lists) |
followerIncreaseDay | integer | null | Follower increase in the last day |
followerIncreaseDayPct | number | Percentage follower growth |
yesterdayRank | integer | null | Rank position from previous day |
rankChange | integer | null | Change in rank (positive = moved up) |
Caching
Responses are cached for 5 minutes. The rankings are updated daily.
Error Responses
Invalid type parameter returns a 400 error:
{
"error": "Invalid type",
"validTypes": [
"top-followers",
"top-followers-1d",
"top-growth-1d",
"top-reach",
"top-new"
]
}