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 Failed requests are free
About this endpoint
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. Bill from meta.creditsCharged.
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.