Bluesky User Posts
Bluesky User Posts are public publications collected from one account using its handle or decentralized identifier. Each normalized record can retain post text, author identity, source and collection times, public media, hashtags, mentions, and available engagement counters.
Features
- Two account identifiersSubmit exactly one identifier: either a Bluesky handle such as jay.bsky.team or a DID matching the did:method:identifier form.
- One-page account collectionSend one provider request for the selected account and collect the public posts exposed in that source page without a caller-controlled source cursor or result limit.
- Stable post-shaped resultsRead normalized post identity, text, author, timestamps, metrics, media, hashtags, and mentions instead of depending on a provider response envelope.
Parameters
| Parameters | Required | Description |
|---|---|---|
username | Required (at least one) | A public Bluesky handle from 1 to 253 characters using letters, digits, periods, or hyphens. A leading @ is not accepted; omit this field when user_id is supplied instead. |
user_id | Required (at least one) | A Bluesky decentralized identifier beginning with did:, followed by a lowercase method and a non-empty identifier using supported letters, digits, periods, underscores, colons, percent signs, or hyphens. |
How to Use
Submit a Bluesky handle or DID, track the asynchronous task, and read its saved PostItem records after completion.
- Choose either a public Bluesky handle without a leading @ or the account DID.
- POST the chosen identifier to /v1/bluesky/user-posts and save the returned task_id.
- Poll /v1/tasks/{task_id} until the task succeeds or reports a failure.
- Read data.results.items; use the task response's next_cursor only when the saved result set has another page.
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"}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items after the task succeedsBest Use Cases
- Account content snapshots: Capture a point-in-time page of public posts for a known handle or DID, retaining post IDs, source URLs, publication times, and collection times.
- Publishing pattern research: Review normalized text, authorship, hashtags, mentions, and available media to study themes and formats within a selected public account.
- Visible engagement comparison: Compare available likes, comments, shares, and views across collected posts while treating absent counters as unavailable rather than zero.
Pro Tips
- Submit handles without @ and validate them against letters, digits, periods, and hyphens before creating a task.
- Use the complete DID when account identity must remain stable across handle changes; do not send an arbitrary user ID.
- Do not add results_limit or a source cursor to the POST payload: the provider collection is one page and those fields are rejected.
- Treat author details, media, hashtags, mentions, and individual counters as optional, and deduplicate repeated snapshots with the post id.
Related APIs
Use these APIs when you need a different type of public Bluesky data.
- Bluesky Profile API — Retrieve one public Bluesky profile from a validated username with normalized identity, biography, imagery, website, status fields, visible account counts, and collection context.
- Bluesky Post API — Resolve one known public bsky.app post URL into normalized text, author, media, timestamp, tag, mention, and visible engagement fields.