3 endpoints for public Bluesky data through one SocQ API key, with runnable cURL, Node.js and Python examples and a valid request body for every endpoint.
Browse Bluesky APIs · Get an API key · Documentation · All SocQ examples
Prices are in SocQ credits; 1 credit = $0.005.
| Endpoint | publicId | What it returns | Price | Launched |
|---|---|---|---|---|
| Bluesky Profile API | bluesky/profile |
Retrieve one public Bluesky profile from a validated username, returning normalized identity, biography, profile images, website, and visible account counts in one asynchronous task. | 0.19 credits ($0.00095) per call | 2026-08-14 |
| Bluesky Post API | bluesky/post |
Collect one public Bluesky post from a known bsky.app URL with normalized text, author, media, timestamp, hashtag, mention, and visible engagement fields. | 0.19 credits ($0.00095) per call | 2026-08-15 |
| Bluesky User Posts API | bluesky/user-posts |
Collect one page of public Bluesky posts by handle or DID, returning normalized content, author, media, timestamps, and visible engagement fields. | 0.19 credits ($0.00095) per call | 2026-08-15 |
- Create an API key at socq.ai/dashboard/api-key.
- Export it. The examples read only
SOCQ_API_KEY.
git clone https://github.com/SocQAPI/bluesky-api.git
cd bluesky-api
export SOCQ_API_KEY="your-api-key"- Run any endpoint by its publicId. Without a second argument the script sends
payloads/<slug>.json; pass a JSON file or an inline JSON object to change the input.
# Node.js 20+
node examples/node/socq.mjs bluesky/profile
# Python 3.8+ (standard library only)
python3 examples/python/socq.py bluesky/profile payloads/profile.json
# cURL + jq
bash examples/curl/socq.sh bluesky/profile '{"username":"jay.bsky.team"}'Each script submits the task, polls it until it succeeds or fails, follows every result page, and writes the records to output/<slug>-<task_id>.json. Run npm run check to validate the payloads and scripts offline.
Never expose SOCQ_API_KEY in browser code, mobile apps, public repositories, screenshots, fixtures or logs.
Base URL https://api.socq.ai. Every request sends the API key as a bearer token:
Authorization: Bearer <SOCQ_API_KEY>
Content-Type: application/jsonAll endpoints are asynchronous:
POST /v1/<publicId> -> data.task_id -> GET /v1/tasks/{task_id} -> queued | running | succeeded | failed
- Submit the JSON body to
POST https://api.socq.ai/v1/<publicId>. The response returnsdata.task_idimmediately; it means the task was created, not that data is ready. - Poll
GET https://api.socq.ai/v1/tasks/{task_id}untildata.statusissucceededorfailed(a failed task carriesdata.error_message). - Read results. A succeeded task returns normalized records in
data.results.items. Uselimit(default 50, max 500) and passdata.results.next_cursorascursorwhiledata.results.has_moreis true.fieldsselects up to 50 comma-separated fields or dot paths. - Raw files (optional).
GET https://api.socq.ai/v1/tasks/{task_id}/fileslists raw JSONL exports.
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
-H "Authorization: Bearer $SOCQ_API_KEY"
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100&cursor=$NEXT_CURSOR" \
-H "Authorization: Bearer $SOCQ_API_KEY"callback_url (where an endpoint accepts it) makes SocQ POST to your URL when the task reaches a terminal state; keep polling as a fallback.
Billing. A submit may reserve credits from results_limit or the number of submitted inputs; when the task finishes SocQ settles the charge from the actual result count and returns unused reserved credits. 402 means insufficient credits.
Errors. 400 invalid body or unsupported field, 401 missing or invalid key, 402 insufficient credits, 403 IP allowlist or task owned by another account, 404 endpoint or task not found, 422 input validation failed, 429 rate or credit-window limit (respect Retry-After), 500 submission failed. A client-side timeout does not cancel a task: resume polling the same task_id instead of submitting again.
Reference: Authentication · Task status and results · Task files · Callbacks · Errors
Retrieve one public Bluesky profile from a validated username, returning normalized identity, biography, profile images, website, and visible account counts in one asynchronous task.
- Request:
POST https://api.socq.ai/v1/bluesky/profile - publicId:
bluesky/profile - Price: 0.19 credits ($0.00095) per call
- Launched: 2026-08-14
- Example body:
payloads/profile.json
Fetch normalized profiles data from Bluesky.
Successful tasks are billed per task.
| Field | Type | Required | Description |
|---|---|---|---|
username |
string | Yes | A Bluesky username containing 1 to 253 ASCII letters, digits, periods, or hyphens, without a leading @. (length 1 to 253; pattern ^[A-Za-z0-9.-]{1,253}$) |
curl -X POST "https://api.socq.ai/v1/bluesky/profile" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"username": "jay.bsky.team"
}'Full docs: https://docs.socq.ai/api-manual/bluesky/profile · Landing page: socq.ai/apis/bluesky/profile
Collect one public Bluesky post from a known bsky.app URL with normalized text, author, media, timestamp, hashtag, mention, and visible engagement fields.
- Request:
POST https://api.socq.ai/v1/bluesky/post - publicId:
bluesky/post - Price: 0.19 credits ($0.00095) per call
- Launched: 2026-08-15
- Example body:
payloads/post.json
Fetch normalized posts data from Bluesky.
Successful tasks are billed per task.
| Field | Type | Required | Description |
|---|---|---|---|
url |
string | Yes | A non-empty post reference with an authority component whose parsed hostname is bsky.app or a bsky.app subdomain. Any scheme is accepted when an authority and hostname are present; protocol-relative references are also accepted. |
curl -X POST "https://api.socq.ai/v1/bluesky/post" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://bsky.app/profile/jay.bsky.team/post/3micofpyeys2g"
}'Full docs: https://docs.socq.ai/api-manual/bluesky/post · Landing page: socq.ai/apis/bluesky/post
Collect one page of public Bluesky posts by handle or DID, returning normalized content, author, media, timestamps, and visible engagement fields.
- Request:
POST https://api.socq.ai/v1/bluesky/user-posts - publicId:
bluesky/user-posts - Price: 0.19 credits ($0.00095) per call
- Launched: 2026-08-15
- Example body:
payloads/user-posts.json
Fetch normalized user posts data from Bluesky.
Successful tasks are billed per task.
| Field | Type | Required | Description |
|---|---|---|---|
user_id |
string | One of* | A Bluesky decentralized identifier in did:method:identifier form. (pattern ^did:[a-z0-9]+:[A-Za-z0-9._:%-]+$) |
username |
string | One of* | A Bluesky handle containing 1 to 253 ASCII letters, digits, periods, or hyphens, without a leading @. (length 1 to 253; pattern ^[A-Za-z0-9.-]{1,253}$) |
*Required rule: send at least one of user_id, username; do not send user_id and username together.
curl -X POST "https://api.socq.ai/v1/bluesky/user-posts" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"username": "jay.bsky.team"
}'Full docs: https://docs.socq.ai/api-manual/bluesky/user-posts · Landing page: socq.ai/apis/bluesky/user-posts
| Path | Purpose |
|---|---|
examples/curl/socq.sh |
Submit, poll and paginate with cURL and jq |
examples/node/socq.mjs |
Same workflow in Node.js 20+ (no dependencies) |
examples/python/socq.py |
Same workflow in Python 3.8+ (standard library) |
payloads/ |
One documented request body per endpoint |
endpoints.json |
Endpoint list, prices and request schemas used by the scripts and checks |
fixtures/ |
Synthetic submit and task response shapes |
docs/production-notes.md |
Retries, timeouts, pagination and data handling |
scripts/check.mjs |
Offline check: payloads, syntax and secrets |
- Use only publicly accessible Bluesky data and the fields supported by each endpoint.
- Do not use the examples to access restricted content, login-only surfaces, authentication controls or non-public personal information.
- SocQ is not an official API of the represented platform and is not affiliated with or endorsed by it. Platform names and trademarks belong to their respective owners.
- Before production use, assess the laws, platform terms, privacy obligations and retention requirements that apply to your organization and use case.
- Collect only the fields needed for a defined purpose, restrict access, set retention periods, and support correction or deletion workflows where required.
This section describes the public-data boundary; it is not legal advice.