# Bluesky (/docs/bluesky)

Bluesky profiles, user feeds, and single posts with their reply threads, from the AT Protocol network

Public Bluesky data on the AT Protocol network: an account snapshot, its feed, and any single post together with the replies underneath it. Three endpoints, all 1 credit, no OAuth and no app password.

Base URL: `/v1/bluesky/...`

  There is no search endpoint on this platform, and no separate comments
  endpoint. `/v1/bluesky/post` returns a post together with its reply thread, or
  not at all. Start from a handle you already hold.

## Quickstart

### 1. Fetch a profile

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/bluesky/profile?handle=espn.com" \
  -H "x-api-key: YOUR_API_KEY"
```

### 2. Fetch their content

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/bluesky/user/posts?handle=espn.com" \
  -H "x-api-key: YOUR_API_KEY"
```

### 3. Read computed fields

When an endpoint supports a computed field and the required source inputs are present, the unified response includes that optional field. Depending on the endpoint, optional fields can include `engagement_rate`, `language`, `content_category`, and `estimated_reach`. See [Computed fields](/docs/computed-fields.md) for formulas, clamping rules, and null semantics. Where an endpoint supports them, list rows also carry judged labels (`computed.labels`, `computed.relevance`) by default at no extra credits; see [Labels](/docs/labels.md).

## Accounts and posts

| Endpoint                     | Credits | What it returns                                                                                    | Key parameters        |
| ---------------------------- | ------- | -------------------------------------------------------------------------------------------------- | --------------------- |
| `GET /v1/bluesky/profile`    | 1       | Display name, description, avatar, follower, following and post counts, join date, verified status | `handle`              |
| `GET /v1/bluesky/user/posts` | 1       | The account's feed, one fixed window                                                               | `handle` or `user_id` |
| `GET /v1/bluesky/post`       | 1       | One post **plus its reply thread**, in the same call                                               | `url`                 |

Each feed post carries its text, author, attachments, and the four engagement counts Bluesky publishes: replies, reposts, likes, and **quotes**. Quote counts are their own number here rather than being folded into reposts, which is a distinction most platforms do not make.

`user/posts` accepts either `handle` or `user_id`. One of the two is required, and sending neither is a `400` before billing.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/bluesky/post?url=https://bsky.app/profile/espn.com/post/3lqdfq7fkvm2g" \
  -H "x-api-key: YOUR_API_KEY"
```

## Two identifiers, one of them permanent

Bluesky identifies accounts two ways. The **handle** is the readable one and is usually a domain such as `espn.com` or `bsky.app`, because Bluesky lets you verify a domain as your handle. The **`did`** is the permanent identifier, in the form `did:plc:x7d6j54pm22ufehkes6jo4jf`.

A handle can change; a `did` cannot. Store the `did` if you are tracking an account over time, and pass it as `user_id` when you read the feed back.

## All endpoints

## Platform notes

**There is no search endpoint on this platform.** Keyword discovery on Bluesky is not covered here. Start from a handle you already know, or find accounts elsewhere and pivot in.

**Handles look like domains and that is correct.** Do not strip a `.com` off a Bluesky handle the way you would strip an `@` elsewhere. The domain _is_ the handle.

**Reposts and quotes are different numbers.** A repost carries no new text; a quote does. Adding them together double-counts the amplification.

**Nothing here pages.** `user/posts` returns one fixed window, and a post's replies arrive with the post.

**`user_id` is the AT Protocol `did`, not a numeric id.**

## Next steps

- [Pagination](/docs/pagination.md): Cursor and page walks, and what has_more actually means.
- [Credits](/docs/credits.md): What each tier costs and when a call is refunded.
- [API reference](/docs/api-reference.md): Every parameter and response field, endpoint by endpoint.
- [Threads](/docs/threads.md): The other text network, same canonical Post object.
- [Universal search](/docs/search/everywhere.md): Keyword discovery across sources, where Bluesky has none of its own.