Social networks API

Bluesky

Live private service · production acceptance passed

Retrieve public Bluesky profiles, paginated user posts, and individual posts with nested replies.

Three authenticated endpoints return structured public data with original post records, media metadata, source counts, and explicit coverage.

Base URLhttp://localhost:3013

Local development example. Replace with your service origin.

Get a Bluesky profile

GET/v1/bluesky/profile

Retrieve a public Bluesky profile by handle, including DID, display name, bio, avatar, banner, follower/following/post counts and available source extensions.

Query parameters

Field	Type	Description
handle	string	Required domain-style Bluesky handle, without @ or a profile URL. Custom domain handles are supported.

Request cURL

export BASE_URL="http://localhost:3013"
export API_KEY="your-service-key"

curl --get "$BASE_URL/v1/bluesky/profile" \
  -H "x-api-key: $API_KEY" \
  --data-urlencode "handle=example.test"

Response fields

Field	Type	Description
did	string	Stable Bluesky account identifier.
handle	string	Required domain-style Bluesky handle, without @ or a profile URL. Custom domain handles are supported.
displayName	string	Published display name when present.
description	string	Published bio when present.
avatar	string	Published avatar URL; media is not downloaded.
banner	string	Published banner URL when present.
followersCount	integer	Current source follower count.
followsCount	integer	Current source following count.
postsCount	integer	Current source post count.
labels	array	Source moderation labels; logged-out access restrictions are honored.
requestId	string	Request correlation identifier.
accounting	object	Total HTTP attempts, decoded bytes, and duration across the operation, including handle resolution and the shared retry.
success	boolean	True when usable data is returned; inspect status and coverage for omissions.
status	string	success, partial, failed, or challenged. HTTP 200 can be partial.
sourceUrl	string	Canonical profile or post URL.
fetchedAt	string	UTC retrieval time.
coverage	object	Complete means this bounded page or thread was returned without known omissions. It does not imply all historical posts or replies.

Nested fields and every response variant are in the OpenAPI specification.

Response 200 · synthetic example

{
  "success": true,
  "status": "success",
  "requestId": "00000000-0000-4000-8000-000000000001",
  "sourceUrl": "https://bsky.app/profile/example.test",
  "fetchedAt": "2026-09-10T00:00:00.000Z",
  "coverage": {
    "source": "public_api",
    "complete": true,
    "warnings": []
  },
  "accounting": {
    "upstreamRequests": 1,
    "responseBytes": 1500,
    "durationMs": 300
  },
  "did": "did:plc:abcdefghijklmnopqrstuvwx",
  "handle": "example.test",
  "displayName": "Example",
  "description": "Synthetic profile",
  "followersCount": 12,
  "followsCount": 2,
  "postsCount": 3,
  "labels": []
}

Get a Bluesky user’s posts

GET/v1/bluesky/user/posts

Retrieve one author-feed page of up to 30 posts and reposts, including replies. Provide exactly one of handle or user_id. Pass the opaque response cursor unchanged to retrieve the next page. Each feed item is the complete source post view; feed wrappers such as repost reasons are not included.

Query parameters

Field	Type	Description
handle	string	One Bluesky handle; mutually exclusive with user_id.
user_id	string	One did:plc or did:web account identifier, mutually exclusive with handle.
cursor	string	Opaque next-page cursor. Absence means the source provided no continuation; do not invent a cursor.

Request cURL

export BASE_URL="http://localhost:3013"
export API_KEY="your-service-key"

curl --get "$BASE_URL/v1/bluesky/user/posts" \
  -H "x-api-key: $API_KEY" \
  --data-urlencode "handle=example.test"

Response fields

Field	Type	Description
requestId	string	Request correlation identifier.
accounting	object	Total HTTP attempts, decoded bytes, and duration across the operation, including handle resolution and the shared retry.
success	boolean	True when usable data is returned; inspect status and coverage for omissions.
status	string	success, partial, failed, or challenged. HTTP 200 can be partial.
sourceUrl	string	Canonical profile or post URL.
fetchedAt	string	UTC retrieval time.
coverage	object	Complete means this bounded page or thread was returned without known omissions. It does not imply all historical posts or replies.
feed	array	Ordered post views: uri, cid, author, record text and facets, embeds, reply/repost/like/quote counts, labels, timestamps and source extensions.
cursor	string	Opaque next-page cursor. Absence means the source provided no continuation; do not invent a cursor.

Nested fields and every response variant are in the OpenAPI specification.

Response 200 · synthetic example

{
  "success": true,
  "status": "success",
  "requestId": "00000000-0000-4000-8000-000000000001",
  "sourceUrl": "https://bsky.app/profile/example.test",
  "fetchedAt": "2026-09-10T00:00:00.000Z",
  "coverage": {
    "source": "public_api",
    "complete": true,
    "warnings": []
  },
  "accounting": {
    "upstreamRequests": 1,
    "responseBytes": 1500,
    "durationMs": 300
  },
  "feed": [
    {
      "uri": "at://did:plc:abcdefghijklmnopqrstuvwx/app.bsky.feed.post/3abcdefghijkl",
      "cid": "synthetic-cid",
      "author": {
        "did": "did:plc:abcdefghijklmnopqrstuvwx",
        "handle": "example.test"
      },
      "record": {
        "$type": "app.bsky.feed.post",
        "text": "A synthetic public post.",
        "createdAt": "2026-09-10T00:00:00.000Z"
      },
      "replyCount": 0,
      "repostCount": 1,
      "likeCount": 2,
      "quoteCount": 0,
      "indexedAt": "2026-09-10T00:00:01.000Z"
    }
  ],
  "cursor": "opaque-next-page"
}

