Bluesky API & Scraper
The Bluesky API returns public social data from the AT Protocol network as clean JSON.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
The primary profile endpoint returns a handle's DID, display name, description, follower, follows and posts counts and avatar, and you can pull an author_feed, search actors, a thread, post_detail, likes and reposts. It is built for social analytics and brand monitoring that need Bluesky data without a scraper. One ReefAPI key, one shared credit pool, the standard envelope.
AT Protocol identifiers: DID, handle, at:// URI, rkey and CID
Bluesky has two names for an account and a URI for everything else, and the difference matters because one of them is permanent and the other is not. Every value below was returned by a live read of the bsky.app account and its pinned post on 2026-08-27.
| Identifier | Measured shape | What it is for |
|---|---|---|
| DID | did:plc:z72i7hdynmk6r22z27h6tvur | The account's permanent id. Store this, not the handle. The actor parameter accepts it, a handle, or a bsky.app/profile/... URL, and all three returned the identical profile |
| handle | bsky.app | A domain name the owner controls. It can be changed or reassigned, so it is a display value, not a key |
| post uri | at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.post/3l6oveex3ii2l | The primary key for thread, likes, reposts, quotes and post_detail |
| rkey | 3l6oveex3ii2l | The last segment of the URI, and also the last segment of the bsky.app share URL, so you can rebuild the URI from a link plus the author DID |
| cid | bafyreicnt42y6vo6pfpvyro234ac4o6ijug6adwwrh7awflgrqlt4zibxq | A content hash of that exact version of the post. Optional on likes, reposts and quotes, where it skips a resolve step |
| cursor | 2026-08-21T18:45:43.613Z | Pagination on author_feed comes back as an ISO timestamp, not an opaque token. Pass it straight back as cursor |
| unknown handle | NOT_FOUND, retryable false | A handle that does not resolve is a hard error with detail.context app.bsky.actor.getProfile, not an empty result |
profile has two modes. One actor returns the profile object at the top level; up to 25 actors returns data.profiles[] with a count and meta.batch true. Note also that a post's author block is thinner than the profile action's output: description and indexed_at come back null inside a post even for accounts that have both.
Real request and response JSON
Captured from the indexed primary action, profile, on .
{
"method": "POST",
"url": "https://api.reefapi.com/bluesky/v1/profile",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"actor": "bsky.app"
}
}{
"ok": true,
"meta": {
"api": "bluesky",
"endpoint": "profile",
"mode": "live",
"latency_ms": 1389,
"record_count": 1,
"bytes": 1054,
"cache_hit": false,
"completeness_pct": 100
},
"data": {
"did": "did:plc:z72i7hdynmk6r22z27h6tvur",
"handle": "bsky.app",
"display_name": "Bluesky",
"description": "official Bluesky account (check username👆)\n\nBugs, feature requests, feedback: [redacted-email]",
"avatar": "https://cdn.bsky.app/img/avatar/plain/did:plc:z72i7hdynmk6r22z27h6tvur/bafkreihwihm6kpd6zuwhhlro75p5qks5qtrcu55jp3gddbfjsieiv7wuka",
"banner": "https://cdn.bsky.app/img/banner/plain/did:plc:z72i7hdynmk6r22z27h6tvur/bafkreichzyovokfzmymz36p5jibbjrhsur6n7hjnzxrpbt5jaydp2szvna",
"followers_count": 34151861,
"follows_count": 11,
"posts_count": 802,
"created_at": "[redacted-phone]T04:53:57.057Z",
"indexed_at": "[redacted-phone]T21:05:26.152Z",
"labels": [],
"verified": false,
"pinned_post": "at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.post/3l6oveex3ii2l",
"associated": {
"feedgens": 7,
"lists": 16,
"starter_packs": 13,
"is_labeler": false
},
"url": "https://bsky.app/profile/bsky.app"
}
}What the Bluesky API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| profile | actor profile: did/handle/displayName/desc/followers/follows/posts counts/avatar/banner/labels (+ batch via 'actors' <=25). Requires actor OR actors (engine-enforced; required_params=() so the actors-only batch isn't rejected by the gateway literal-key validator). | Social-listening tools call profile to get actor profile. | actor, actors |
| author_feed | an actor's posts (full record+embed+counts), cursor-paginated; filter=posts_no_replies|posts_with_replies|posts_with_media|posts_and_author_threads | Creator and influencer platforms call author_feed to get an actor's posts (full record+embed+counts), cursor-paginated; filter=posts_no_replies|posts_…. | actor, limit, filter, cursor |
| search_actors | search users by name/handle/bio (cursor); typeahead=true for fast suggest | Brand-monitoring teams call search_actors to search users by name/handle/bio (cursor); typeahead=true for fast suggest. | q, limit, cursor, typeahead |
| thread | a post + its reply tree (recursive) + parent | Audience analysts call thread to get a post + its reply tree (recursive) + parent. | uri, depth, parent_height |
| post_detail | hydrate one or more posts by at:// URI (<=25): record/embed/like+repost+reply+quote counts | Social-listening tools call post_detail to get hydrate one or more posts by at:// URI (<=25). | uris |
| likes | actors who liked a post (cursor); cid auto-used if given | Creator and influencer platforms call likes to get actors who liked a post (cursor); cid auto-used if given. | uri, cid, limit, cursor |
| reposts | actors who reposted a post (cursor) | Brand-monitoring teams call reposts to get actors who reposted a post (cursor). | uri, cid, limit, cursor |
| followers | actors following the subject (cursor) | Audience analysts call followers to get actors following the subject (cursor). | actor, limit, cursor |
| follows | actors the subject follows (cursor) | Social-listening tools call follows to get actors the subject follows (cursor). | actor, limit, cursor |
| quotes | Accounts/posts that QUOTE a given post (quote-posts), cursor-paginated. The other half of a post's engagement alongside likes and reposts. | Creator and influencer platforms call quotes to get accounts/posts that QUOTE a given post (quote-posts), cursor-paginated. | uri, cid, limit, cursor |
| suggested_follows | Accounts suggested from a given account — Bluesky's 'who to follow next' / similar-accounts set. Not paginated (a fixed suggestion set, ~10-50 actors). | Brand-monitoring teams call suggested_follows to get accounts suggested from a given account. | actor, limit |
| lists | The curated/moderation lists an account CREATED (user-curated lists + mute/block mod-lists), cursor-paginated. | Audience analysts call lists to get the curated/moderation lists an account CREATED (user-curated lists + mute/block mod-lists),…. | actor, limit, cursor |
| list | A single list's metadata plus its MEMBERS (the accounts on the list), members cursor-paginated. | Social-listening tools call list to get a single list's metadata plus its MEMBERS (the accounts on the list), members cursor-paginated.. | list, limit, cursor |
| list_feed | The feed of posts authored by the members of a list (a list used as a custom timeline), cursor-paginated. | Creator and influencer platforms call list_feed to get the feed of posts authored by the members of a list (a list used as a custom timeline), curso…. | list, limit, cursor |
| actor_feeds | The custom feed generators an account CREATED (its published feeds), cursor-paginated. | Brand-monitoring teams call actor_feeds to get the custom feed generators an account CREATED (its published feeds), cursor-paginated.. | actor, limit, cursor |
| feed_generator | One custom feed generator's metadata plus its live online/valid status (is the feed service up). | Audience analysts call feed_generator to get one custom feed generator's metadata plus its live online/valid status (is the feed service up).. | feed |
| popular_feeds | Discover popular custom feed generators — pass `q` to search feeds by name/topic, or omit for the platform-wide popular list. Cursor-paginated. | Social-listening tools call popular_feeds to discover popular custom feed generators. | q, limit, cursor |
| get_feed | The posts served BY a custom feed generator (e.g. a Discover/What's-Hot/topic feed) by its at:// URI, cursor-paginated. Public — no account required. | Creator and influencer platforms call get_feed to get the posts served BY a custom feed generator (e.g. | feed, limit, cursor |
| starter_packs | The starter packs an account CREATED (shareable onboarding bundles of accounts + feeds), cursor-paginated. | Brand-monitoring teams call starter_packs to get the starter packs an account CREATED (shareable onboarding bundles of accounts + feeds), curs…. | actor, limit, cursor |
| starter_pack | One starter pack's full detail: its underlying list, sample member profiles and any bundled feeds. | Audience analysts call starter_pack to get one starter pack's full detail. | starter_pack |
| search_posts | Search Bluesky posts by keyword or hashtag — filter by sort order, date range, author, language, domain or tag. Requires an app-password; returns a clear error if none is configured. | Social-listening tools call search_posts to search Bluesky posts by keyword or hashtag. | q, sort, limit, cursor, since, ... |
| get_actor_likes | posts an actor liked (authed; the AppView serves the authenticated account's own likes). Defaults to the logged-in handle. | Creator and influencer platforms call get_actor_likes to get posts an actor liked (authed; the AppView serves the authenticated account's own likes). | actor, limit, cursor |
| timeline | the authenticated account's home timeline (authed) | Brand-monitoring teams call timeline to get the authenticated account's home timeline (authed). | limit, cursor, algorithm |
Call profile from your stack
curl -X POST https://api.reefapi.com/bluesky/v1/profile \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"actor":"bsky.app"}'import requests
r = requests.post(
"https://api.reefapi.com/bluesky/v1/profile",
headers={"x-api-key": REEF_KEY},
json={
"actor": "bsky.app"
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/bluesky/v1/profile", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"actor": "bsky.app"
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.bluesky.profile with {"actor":"bsky.app"}.Who uses this API and why
- Social analytics call profile and author_feed to measure a handle's reach.
- Brand monitoring uses search_actors and thread to track mentions.
- Research uses likes and reposts to gauge engagement.
Questions developers ask before integrating
Should I key my records on the Bluesky handle or the DID?
The DID. A handle is a domain the account owner controls and can change; the did:plc identifier never moves. On 2026-08-27, actor bsky.app and actor did:plc:z72i7hdynmk6r22z27h6tvur returned the same profile field for field, so you lose nothing by resolving to the DID once and storing that.
Why does author_feed return posts written by other accounts?
Because reposts are part of an author's feed. A live author_feed read for bsky.app returned three posts, one of which carried an author.handle and author.did belonging to a different account entirely. The filter parameter controls replies and media, not reposts, so if you only want the account's own writing, compare each post's author.did to the subject's DID and drop the ones that differ.
Which engagement counts come back on a post?
Five, all as integers on every post object: like_count, repost_count, reply_count, quote_count and bookmark_count. One measured post carried 5,144 likes, 1,224 reposts, 235 replies, 519 quotes and 288 bookmarks. bookmark_count is worth knowing about because the Bluesky web interface does not display it anywhere.
Why does thread return far fewer replies than reply_count claims?
reply_count is the post's lifetime counter and the tree is what the network will serve right now. A live thread call on the bsky.app pinned post returned reply_total 159 while the root post's own reply_count read 8,569. Deleted accounts, blocked authors and replies deeper than your depth setting all drop out of the tree but stay in the counter. Raise depth, which accepts 0 to 100, to recover the deeper levels; nothing will recover the deleted ones.
What does the verified field mean, and why is it sometimes null?
It is tri-state. jay.bsky.team returned verified true, the official bsky.app account returned false, and authors embedded inside a quoted post returned null. Null means the check was not evaluated in that context rather than that the account failed it, so treat only an explicit true as verification and never read null as false.
What is the associated block on a profile?
A count of the things that account publishes. bsky.app returned associated with feedgens 7, lists 17, starter_packs 14 and is_labeler false. Use it as a cheap check before spending a call: if feedgens is 0 there is no point calling actor_feeds, and is_labeler tells you whether the account issues moderation labels.
Can I look up several accounts in one call?
Yes. Pass actors with up to 25 handles or DIDs instead of a single actor, and the response shape changes to data.profiles[] plus a count, with meta.batch true. A measured two-actor batch returned both full profiles including followers_count, associated and pinned_post. pinned_post is an at:// URI when one is set and null when it is not.
What comes back for a handle that does not exist?
A clean failure, not an empty object. profile for a made-up handle returned ok false with error.code NOT_FOUND, retryable false, and detail.context app.bsky.actor.getProfile. Because retryable is false, do not put that call in a retry loop; the handle is simply not on the network.
What is the Bluesky API?
Bluesky API is a ReefAPI endpoint group for profiles, posts, followers and the social graph. It returns live JSON through POST requests under /bluesky/v1.
Is the Bluesky API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. Bluesky calls use the same shared credit balance as every other ReefAPI engine.
Do I need a Bluesky login or account?
No login to Bluesky is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the Bluesky data?
The page example is captured from a live profile call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the Bluesky API use?
Bluesky actions currently cost 1 credit per successful call. Failed or blocked calls are free, and all APIs draw from one credit pool.
Can I call Bluesky from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call bluesky actions with the same key, credit pool and JSON envelope used by normal REST requests.