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:
- Ready-made endpoints (post engagement, profiles, search, followers and follows) that answer in Upload-Post's own shape, the same keys every time.
- The XRPC gateway, which forwards an allow-listed, read-only Bluesky method and returns Bluesky's answer untouched.
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 passeduser, 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 answers400bluesky_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
403bluesky_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
actorand you omit it but passuser, the profile's own Bluesky account is used. This applies togetProfile,getAuthorFeed,getActorFeeds,getActorStarterPacks,getFollowers,getFollows,getLists,getRelationshipsandgetSuggestedFollowsByActor(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
| Name | Required | Description |
|---|---|---|
user | Account methods: yes. Public methods: no | Upload-Post profile username with Bluesky connected. |
| the method's parameters | As Bluesky defines them | Same 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
400bluesky_invalid_parameter, with the offending names inunknown_parameters. - A method that is not in the lists below answers
400bluesky_method_not_allowed, with the full list inallowed_methods. The gateway knows 47 methods: the 27 public ones, 5 account methods and 15 that read the account's private data, which answer403bluesky_private_read_disabled. limitgoes from 1 to 100 wherever Bluesky accepts it (also onsearchActorsTypeahead).cursoris opaque: pass back thecursorBluesky 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
}
}
| Field | Description |
|---|---|
method | The method that was called. |
authenticated | true when Bluesky answered as the connected account, false for a public read. |
data | Bluesky's own JSON for that method. |
data is Bluesky's raw shapedata 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)
| Method | Notes |
|---|---|
app.bsky.actor.getProfile | |
app.bsky.actor.getProfiles | actors: up to 25. |
app.bsky.actor.searchActors | q |
app.bsky.actor.searchActorsTypeahead | q |
app.bsky.feed.getActorFeeds | |
app.bsky.feed.getAuthorFeed | filter, includePins |
app.bsky.feed.getFeed | feed |
app.bsky.feed.getFeedGenerator | |
app.bsky.feed.getFeedGenerators | feeds: up to 25. |
app.bsky.feed.getLikes | |
app.bsky.feed.getListFeed | |
app.bsky.feed.getPostThread | depth, parentHeight |
app.bsky.feed.getPosts | uris: up to 25. |
app.bsky.feed.getQuotes | sort: latest or top. |
app.bsky.feed.getRepostedBy | |
app.bsky.graph.getActorStarterPacks | |
app.bsky.graph.getFollowers | sort |
app.bsky.graph.getFollows | sort |
app.bsky.graph.getList | |
app.bsky.graph.getLists | purposes |
app.bsky.graph.getRelationships | others: up to 30. |
app.bsky.graph.getStarterPack | |
app.bsky.graph.getStarterPacks | uris: up to 25. |
app.bsky.graph.getSuggestedFollowsByActor | |
app.bsky.graph.searchStarterPacks | |
app.bsky.graph.searchStarterPacksV2 | |
app.bsky.labeler.getServices | dids: up to 25; detailed. |
Account methods (user required)
| Method | Notes |
|---|---|
app.bsky.embed.getEmbedExternalView | url, canonicalUri, uris (up to 4). |
app.bsky.feed.searchPosts | q, sort, since, until, mentions, author, lang, domain, url, tag (up to 10). |
app.bsky.feed.searchPostsV2 | Every 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.
| Method | Use 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.getPreferences | GET /bluesky/notification-preferences |
app.bsky.notification.getUnreadCount | GET /bluesky/notifications/unread-count |
app.bsky.notification.listActivitySubscriptions | GET /bluesky/activity-subscriptions |
app.bsky.notification.listNotifications | GET /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/*withplatform=bluesky.com.atproto.*andtools.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:
| Field | Description |
|---|---|
id | at:// URI of the post. |
cid | Content id of the post version. |
url | Link to the post on bsky.app. |
text | Post text. |
author | Account object. |
created_at, indexed_at | When it was written and when Bluesky indexed it. |
like_count, repost_count, reply_count, quote_count, bookmark_count | Counters. |
langs | Languages declared on the post. |
media_type, media_url, thumbnail_url | Attached media, same values as Media List. |
reply_to, thread_root | at:// 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.
| Name | Required | Description |
|---|---|---|
platform | No | bluesky (the only value supported; anything else answers 400 unsupported_platform). |
post_id | Yes | at:// URI or bsky.app link of the post. |
type | No | likes (default), reposts or quotes. |
limit | No | 1-100. |
cursor | No | pagination.next_cursor of the previous page. |
sort | No | latest or top. Only with type=quotes. |
user | No | Profile 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
| Name | Required | Description |
|---|---|---|
actor | No | Handle or DID, or several separated by commas (up to 25). Without it, the profile's own Bluesky account (needs user). |
user | No | Profile 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).
| Name | Required | Description |
|---|---|---|
user | Yes | Profile username. |
q | Yes | Search text. |
sort | No | latest or top. |
since, until | No | Date range: YYYY-MM-DD or an ISO-8601 datetime with a time zone. |
author, mentions | No | Handle or DID. |
lang | No | Language code, e.g. en. |
domain, url | No | Posts linking to a domain or URL. |
tag | No | Hashtag (without #); up to 10. |
limit, cursor | No | Paging (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
| Name | Required | Description |
|---|---|---|
q | Yes | Search text. |
typeahead | No | true for fast prefix matching (for autocomplete boxes), false (default) for full search. |
limit, cursor | No | Paging (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
| Name | Required | Description |
|---|---|---|
actor | No | Handle or DID. Without it, the profile's own Bluesky account (needs user). |
user | No | Profile username. |
sort | No | latest or top. |
limit, cursor | No | Paging (1-100). |
known | No | Followers 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
429bluesky_read_rate_limitedwithretry_after(seconds) and aRetry-Afterheader. 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 (
429bluesky_read_rate_limited) and a shared ceiling for all accounts together; when it is reached they answer503bluesky_read_capacitywithretry_after. - Public reads. Reads of public data have their own limit of 150 per 5 minutes per Upload-Post account (
429bluesky_read_rate_limited) and their own shared ceiling (503bluesky_read_capacity). - The
429message states the limit that was reached, andretry_aftersays when to try again. When the limits cannot be checked, reads are refused with503bluesky_read_capacityinstead of going through unchecked. - Timeout. Each call to Bluesky waits up to 20 seconds; past that the read answers
502bluesky_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
}
| Status | error_code | Meaning |
|---|---|---|
| 400 | bluesky_invalid_parameter | A parameter has a wrong value, or the method does not have it (unknown_parameters). |
| 400 | bluesky_missing_parameter | A required parameter is missing. |
| 400 | bluesky_method_not_allowed | The method is not one of the allowed reads. allowed_methods lists them. |
| 400 | bluesky_user_required | The read needs the connected account: pass user. |
| 400 | bluesky_not_connected | The profile has no Bluesky account connected. |
| 400 | bluesky_rejected | Bluesky rejected the request; error carries Bluesky's message. |
| 400 | unsupported_platform | post-engagement with a platform other than bluesky. |
| 401 | bluesky_reauth_required | Bluesky refused the account's app password (revoked or changed). Reconnect the Bluesky account. Only this definitive refusal is a 401. |
| 403 | bluesky_auth_required | Bluesky only answers this read for a signed-in account: pass user. |
| 403 | bluesky_private_read_disabled | The method reads the account's private data and is not enabled on the gateway. See Private account data. |
| 403 | bluesky_blocked | There is a block between the account and the one requested. |
| 404 | bluesky_not_found | Bluesky could not find the post, account, feed or list. |
| 429 | bluesky_rate_limited | Bluesky's own rate limit. Wait retry_after seconds. |
| 429 | bluesky_read_rate_limited | Upload-Post's per-minute limit for these reads (see above). |
| 502 | bluesky_unavailable | Bluesky did not answer. Retry shortly. |
| 502 | bluesky_login_failed | Signing in to Bluesky failed for a temporary reason. Retry in a few minutes: sign-in attempts for that account are paused for 5 minutes. |
| 502 | bluesky_session_unavailable | Bluesky did not accept the account's session right now. Retryable: try again shortly. |
| 503 | bluesky_edge_rate_limited | Bluesky is temporarily limiting traffic from Upload-Post. retry_after is 300 seconds. |
| 503 | bluesky_read_capacity | Reads are busy right now (the shared ceiling, see Caching and limits). Retry after retry_after. |
| 503 | bluesky_reads_disabled | Bluesky reads are temporarily disabled. Retry later. |
When Bluesky itself names the error (for example BlockedActor or NotFound), it is added as bluesky_error.