Get a Bluesky post

GET/v1/bluesky/post

Retrieve a public post and a bounded nested reply tree by HTTPS bsky.app URL. The profile segment accepts a handle or DID. Handles are resolved through the public profile API. Up to six reply levels and 100 visited reply nodes are included; ancestors are not fetched.

Query parameters

Field	Type	Description
url	string	Required HTTPS bsky.app/profile/<handle-or-did>/post/<record-key> URL. No credentials, ports or encoded path segments. Tracking query and fragment are discarded.

Request cURL

export BASE_URL="http://localhost:3013"
export API_KEY="your-service-key"

curl --get "$BASE_URL/v1/bluesky/post" \
  -H "x-api-key: $API_KEY" \
  --data-urlencode "url=https://bsky.app/profile/example.test/post/3abcdefghijkl"

Response fields

Field	Type	Description
requestId	string	Request correlation identifier.
accounting	object	Total HTTP attempts, decoded bytes, and duration across the operation, including handle resolution and the shared retry.
success	boolean	True when usable data is returned; inspect status and coverage for omissions.
status	string	success, partial, failed, or challenged. HTTP 200 can be partial.
sourceUrl	string	Canonical profile or post URL.
fetchedAt	string	UTC retrieval time.
coverage	object	Complete means this bounded page or thread was returned without known omissions. It does not imply all historical posts or replies.
post	object	Complete primary post view, including record, author, embeds and source engagement counts.
replies	array	Nested source thread nodes with post and replies. Missing, blocked or logged-out-restricted reply posts are omitted with a coverage warning.

Nested fields and every response variant are in the OpenAPI specification.

Response 200 · synthetic example

{
  "success": true,
  "status": "success",
  "requestId": "00000000-0000-4000-8000-000000000001",
  "sourceUrl": "https://bsky.app/profile/example.test/post/3abcdefghijkl",
  "fetchedAt": "2026-09-10T00:00:00.000Z",
  "coverage": {
    "source": "public_api",
    "complete": true,
    "warnings": []
  },
  "accounting": {
    "upstreamRequests": 2,
    "responseBytes": 1500,
    "durationMs": 300
  },
  "post": {
    "uri": "at://did:plc:abcdefghijklmnopqrstuvwx/app.bsky.feed.post/3abcdefghijkl",
    "cid": "synthetic-cid",
    "author": {
      "did": "did:plc:abcdefghijklmnopqrstuvwx",
      "handle": "example.test"
    },
    "record": {
      "$type": "app.bsky.feed.post",
      "text": "A synthetic public post.",
      "createdAt": "2026-09-10T00:00:00.000Z"
    },
    "replyCount": 0,
    "repostCount": 1,
    "likeCount": 2,
    "quoteCount": 0,
    "indexedAt": "2026-09-10T00:00:01.000Z"
  },
  "replies": []
}

Coverage & limits

Independent, stateless worker: four concurrent operations; 15-second total deadline; at most three upstream HTTP attempts with one shared transient retry. No automatic retry for challenges or HTTP 429.
Fixed public.api.bsky.app HTTPS origin. No login, cookies, browser, proxy, outbound link visits, media downloads or result storage. The service API key is never forwarded.
At most 4 MiB combined decoded JSON, depth 32 and 30,000 nodes per source response. Oversize or malformed responses fail explicitly.
User posts: one source page of up to 30 entries; source order and duplicates are preserved. Cursor continuation is caller-driven, without automatic crawling.
Single post: six reply levels and at most 100 visited reply nodes. Known unreturned replies produce replies_incomplete or reply_limit warnings. No ancestor enumeration.
Logged-out restrictions, hidden/taken-down labels and blocked/not-found embedded content are honored. A restricted primary object fails; affected feed entries or replies are omitted with explicit partial coverage. Ordinary content labels remain metadata.
Source optional fields and null values are preserved. Source caching and live counters can affect freshness. Sampled profile and feed data matched ScrapeCreators; the sampled post omits one reply restricted to logged-in viewers, with partial coverage. No credit balances, billing or caching controls are provided.

Errors & partial results

HTTP	Code / status	Meaning
200	partial	Usable data with restricted_posts_omitted, unavailable_replies_omitted, replies_incomplete, or reply_limit warnings.
400	invalid_request	Missing, duplicate, ambiguous, unsafe or unsupported parameters.
401	unauthorized	Missing or invalid worker API key.
403	restricted_page	The primary account/post requires access or is unavailable to logged-out readers.
404	not_found	The source reports a missing profile or post.
429	upstream_rate_limited	Source throttling; no automatic retry.
502	upstream_challenged	Source rejected the unauthenticated request.
502	unsupported_page	Malformed, missing or mismatched source data.
502	response_too_large / payload_too_complex	Response exceeded byte or parsing limits.
502	unsafe_redirect / request_limit / upstream_error	Bounded source retrieval could not complete.
503	busy	All worker slots are occupied.
504	timeout	Total request deadline expired.