Skip to main content

Bluesky Reads

Read Bluesky through Upload-Post: profiles, feeds, threads, who liked or reposted a post, searches, followers, lists, starter packs and more. There are two ways to do it:

Notifications (list, unread count, mark as seen, preferences, activity subscriptions) have their own page: Bluesky Notifications. Direct messages are in Direct Messages, comments on your posts in Comments and your own posts in Media List.


Authentication and the user parameter​

Send your API key as usual:

Authorization: Apikey your-api-key-here

user is the Upload-Post profile username that has the Bluesky account connected.

  • Public reads (profiles, author feeds, threads, likes, followers, actor search…) work without user. They are read from Bluesky's public API and do not use the connected account's session, so they never touch the account. If Bluesky only answers a public read for a signed-in viewer and you passed user, the read is retried once with the account.
  • Account reads (post search, known followers, notifications…) need user: they are read as that Bluesky account. Without it the call answers 400 bluesky_user_required. They have a tighter limit than public reads (see Caching and limits).
  • The account's private data (timeline, bookmarks, likes, mutes, blocks, preferences, suggestions…) is not readable through the gateway: those methods answer 403 bluesky_private_read_disabled. Notifications have their own endpoints, and followers the account also follows are on /bluesky/followers?known=true. The account's birth date is never returned.
  • When a method takes an actor and you omit it but pass user, the profile's own Bluesky account is used. This applies to getProfile, getAuthorFeed, getActorFeeds, getActorStarterPacks, getFollowers, getFollows, getLists, getRelationships and getSuggestedFollowsByActor (and to the profile and followers and follows endpoints).

Post references (uri, uris, post_id) accept either the at:// URI or the post link from the Bluesky app, https://bsky.app/profile/<handle>/post/<rkey>.


XRPC gateway​

GET /api/uploadposts/bluesky/xrpc/{nsid}

Calls one read-only Bluesky method (nsid, for example app.bsky.feed.getAuthorFeed) and returns Bluesky's JSON.

Query parameters​

NameRequiredDescription
userAccount methods: yes. Public methods: noUpload-Post profile username with Bluesky connected.
the method's parametersAs Bluesky defines themSame names as in Bluesky's API, in camelCase (includePins, parentHeight, canonicalUri…). Array parameters: repeat the parameter (actors=a&actors=b) or separate the values with commas.
  • A parameter the method does not have answers 400 bluesky_invalid_parameter, with the offending names in unknown_parameters.
  • A method that is not in the lists below answers 400 bluesky_method_not_allowed, with the full list in allowed_methods. The gateway knows 47 methods: the 27 public ones, 5 account methods and 15 that read the account's private data, which answer 403 bluesky_private_read_disabled.
  • limit goes from 1 to 100 wherever Bluesky accepts it (also on searchActorsTypeahead). cursor is opaque: pass back the cursor Bluesky returned.

Response​

{
"success": true,
"platform": "bluesky",
"method": "app.bsky.actor.getProfile",
"authenticated": false,
"data": {
"did": "did:plc:z72i7hdynmk6r22z27h6tvur",
"handle": "bsky.app",
"displayName": "Bluesky",
"followersCount": 32000000,
"followsCount": 5,
"postsCount": 650
}
}
FieldDescription
methodThe method that was called.
authenticatedtrue when Bluesky answered as the connected account, false for a public read.
dataBluesky's own JSON for that method.
data is Bluesky's raw shape

data is passed through exactly as Bluesky returns it, following Bluesky's lexicon (camelCase keys, $type, embeds…). If Bluesky changes the lexicon of a method, data changes with it. If you want a stable shape, use the ready-made endpoints on this page, whose keys are Upload-Post's.

Public methods (no user needed)​

