Follow us on Bluesky

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 to bluefacts.app on 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

GET /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-followers

Most Followed

Users ranked by total follower count

top-followers-1d

Trending (24h)

Users with the most new followers in the last 24 hours

top-growth-1d

Fastest Growing (24h)

Users with the highest follower growth rate in the last 24 hours

top-reach

Most Reach

Users with the highest engagement and reach metrics

top-new

Top 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"
  ]
}