Bluesky User Posts
Structured Bluesky data: send handles. Cursor-paginated, 1 credit per successful call.
Overview
Section titled βOverviewβCall GET /api/v2/bluesky-user-posts/ with handles. The results are in data.posts; send data.next_cursor back as cursor to get the next page. 5 optional parameters refine the call (see Parameters).
Request
Section titled βRequestβcurl -G "https://api.scrapier.io/api/v2/bluesky-user-posts/" \ -H "X-API-Key: YOUR_API_KEY" \ --data-urlencode "handles=espn.com" \ --max-time 210const params = new URLSearchParams({ handles: "espn.com" });
const res = await fetch(`https://api.scrapier.io/api/v2/bluesky-user-posts/?${params}`, { headers: { "X-API-Key": "YOUR_API_KEY" }, signal: AbortSignal.timeout(210_000),});const body = await res.json();if (!res.ok) throw new Error(body.error ?? body.detail ?? `HTTP ${res.status}`);
console.log(body.data.posts);import requests
resp = requests.get( "https://api.scrapier.io/api/v2/bluesky-user-posts/", headers={"X-API-Key": "YOUR_API_KEY"}, params={"handles": "espn.com"}, timeout=210,)body = resp.json()if not resp.ok: raise RuntimeError(body.get("error") or body.get("detail"))
print(body["data"]["posts"])curl -X POST "https://api.scrapier.io/api/v2/bluesky-user-posts/" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"handles":"espn.com"}' \ --max-time 210Parameters
Section titled βParametersβ| Name | Type | Required | Default | Description |
|---|---|---|---|---|
X-API-Key header | string | yes | β | Your API key from the dashboard. |
handles | string | yes | e.g. espn.com | Bluesky account: a handle ("espn.com", "@espn.com"), a profile URL (https://bsky.app/profile/espn.com), an at:// URI or a DID ("did:plc:x7d6j54pm22ufehkes6jo4jf") -> ONE native getAuthorFeed page (30 posts) per call in feed order, each row with the post's text, author, media, like / reply / repost / quote counts, the full post record + embed and the computed block (engagement_rate, language, content_category). An unknown / deactivated / taken-down / blocked account or an empty feed answers one status row (next_cursor null). Required on the first call; ignored when cursor is supplied. A raw Bluesky cursor (a v1 row's pagination.next_cursor) passed as cursor on the first call starts the walk there. |
cursor | string | no | β | Pagination cursor returned in the previous response's next_cursor. Pass it back unchanged to fetch the next page. When next_cursor is null, you have reached the last page. |
filter | string | no | posts_and_author_threads | posts_and_author_threads (default) | posts_no_replies | posts_with_replies | posts_with_media | posts_with_video - getAuthorFeed's own filter (applied by Bluesky after slicing, so a page can be shorter than 30). posts_and_author_threadsposts_no_repliesposts_with_repliesposts_with_mediaposts_with_video locked in cursor |
include_pins | boolean | no | true | true (default) = the pinned post rides on top of page 1 (is_pinned_copy true, an extra item); false = chronological only. locked in cursor |
compute_metrics | boolean | no | true | true (default) = getProfile on page 1 fills account_followers_count / account_posts_count and computed.engagement_rate (carried in the cursor for later pages). locked in cursor |
video_duration | boolean | no | true | true (default) = video posts get duration_seconds from their HLS playlist. locked in cursor |
Advanced
| Name | Type | Default | Description |
|---|---|---|---|
use_proxy | boolean | true | Route the request through Scrapier's residential proxy pool. Default: true. Leave as is unless support tells you otherwise. |
raw_data | boolean | false | When true, the response carries the full raw upstream payload(s) the scraper received (GraphQL / JSON API bodies, HTML, embedded JSON-LD -- exactly as the platform returned them) under raw_responses, in place of the formatted items. When false (default) you get the formatted output. Pagination (cursor / next_cursor) works the same in both modes. |
Response
Section titled βResponseβ{ "success": true, "data": { "handles": "espn.com", "handle": "espn.com", "did": "did:plc:x7d6j54pm22ufehkes6jo4jf", "filter": "posts_no_replies", "include_pins": true, "status": "ok", "note": null, "account_followers_count": 296583, "account_posts_count": 872, "page": 1, "page_size": 30, "cursor_sent": null, "bluesky_cursor": "2025-09-25T17:06:11.912Z", "has_more": true, "posts": [ { "input_handle": "espn.com", "handle": "espn.com", "did": "did:plc:x7d6j54pm22ufehkes6jo4jf", "status": "ok", "position": 1, "post_id": "3muznlkmspz2x", "uri": "at://did:plc:x7d6j54pm22ufehkes6jo4jf/app.bsky.feed.post/3muznlkmspz2x", "cid": "bafyreiceaay7jrgqznvxhttsmizofewx3mj6bwebjtz76nd2wh4hix4fty", "url": "https://bsky.app/profile/espn.com/post/3muznlkmspz2x", "text": "One more sleep until NFL football is BACK. π", "published_at": "2026-09-08T18:27:24.700Z", "indexed_at": "2026-09-08T18:27:30.159Z", "author_handle": "espn.com", "author_did": "did:plc:x7d6j54pm22ufehkes6jo4jf", "author_display_name": "ESPN", "like_count": 85, "reply_count": 8, "repost_count": 11, "quote_count": 6, "bookmark_count": 0, "is_pinned": false, "is_pinned_copy": false, "is_repost": false, "is_reply": false, "media_urls": [ "https://video.bsky.app/watch/.../playlist.m3u8" ], "thumbnail_url": "https://video.bsky.app/watch/.../thumbnail.jpg", "duration_seconds": 34.567, "post": { "id": "3muznlkmspz2x", "url": "https://bsky.app/profile/espn.com/post/3muznlkmspz2x", "content": { "text": "One more sleep until NFL football is BACK. π", "...": "..." }, "author": { "username": "espn.com", "display_name": "ESPN", "verified": true, "did": "did:plc:x7d6j54pm22ufehkes6jo4jf", "...": "..." }, "engagement": { "views": null, "likes": 85, "comments": 8, "shares": 11, "saves": 0, "quote_count": 6 }, "flags": { "nsfw": false, "spoiler": null, "pinned": false, "deleted": false }, "published_at": "2026-09-08T18:27:24.700Z", "record": { "$type": "app.bsky.feed.post", "...": "..." }, "embed": { "$type": "app.bsky.embed.video#view", "...": "..." }, "...": "(same shape as the v1 row)" }, "computed": { "engagement_rate": 0.0371, "language": "en", "content_category": "sports", "estimated_reach": null }, "category_keywords": [ "football", "nfl" ], "account_followers_count": 296583, "account_posts_count": 872, "filter": "posts_no_replies", "pagination": { "page": 1, "cursor_sent": null, "next_cursor": "2025-09-25T17:06:11.912Z", "has_more": true }, "scraped_at": "2026-09-22T08:47:10.412Z" }, { "position": 2, "post_id": "3mpglmolczz2w", "text": "Former Tennessee Titans and Arizona Cardinals running back Chris Johnson...", "like_count": 129, "reply_count": 16, "repost_count": 33, "quote_count": 17, "...": "(same shape as row 1)" }, "... 28 more rows (positions 3-30: 3mov4cob7hn2x, 3mnzrylb65e2d, ... 3lzogruhwz52e) ..." ], "warnings": [], "next_cursor": "eyJjIjoiMjAyNS0wOS0yNVQxNzowNjoxMS45MTJaIiwiaCI6ImVzcG4uY29tIiwibGsiOnsiZmlsdGVyIjoicG9zdHNfbm9fcmVwbGllcyJ9LCJwIjoxLCJwZiI6eyJkaWQiOiJkaWQ6cGxjOng3ZDZqNTRwbTIydWZlaGtlczZqbzRqZiIsImZvbGxvd2Vyc0NvdW50IjoyOTY1ODMsImhhbmRsZSI6ImVzcG4uY29tIiwicG9zdHNDb3VudCI6ODcyfSwicGluIjpudWxsLCJwb3MiOjMwLCJzIjpbImtlczZqbzRqZi8zbXV6bmxrbXNwejJ4Iiwia2VzNmpvNGpmLzNtcGdsbW9sY3p6MnciLCIuLi4iXX0" }}Bad input. The exact message varies by endpoint.
{ "success": false, "error": "β¦"}Balance below the endpointβs price.
{ "error": "Insufficient credits. Buy more to scrape more.", "balance": 1, "required": 2}Invalid or unknown API key.
{ "detail": "Authentication service unavailable or invalid API key."}Throttled β wait for Retry-After.
{ "detail": "Request was throttled. Expected available in N seconds."}Sample from the live catalog; arrays trimmed to 3 items. Results are in data.posts.
Response fields
Section titled βResponse fieldsβ| Field | Type | Example | Description |
|---|---|---|---|
handles | string | espn.com | β |
handle | string | espn.com | β |
did | string | did:plc:x7d6j54pm22ufehkes6jo4jf | β |
filter | string | posts_no_replies | β |
include_pins | boolean | true | β |
status | string | ok | β |
note | null | null | β |
account_followers_count | integer | 296583 | β |
account_posts_count | integer | 872 | β |
page | integer | 1 | β |
page_size | integer | 30 | β |
cursor_sent | null | null | β |
bluesky_cursor | string | 2025-09-25T17:06:11.912Z | β |
has_more | boolean | true | β |
posts | array | [3 items] | The results. |
warnings | array | [] | β |
next_cursor | string | eyJjIjoiMjAyNS0wOS0yNVQxNzowNjoxMS45MTJaIiwia⦠| Pass back as cursor for the next page. null on the last page. |
posts[].input_handle | string | espn.com | β |
posts[].handle | string | espn.com | β |
posts[].did | string | did:plc:x7d6j54pm22ufehkes6jo4jf | β |
posts[].status | string | ok | β |
posts[].position | integer | 1 | β |
posts[].post_id | string | 3muznlkmspz2x | β |
posts[].uri | string | at://did:plc:x7d6j54pm22ufehkes6jo4jf/app.bskβ¦ | β |
posts[].cid | string | bafyreiceaay7jrgqznvxhttsmizofewx3mj6bwebjtz7β¦ | β |
posts[].url | string | https://bsky.app/profile/espn.com/post/3muznlβ¦ | β |
posts[].text | string | One more sleep until NFL football is BACK. π | β |
posts[].published_at | string | 2026-09-08T18:27:24.700Z | β |
posts[].indexed_at | string | 2026-09-08T18:27:30.159Z | β |
posts[].author_handle | string | espn.com | β |
posts[].author_did | string | did:plc:x7d6j54pm22ufehkes6jo4jf | β |
posts[].author_display_name | string | ESPN | β |
posts[].like_count | integer | 85 | β |
posts[].reply_count | integer | 8 | β |
posts[].repost_count | integer | 11 | β |
posts[].quote_count | integer | 6 | β |
posts[].bookmark_count | integer | 0 | β |
posts[].is_pinned | boolean | false | β |
posts[].is_pinned_copy | boolean | false | β |
posts[].is_repost | boolean | false | β |
posts[].is_reply | boolean | false | β |
posts[].media_urls | array | [1 item] | β |
posts[].thumbnail_url | string | https://video.bsky.app/watch/.../thumbnail.jpg | β |
posts[].duration_seconds | number | 34.567 | β |
posts[].post | object | {β¦} | β |
posts[].computed | object | {β¦} | β |
posts[].category_keywords | array | [2 items] | β |
posts[].account_followers_count | integer | 296583 | β |
posts[].account_posts_count | integer | 872 | β |
posts[].filter | string | posts_no_replies | β |
posts[].pagination | object | {β¦} | β |
posts[].scraped_at | string | 2026-09-22T08:47:10.412Z | β |
Pagination
Section titled βPaginationβPass data.next_cursor back as cursor until it is null. Required inputs are ignored once a cursor is sent. Each page is one billed call. More in Pagination.
const url = "https://api.scrapier.io/api/v2/bluesky-user-posts/";let params = { handles: "espn.com" };const items = [];
for (let page = 0; page < 10; page++) { // each page is one billed call const res = await fetch(`${url}?${new URLSearchParams(params)}`, { headers: { "X-API-Key": "YOUR_API_KEY" }, signal: AbortSignal.timeout(210_000), }); const body = await res.json(); if (!res.ok) throw new Error(body.error ?? body.detail ?? `HTTP ${res.status}`); const data = body.data; items.push(...(data.posts ?? [])); if (!data.next_cursor) break; // null = last page params = { cursor: data.next_cursor };}import requests
URL = "https://api.scrapier.io/api/v2/bluesky-user-posts/"HEADERS = {"X-API-Key": "YOUR_API_KEY"}params = {"handles": "espn.com"}items = []
for _ in range(10): # each page is one billed call resp = requests.get(URL, headers=HEADERS, params=params, timeout=210) resp.raise_for_status() data = resp.json()["data"] items.extend(data.get("posts") or []) if not data.get("next_cursor"): # None = last page break params = {"cursor": data["next_cursor"]}Failed calls are free. Branch on the HTTP status and read the message from error (or detail). Full details in Errors.
| Status | Meaning | Retry? | Charged? |
|---|---|---|---|
400 | Bad or missing input. | No β fix the params | No |
401 / 403 | Missing, invalid or revoked API key. | No β fix the key | No |
402 | Out of credits (body has balance). | No β top up | No |
404 | Unknown endpoint slug. | No β check the slug | No |
429 / 503 | Busy or throttled. | Yes β after Retry-After | No |
5xx | Target site or upstream failure, or timeout. | Yes β with backoff | No |
- Locked into the cursor:
filter,include_pins,compute_metrics,video_duration. Set them on the first call; later pages reuse them.
Related
Section titled βRelatedβ- Bluesky Profile Info β Structured Bluesky data: send
handles. Single lookup, 1 credit per successful call. - Bluesky Single Posts β Structured Bluesky data: send
urls. Cursor-paginated, 1 credit per successful call.