MethodNotes
app.bsky.actor.getProfile
app.bsky.actor.getProfilesactors: up to 25.
app.bsky.actor.searchActorsq
app.bsky.actor.searchActorsTypeaheadq
app.bsky.feed.getActorFeeds
app.bsky.feed.getAuthorFeedfilter, includePins
app.bsky.feed.getFeedfeed
app.bsky.feed.getFeedGenerator
app.bsky.feed.getFeedGeneratorsfeeds: up to 25.
app.bsky.feed.getLikes
app.bsky.feed.getListFeed
app.bsky.feed.getPostThreaddepth, parentHeight
app.bsky.feed.getPostsuris: up to 25.
app.bsky.feed.getQuotessort: latest or top.
app.bsky.feed.getRepostedBy
app.bsky.graph.getActorStarterPacks
app.bsky.graph.getFollowerssort
app.bsky.graph.getFollowssort
app.bsky.graph.getList
app.bsky.graph.getListspurposes
app.bsky.graph.getRelationshipsothers: up to 30.
app.bsky.graph.getStarterPack
app.bsky.graph.getStarterPacksuris: up to 25.
app.bsky.graph.getSuggestedFollowsByActor
app.bsky.graph.searchStarterPacks
app.bsky.graph.searchStarterPacksV2
app.bsky.labeler.getServicesdids: up to 25; detailed.

Account methods (user required)​

MethodNotes
app.bsky.embed.getEmbedExternalViewurl, canonicalUri, uris (up to 4).
app.bsky.feed.searchPostsq, sort, since, until, mentions, author, lang, domain, url, tag (up to 10).
app.bsky.feed.searchPostsV2Every parameter of Bluesky's lexicon (query, authors, hashtags, …).
app.bsky.graph.getListsWithMembership
app.bsky.graph.getStarterPacksWithMembership

Private account data (not enabled)​

These methods read the connected account's private data. They are known to the gateway but not enabled on it: they answer 403 bluesky_private_read_disabled.

MethodUse instead
app.bsky.actor.getPreferences—
app.bsky.actor.getSuggestions—
app.bsky.bookmark.getBookmarks—
app.bsky.feed.getActorLikes—
app.bsky.feed.getTimeline—
app.bsky.feed.getSuggestedFeeds—
app.bsky.graph.getBlocks—
app.bsky.graph.getMutes—
app.bsky.graph.getListBlocks—
app.bsky.graph.getListMutes—
app.bsky.graph.getKnownFollowers/bluesky/followers?known=true
app.bsky.notification.getPreferencesGET /bluesky/notification-preferences
app.bsky.notification.getUnreadCountGET /bluesky/notifications/unread-count
app.bsky.notification.listActivitySubscriptionsGET /bluesky/activity-subscriptions
app.bsky.notification.listNotificationsGET /bluesky/notifications

