Bluesky Profile API
Resolve a Bluesky handle to a structured profile card and follower metrics in the shared Social Fetch JSON envelope.
GET /v1/bluesky/profiles/{handle}1 credit per successful request.
About this endpoint
Cross-network creator tools treat Bluesky like any other identity source: you have a handle (often a custom domain or `*.bsky.social`), and you need a stable card before you store posts or score reach. Standing up your own AT Protocol client works for a Bluesky-native app. For a multi-platform enrichment job that already meters TikTok and X through Social Fetch, a hosted profile GET is usually enough.
`GET /v1/bluesky/profiles/{handle}` takes a Bluesky handle with or without a leading `@` and returns the shared envelope. On `found`, `data.profile` includes handle, displayName, bio, avatarUrl, verified, profileUrl, `platformUserId` (the DID), and `createdAt` when available. `data.metrics` carries followers, following, and posts. Branch on `data.lookupStatus` first: `found` and `not_found` are explicit outcomes.
Typical uses: upsert a Bluesky row next to other networks, confirm a handle before spending credits on profile posts, or refresh public follower totals on a schedule. Pricing is on the credit badge for this operation; bill from `meta.creditsCharged`. on every response.
Bluesky Profile API FAQ
How do I get a Bluesky profile by handle via API?
Call `GET /v1/bluesky/profiles/{handle}` with your Social Fetch API key (`x-api-key`). Pass the Bluesky handle as the path parameter, with or without a leading `@` (custom domains and `*.bsky.social` handles both work). Read `data.lookupStatus`, then `data.profile` and `data.metrics` when the account is found.
How much does the Bluesky Profile API cost?
Pricing is documented on the operation in the API registry (shown on this page). Confirm on every response with meta.creditsCharged — that field is the billing source of truth.
What does the Bluesky Profile API return?
A structured card under `data.profile` (handle, display name, bio, avatar URL, verification, public profile URL, DID as `platformUserId`, and account `createdAt` when available) plus `data.metrics` (followers, following, posts). The response also includes `data.lookupStatus`, `meta.requestId`, and `meta.creditsCharged`.
What happens if the Bluesky handle does not exist?
`data.lookupStatus` is `not_found`, and `data.profile` / `data.metrics` are null. Do not treat a successful HTTP 200 as a found account without checking `lookupStatus`.
Do I need a Bluesky App Password or AT Protocol session?
No. Authenticate to Social Fetch with an API key. This route reads public profile data; it does not act as a logged-in Bluesky user.
How is this different from listing a profile's posts?
This route returns the identity card and aggregate metrics for one handle. Recent posts are `GET /v1/bluesky/profiles/{handle}/posts`. Call the profile route first when you need an explicit `lookupStatus` before interpreting an empty post list.
Can I use the Bluesky Profile API in a multi-network creator database?
Yes. Teams use it to upsert Bluesky rows (DID, followers, bio, verification) beside TikTok, Instagram, and X lookups on one API key, and to confirm a handle exists before spending credits on post routes.