Skip to content

About

SocQ Bluesky API examples in cURL, Node.js and Python: 3 endpoints for profile, post and user posts. Pay per call.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Bluesky API

SocQ Bluesky API API documentation License: MIT Check examples

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

Endpoints

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

Quick start

  1. Create an API key at socq.ai/dashboard/api-key.
  2. 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"
  1. 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.

How the API works

Base URL https://api.socq.ai. Every request sends the API key as a bearer token:

Authorization: Bearer <SOCQ_API_KEY>
Content-Type: application/json

All endpoints are asynchronous:

POST /v1/<publicId>  ->  data.task_id  ->  GET /v1/tasks/{task_id}  ->  queued | running | succeeded | failed
  1. Submit the JSON body to POST https://api.socq.ai/v1/<publicId>. The response returns data.task_id immediately; it means the task was created, not that data is ready.
  2. Poll GET https://api.socq.ai/v1/tasks/{task_id} until data.status is succeeded or failed (a failed task carries data.error_message).
  3. Read results. A succeeded task returns normalized records in data.results.items. Use limit (default 50, max 500) and pass data.results.next_cursor as cursor while data.results.has_more is true. fields selects up to 50 comma-separated fields or dot paths.
  4. Raw files (optional). GET https://api.socq.ai/v1/tasks/{task_id}/files lists 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

Endpoint reference

Bluesky Profile API

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

Bluesky Post API

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

Bluesky User Posts API

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

Repository contents

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

Responsible use and platform scope

  • 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.

License

MIT

About

SocQ Bluesky API examples in cURL, Node.js and Python: 3 endpoints for profile, post and user posts. Pay per call.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages