Bluesky API
Account history and post data as JSON
Weekly snapshots of tracked Bluesky accounts, their history week by week, and Bluesky posts that mention public companies, over HTTPS with an API key.
featured in
The Subalytics Bluesky API gives you tracked Bluesky accounts as structured JSON: the latest weekly snapshot of each account, its history week by week, and, with Entity Mentions access, Bluesky posts that mention public companies.
Accounts are identified by a stable Subalytics ID (sub_id), shared across the creator endpoints and the mention endpoints, so data you already store joins to new data.
Every endpoint uses GET, filters with query parameters and returns the same response envelope.
Endpoints for Bluesky data
Each endpoint links to its full reference in the API documentation.
Influencers
/api/v1/influencers/?social=bluesky
The latest weekly snapshot of each Bluesky creator: subscriber counts, publication details and more. Filter by Subalytics ID, year and minimum free or paid subscribers. Cursor pagination.
Creators (historical)
/api/v1/creators-historical/?social=bluesky
Weekly creator records by Subalytics ID, platform, week and year, or a date range. Offset pagination.
Subscribers (historical)
/api/v1/subscribers-historical/?social=bluesky
Weekly subscriber statistics by Subalytics ID, platform and date, with minimum free and paid subscriber filters. Offset pagination.
Bluesky posts with company mentions
/api/v1/entity-bluesky-posts/
Top-level posts from tracked Bluesky accounts that mention at least one monitored public company, with the full post text and each mention. Part of the separate Entity Mentions product, with its own access.
Example requests
Base URL: https://subalytics.com/api/v1/. Send your API key in the X-API-key header; every request is a GET with query parameters.
curl -H "X-API-key: <your-api-key>" \
"https://subalytics.com/api/v1/influencers/?social=bluesky&free_subscribers=5000"
GET /api/v1/influencers/?social=bluesky&free_subscribers=5000
GET /api/v1/subscribers-historical/?social=bluesky&from=2025-03-01&to=2025-05-01
GET /api/v1/entity-bluesky-posts/?symbol=META&min_confidence=0.9&limit=1
Weekly creator snapshot: query parameters
The influencers endpoint returns the latest weekly snapshot of each creator. Use social=bluesky to limit it to Bluesky.
| Parameter | Type | Description |
|---|---|---|
sub_id | string | Subalytics ID of one creator |
social | string | Platform: substack, medium or bluesky |
year | int | Year of the snapshot |
free_subscribers | int | Minimum number of free subscribers |
paid_subscribers | int | Minimum number of paid subscribers |
limit | int | Results per page (default 25, max 100) |
cursor | string | next_cursor from the previous page |
Subscriber history: query parameters
The subscribers (historical) endpoint returns one record per creator per week. from and to apply to the start date of each weekly record; dates are UTC, YYYY-MM-DD.
| Parameter | Type | Description |
|---|---|---|
sub_id | string | Subalytics ID of one creator |
social | string | Platform: substack, medium or bluesky |
week_number | int | ISO week number (1–53) |
year | int | Year, e.g. 2025 |
free_subscribers | int | Minimum number of free subscribers |
paid_subscribers | int | Minimum number of paid subscribers |
from | string | Start date of the week, from (YYYY-MM-DD) |
to | string | Start date of the week, to (YYYY-MM-DD) |
limit | int | Results per page (default 25, max 100) |
offset | int | Records to skip (default 0) |
Bluesky posts with company mentions
Bluesky posts that mention at least one monitored company, each with its entities[]. Only top-level posts from tracked Bluesky accounts are included, not replies. Bluesky posts are short and public, so the full text is returned.
Filter by post (post_uri), creator (sub_id), Bluesky account (did), company (symbol), minimum confidence, publish date or last-changed date. Example response record:
| Field | Type | Description |
|---|---|---|
post_uri | string | Public post ID (AT Protocol URI) |
sub_id | string | The creator |
did | string | The Bluesky account |
url | string | Link to the post on bsky.app |
text | string | Full post text |
published_utc | date | When the post was created |
entities | array | Company mentions: mention_id, symbol, company_name, match_type, matched_text, confidence, snippet, field |
created_at | date | When the post first appeared in this product |
updated_at | date | When its mentions last changed |
{
"post_uri": "at://did:plc:exampleaccount000000000/app.bsky.feed.post/3lqz7x2kfbc2s",
"sub_id": "e81a3f90c2",
"did": "did:plc:exampleaccount000000000",
"url": "https://bsky.app/profile/did:plc:exampleaccount000000000/post/3lqz7x2kfbc2s",
"text": "$META up 4% premarket after ad revenue beat. Instagram Reels doing the heavy lifting again.",
"published_utc": "2026-09-27T14:02:11Z",
"entities": [
{
"mention_id": "9f2c41d07ab35e18",
"symbol": "META",
"company_name": "Meta Platforms, Inc.",
"match_type": "cashtag",
"matched_text": "$META",
"confidence": 0.95,
"snippet": "$META up 4% premarket after ad revenue beat.",
"field": "text"
}
],
"created_at": "2026-09-27T14:03:40Z",
"updated_at": "2026-09-27T14:03:40Z"
}
Responses and errors
Every endpoint returns the same JSON envelope. Cursor-paginated endpoints include next_cursor: pass it back as cursor to get the next page, and stop when it is null. Cursors are opaque strings: don't parse or build them.
Offset-paginated endpoints return "offset" in place of "next_cursor". An empty results list is a success, not an error.
| Code | Meaning | When |
|---|---|---|
400 | Bad request | Unknown query parameter, invalid date or date range, invalid limit or invalid cursor. The message says which. |
401 | Unauthorized | Missing API key, or the key is not enabled for this endpoint. |
500 | Server error | Something went wrong on our side. Retry later. |
{
"success": true,
"results": [ ... ],
"returned_results": 25,
"limit": 25,
"next_cursor": "6a7d976dc8173839e225382f"
}
How to get started
Request access
Tell us which endpoints you need. Keys are enabled per endpoint.
Get your API key
Send it in the X-API-key header with every request.
Query and page through results
Filter with query parameters and follow next_cursor or offset until the last page.
FAQ
Common questions
Yes. The influencers endpoint returns the latest weekly snapshot of each tracked account and the subscribers (historical) endpoint returns weekly statistics; use social=bluesky. Both filter by Subalytics ID and minimum free_subscribers.
The Bluesky posts endpoint in Entity Mentions returns top-level posts from tracked accounts that mention at least one monitored public company, with the full post text. Replies are not included.
In Entity Mentions, Bluesky posts usually appear within minutes.
Send your API key in the X-API-key header with every request. Each key is enabled for specific endpoints; a request without a valid key, or to an endpoint your key isn't enabled for, returns 401.
Every endpoint accepts limit (default 25, maximum 100). Cursor-paginated endpoints return next_cursor: pass it back as cursor and stop when it is null. Offset-paginated endpoints take offset: increase it by limit until a page returns fewer than limit results.
JSON over HTTPS. All endpoints use GET, filter with query parameters and return the same response envelope: success, results, returned_results, limit, and next_cursor or offset. Endpoint paths end with a trailing slash.
Any query parameter not listed for an endpoint is rejected with 400 and a message naming it, e.g. "Unknown parameters: bad_param", so typos don't silently return the wrong data.
Yes. A machine-readable OpenAPI 3.1 description of every documented endpoint is at https://subalytics.com/openapi.json, for API clients, code generators and AI tools.
Contact us
Have a question or a custom use case?
Tell us what you're trying to monitor or search across, and we'll get back to you within a business day.
Get access to the Bluesky API
Tell us which data you need and we'll enable the matching endpoints on your API key. The full reference, with every parameter and response field, is in the API documentation.