Bluesky Profile
Bluesky profiles are public account records with a durable identifier, handle, display name, biography, profile imagery, website, and visible follower, following, and post counts. These identity fields and account signals support profile enrichment, public account comparison, and observation over time.
Features
- Direct username lookupResolve one username containing 1 to 253 letters, digits, dots, or hyphens into a public profile record.
- Normalized profile identityReturn the available profile ID, source URL, username, display name, biography, and linked website in a consistent account shape.
- Profile imagery and status fieldsKeep available avatar, cover, verification, and privacy values as nullable fields without inventing values when the source omits them.
- Visible account count snapshotGroup available follower, following, and post counts with collected_at so each public account snapshot has an observation time.
Parameters
| Parameters | Required | Description |
|---|---|---|
username | Required | Required public Bluesky username using 1 to 253 letters, digits, dots, or hyphens. Do not include a leading @, underscore, DID, profile URL, or a second username. |
How to Use
Submit one validated username, follow the asynchronous task, and read the normalized profile from the standard result response.
- Prepare one Bluesky username with letters, digits, dots, or hyphens, such as jay.bsky.team, and omit the leading @.
- Submit username to /v1/bluesky/profile and save the returned task_id.
- Poll /v1/tasks/{task_id} until the task succeeds or returns a failure.
- Read data.results.items. This lookup normally stores one profile, so has_more is false; if the generic result response reports more data, continue with next_cursor.
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"}'
# Poll GET /v1/tasks/{task_id}
# Read the profile from data.results.itemsBest Use Cases
- Known-profile enrichment: Add a public handle, display name, biography, profile images, website, and source URL to a record that already contains a Bluesky username.
- Account footprint comparison: Compare available follower, following, and post counts across separately submitted usernames using the same normalized metric keys.
- Profile presentation monitoring: Store identity, biography, imagery, website, and collected_at across repeated tasks to identify changes between public snapshots.
Pro Tips
- Strip a leading @ and validate the remaining username against letters, digits, dots, and hyphens before submission; reject DID values because this endpoint does not accept user_id.
- Use the returned id as the preferred deduplication key, then fall back to url or username when id is empty.
- Allow biography, avatar, cover, website, status flags, location, and individual metrics to be null so partial public records remain usable.
- Do not add results_limit or a username array: submit each username as its own fixed-price task and treat the normal result as a single profile.
Related APIs
Use these APIs when you need a different type of public Bluesky data.
- Bluesky Post API — Resolve one known public bsky.app post URL into normalized text, author, media, timestamp, tag, mention, and visible engagement fields.
- Bluesky User Posts API — Collect one page of public Bluesky posts by handle or DID with normalized content, author, media, timestamps, and visible engagement.