Not available (on purpose)​

  • Writes of any kind. The gateway only reads. To publish, reply or send DMs use the regular endpoints (upload, comments, DMs); notification settings have their own endpoints.
  • app.bsky.unspecced.* (unstable).
  • app.bsky.notification.getGroupedNotifications (Bluesky marks it unstable).
  • chat.bsky.*: use /api/uploadposts/dms/* with platform=bluesky.
  • com.atproto.* and tools.ozone.*.

Example​

curl -G 'https://api.upload-post.com/api/uploadposts/bluesky/xrpc/app.bsky.feed.getAuthorFeed' \
--data-urlencode 'actor=bsky.app' \
--data-urlencode 'filter=posts_with_media' \
--data-urlencode 'includePins=true' \
--data-urlencode 'limit=20' \
-H 'Authorization: Apikey your-api-key-here'
# Account method: post search (Bluesky only answers it for a signed-in account)
curl -G 'https://api.upload-post.com/api/uploadposts/bluesky/xrpc/app.bsky.feed.searchPosts' \
--data-urlencode 'user=my-profile' \
--data-urlencode 'q=upload-post' \
--data-urlencode 'limit=30' \
-H 'Authorization: Apikey your-api-key-here'

Ready-made endpoints​

These return Upload-Post's own shape. Two objects repeat across them:

Account (a Bluesky user):

{
"id": "did:plc:abc123...",
"handle": "alice.bsky.social",
"display_name": "Alice",
"avatar": "https://cdn.bsky.app/img/avatar/...",
"url": "https://bsky.app/profile/alice.bsky.social"
}

Always present: id (the DID), handle, display_name, avatar, url. Added when Bluesky returns them: description, followers_count, follows_count, posts_count, banner, created_at, indexed_at, pinned_post_id, viewer (relationship with the connected account: following, followedBy, muted, blockedBy, blocking), labels.

Post:

FieldDescription
idat:// URI of the post.
cidContent id of the post version.
urlLink to the post on bsky.app.
textPost text.
authorAccount object.
created_at, indexed_atWhen it was written and when Bluesky indexed it.
like_count, repost_count, reply_count, quote_count, bookmark_countCounters.
langsLanguages declared on the post.
media_type, media_url, thumbnail_urlAttached media, same values as Media List.
reply_to, thread_rootat:// URIs of the parent and the root when the post is a reply, otherwise null.

Every list has the same pagination: {"next_cursor": "...", "has_more": true}. Pass next_cursor back as cursor.

Post engagement (likes, reposts, quotes)​

GET /api/uploadposts/post-engagement?platform=bluesky

Who liked, reposted or quoted a post.

NameRequiredDescription
platformNobluesky (the only value supported; anything else answers 400 unsupported_platform).
post_idYesat:// URI or bsky.app link of the post.
typeNolikes (default), reposts or quotes.
limitNo1-100.
cursorNopagination.next_cursor of the previous page.
sortNolatest or top. Only with type=quotes.
userNoProfile username. Not needed: this is a public read.

items are accounts for likes (plus liked_at) and reposts, and posts for quotes.

curl -G 'https://api.upload-post.com/api/uploadposts/post-engagement' \
--data-urlencode 'platform=bluesky' \
--data-urlencode 'post_id=https://bsky.app/profile/alice.bsky.social/post/3lb2xyz' \
--data-urlencode 'type=likes' \
--data-urlencode 'limit=50' \
-H 'Authorization: Apikey your-api-key-here'
{
"success": true,
"platform": "bluesky",
"post_id": "at://did:plc:abc123.../app.bsky.feed.post/3lb2xyz",
"type": "likes",
"items": [
{
"id": "did:plc:def456...",
"handle": "bob.bsky.social",
"display_name": "Bob",
"avatar": "https://cdn.bsky.app/img/avatar/...",
"url": "https://bsky.app/profile/bob.bsky.social",
"liked_at": "2026-11-12T09:14:03.120Z"
}
],
"pagination": { "next_cursor": "1731402843120::bafy...", "has_more": true }
}

Profiles​

GET /api/uploadposts/bluesky/profile
NameRequiredDescription
actorNoHandle or DID, or several separated by commas (up to 25). Without it, the profile's own Bluesky account (needs user).
userNoProfile username.

One actor answers {"success": true, "platform": "bluesky", "profile": {account}}; several answer {"profiles": [ ... ]}.

curl 'https://api.upload-post.com/api/uploadposts/bluesky/profile?actor=alice.bsky.social,bob.bsky.social' \
-H 'Authorization: Apikey your-api-key-here'

Search posts​

GET /api/uploadposts/bluesky/search/posts

Bluesky does not answer post search without a signed-in account, so user is required (400 bluesky_user_required otherwise).

NameRequiredDescription
userYesProfile username.
qYesSearch text.
sortNolatest or top.
since, untilNoDate range: YYYY-MM-DD or an ISO-8601 datetime with a time zone.
author, mentionsNoHandle or DID.
langNoLanguage code, e.g. en.
domain, urlNoPosts linking to a domain or URL.
tagNoHashtag (without #); up to 10.
limit, cursorNoPaging (1-100).

Response: {"success": true, "platform": "bluesky", "posts": [post, ...], "pagination": {...}}, plus hits_total when Bluesky reports it.

curl -G 'https://api.upload-post.com/api/uploadposts/bluesky/search/posts' \
--data-urlencode 'user=my-profile' \
--data-urlencode 'q=upload-post' \
--data-urlencode 'sort=latest' \
-H 'Authorization: Apikey your-api-key-here'

Search accounts​

GET /api/uploadposts/bluesky/search/actors
NameRequiredDescription
qYesSearch text.
typeaheadNotrue for fast prefix matching (for autocomplete boxes), false (default) for full search.
limit, cursorNoPaging (1-100).

Public read: no user needed. Response: {"success": true, "platform": "bluesky", "actors": [account, ...], "pagination": {...}}.

Followers and follows​

GET /api/uploadposts/bluesky/followers
GET /api/uploadposts/bluesky/follows
NameRequiredDescription
actorNoHandle or DID. Without it, the profile's own Bluesky account (needs user).
userNoProfile username.
sortNolatest or top.
limit, cursorNoPaging (1-100).
knownNoFollowers only. true returns only the followers of actor that the connected account also follows. Needs user.

Response:

{
"success": true,
"platform": "bluesky",
"subject": { "id": "did:plc:abc123...", "handle": "alice.bsky.social", "display_name": "Alice", "avatar": null, "url": "https://bsky.app/profile/alice.bsky.social" },
"actors": [
{ "id": "did:plc:def456...", "handle": "bob.bsky.social", "display_name": "Bob", "avatar": null, "url": "https://bsky.app/profile/bob.bsky.social" }
],
"pagination": { "next_cursor": "3lb...", "has_more": true }
}

Caching and limits​

  • Cache. Successful reads are cached for 60 seconds (notifications: 30 seconds), keyed on the validated parameters, so reordering the query string does not skip it. Public reads are shared: the same public read made by anyone within that window is answered from the cache. Account reads are cached per Bluesky account. Errors are not cached.
  • Per-minute limit. These endpoints make at most 60 calls to Bluesky per minute per Upload-Post account. Past that they answer 429 bluesky_read_rate_limited with retry_after (seconds) and a Retry-After header. Cached answers do not count. The existing comments listing (without the Bluesky thread parameters), media list and post analytics endpoints are not counted here.
  • Account reads. Reads made as the connected account (post search, notifications, notification preferences, known followers, account methods of the gateway) also have a limit of 60 per 5 minutes per Upload-Post account (429 bluesky_read_rate_limited) and a shared ceiling for all accounts together; when it is reached they answer 503 bluesky_read_capacity with retry_after.
  • Public reads. Reads of public data have their own limit of 150 per 5 minutes per Upload-Post account (429 bluesky_read_rate_limited) and their own shared ceiling (503 bluesky_read_capacity).
  • The 429 message states the limit that was reached, and retry_after says when to try again. When the limits cannot be checked, reads are refused with 503 bluesky_read_capacity instead of going through unchecked.
  • Timeout. Each call to Bluesky waits up to 20 seconds; past that the read answers 502 bluesky_unavailable.

Errors​

Every error has the same shape, and 429 / 503 also send a Retry-After header:

{
"success": false,
"error": "Too many Bluesky reads for this account (max 60 per minute). Please wait before retrying.",
"error_code": "bluesky_read_rate_limited",
"retry_after": 37
}
Statuserror_codeMeaning
400bluesky_invalid_parameterA parameter has a wrong value, or the method does not have it (unknown_parameters).
400bluesky_missing_parameterA required parameter is missing.
400bluesky_method_not_allowedThe method is not one of the allowed reads. allowed_methods lists them.
400bluesky_user_requiredThe read needs the connected account: pass user.
400bluesky_not_connectedThe profile has no Bluesky account connected.
400bluesky_rejectedBluesky rejected the request; error carries Bluesky's message.
400unsupported_platformpost-engagement with a platform other than bluesky.
401bluesky_reauth_requiredBluesky refused the account's app password (revoked or changed). Reconnect the Bluesky account. Only this definitive refusal is a 401.
403bluesky_auth_requiredBluesky only answers this read for a signed-in account: pass user.
403bluesky_private_read_disabledThe method reads the account's private data and is not enabled on the gateway. See Private account data.
403bluesky_blockedThere is a block between the account and the one requested.
404bluesky_not_foundBluesky could not find the post, account, feed or list.
429bluesky_rate_limitedBluesky's own rate limit. Wait retry_after seconds.
429bluesky_read_rate_limitedUpload-Post's per-minute limit for these reads (see above).
502bluesky_unavailableBluesky did not answer. Retry shortly.
502bluesky_login_failedSigning in to Bluesky failed for a temporary reason. Retry in a few minutes: sign-in attempts for that account are paused for 5 minutes.
502bluesky_session_unavailableBluesky did not accept the account's session right now. Retryable: try again shortly.
503bluesky_edge_rate_limitedBluesky is temporarily limiting traffic from Upload-Post. retry_after is 300 seconds.
503bluesky_read_capacityReads are busy right now (the shared ceiling, see Caching and limits). Retry after retry_after.
503bluesky_reads_disabledBluesky reads are temporarily disabled. Retry later.

When Bluesky itself names the error (for example BlockedActor or NotFound), it is added as bluesky_error.