# Bluesky API guide



## Start with Bluesky



Read public accounts and posts using handles, DIDs and post URIs. Keep the original post author separate from the account that reposted it.



These requests use your API key and can spend credits. Check the current price on the endpoint page; each new page is a separate request. Later examples use illustrative identifiers: replace them with values from your earlier response.



### 1. Resolve an account



The returned id is the account DID; store it alongside the current handle. [Parameters and current cost →](https://www.monocrawl.com/docs/endpoints/bluesky/profile)



**bluesky/profile**

```
curl "https://www.monocrawl.com/v1/bluesky/profile?handle=bsky.app" \
  -H "x-api-key: mn_your_key_here"
```



### 2. Read the account feed



Supply handle or user_id. Keep each post’s at:// URI and is_repost flag when present. [Parameters and current cost →](https://www.monocrawl.com/docs/endpoints/bluesky/user/posts)



**bluesky/user/posts**

```
curl "https://www.monocrawl.com/v1/bluesky/user/posts?handle=bsky.app&limit=25" \
  -H "x-api-key: mn_your_key_here"
```



### 3. Inspect a post



Use a returned post URL or at:// post URI. The author can differ from the feed owner. [Parameters and current cost →](https://www.monocrawl.com/docs/endpoints/bluesky/post)



**bluesky/post**

```
curl "https://www.monocrawl.com/v1/bluesky/post?url=https%3A%2F%2Fbsky.app%2Fprofile%2Fespn.com%2Fpost%2F3lqdfq7fkvm2g" \
  -H "x-api-key: mn_your_key_here"
```



## Choose filters with the source behavior in mind



| Control | Behavior and limits |
| --- | --- |
| Identity | A handle can change; store the DID alongside it. Post IDs are at:// URIs, not decimal numbers. [Endpoint reference →](https://www.monocrawl.com/docs/endpoints/bluesky/profile) |
| Feed owner versus author | Supply handle or user_id. A repost preserves the original author and reports is_repost, so do not attribute every feed row to the owner. [Endpoint reference →](https://www.monocrawl.com/docs/endpoints/bluesky/user/posts) |
| Search ordering | sort is top or latest. Keep sort and query with the opaque cursor; ranking can change between requests. [Endpoint reference →](https://www.monocrawl.com/docs/endpoints/bluesky/search) |



Source availability, ordering and field coverage can change. Inspect warnings and partial-result metadata alongside the rows. See [runnable workflows](https://www.monocrawl.com/docs/workflows), [metric semantics](https://www.monocrawl.com/docs/metric-semantics), [computed fields](https://www.monocrawl.com/docs/computed-fields) and the [pagination matrix](https://www.monocrawl.com/docs/pagination).



## Match the operation to your task



| Your task | Endpoint | When to use it |
| --- | --- | --- |
| Keyword discovery | [`search`](https://www.monocrawl.com/docs/endpoints/bluesky/search) | Select latest or top and preserve the query and cursor. |
| Stable account identity | [`profile`](https://www.monocrawl.com/docs/endpoints/bluesky/profile) | A DID and a handle serve different purposes; preserve both. |



Explore all documented operations by purpose below. Each endpoint reference contains its accepted parameters and current price.



### Posts and media



- [`post`](https://www.monocrawl.com/docs/endpoints/bluesky/post)

- [`user/posts`](https://www.monocrawl.com/docs/endpoints/bluesky/user/posts)



### Accounts and audiences



- [`profile`](https://www.monocrawl.com/docs/endpoints/bluesky/profile)



### Search and discovery



- [`search`](https://www.monocrawl.com/docs/endpoints/bluesky/search)



## Endpoint reference

## bluesky/post

`GET /v1/bluesky/post`

Fetch a single Bluesky post from its bsky.app URL: text, author and like/repost/reply/quote counts.

*Bluesky post*

| Parameter | Required | Description |
| --- | --- | --- |
| `url` | yes | bsky.app post link or at:// post URI — e.g. `https://bsky.app/profile/espn.com/post/3lqdfq7fkvm2g` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `judgments` | no | Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable. — e.g. `on` |
| `label` | no | Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable. — e.g. `none` |
| `label_evidence` | no | Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `exclude` | no | Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable. — e.g. `engagement_bait` |
| `fit` | no | Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable. — e.g. `goal` |
| `goal` | no | Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts. — e.g. `Find concrete product complaints` |
| `tokens` | no | Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. — e.g. `4000` |

### Useful optional inputs

- `fit`: Use fit=goal with a task description to replace confidently irrelevant records with recall stubs and reduce agent context. No fit surcharge; full evidence is retained for 24 hours when stored, and the response size target is soft.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/bluesky/post?url=https%3A%2F%2Fbsky.app%2Fprofile%2Fespn.com%2Fpost%2F3lqdfq7fkvm2g" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "id": "at://did:plc:example/app.bsky.feed.post/example",
  "text": "Illustrative post",
  "likes": 3
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/bluesky/post#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/bluesky/post.json)


## bluesky/profile

`GET /v1/bluesky/profile`

Fetch a Bluesky profile by handle or DID: display name, bio, follower/following/post counts and avatar.

*Bluesky profile*

| Parameter | Required | Description |
| --- | --- | --- |
| `handle` | yes | Bluesky handle (e.g. alice.bsky.social) or DID — e.g. `bsky.app` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `judgments` | no | Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable. — e.g. `on` |
| `label` | no | Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable. — e.g. `none` |
| `label_evidence` | no | Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `exclude` | no | Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable. — e.g. `engagement_bait` |
| `fit` | no | Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable. — e.g. `goal` |
| `goal` | no | Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts. — e.g. `Find concrete product complaints` |
| `tokens` | no | Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. — e.g. `4000` |

### Useful optional inputs

- `fit`: Use fit=goal with a task description to replace confidently irrelevant records with recall stubs and reduce agent context. No fit surcharge; full evidence is retained for 24 hours when stored, and the response size target is soft.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/bluesky/profile?handle=bsky.app" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "id": "did:plc:example",
  "handle": "example.bsky.social",
  "followers": 12
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/bluesky/profile#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/bluesky/profile.json)


## bluesky/search

`GET /v1/bluesky/search`

Full-text search over public Bluesky posts with engagement counts.

*Bluesky post search*

| Parameter | Required | Description |
| --- | --- | --- |
| `query` | yes | Search text — e.g. `nextjs` |
| `limit` | no | Max results (1-100) — e.g. `25` |
| `sort` | no | top or latest Accepted values: top, latest. Case, spaces, hyphens and underscores are interchangeable. — e.g. `latest` |
| `cursor` | no | Continue a previous page |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `judgments` | no | Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable. — e.g. `on` |
| `label` | no | Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable. — e.g. `none` |
| `label_evidence` | no | Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `exclude` | no | Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable. — e.g. `engagement_bait` |
| `fit` | no | Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable. — e.g. `goal` |
| `goal` | no | Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts. — e.g. `Find concrete product complaints` |
| `tokens` | no | Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. — e.g. `4000` |

### Useful optional inputs

- `sort`: Choose the documented source ordering before paging through results. Ordering keeps the normal endpoint price and does not guarantee exhaustive results.
- `limit`: Bound the returned rows to what your task needs. A smaller limit does not necessarily reduce source calls or price; inspect the quote.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 3 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/bluesky/search?query=nextjs" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "items": [
    {
      "id": "at://did:plc:example/app.bsky.feed.post/example",
      "text": "Illustrative post",
      "author": {
        "id": "did:plc:example"
      },
      "is_repost": false
    }
  ],
  "cursor": null,
  "has_more": null
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/bluesky/search#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/bluesky/search.json)


## bluesky/user/posts

`GET /v1/bluesky/user/posts`

List a Bluesky account's posts (newest first) with like/repost/reply/quote counts; reposts are included and labeled is_repost.

*Bluesky user posts*

| Parameter | Required | Description |
| --- | --- | --- |
| `handle` | no | Bluesky handle (provide this or user_id) — e.g. `bsky.app` |
| `user_id` | no | Account DID (provide this or handle) — e.g. `did:plc:z72i7hdynmk6r22z27h6tvur` |
| `limit` | no | Posts per page, 1-100 (default 25) — e.g. `25` |
| `cursor` | no | Opaque cursor from a previous page |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `judgments` | no | Add bounded AI labels to eligible returned records (default on). off preserves the original data shape. Unclassified records remain present; labels depend on evidence, time, capacity and the existing request budget. No label surcharge. Accepted values: on, off. Case, spaces, hyphens and underscores are interchangeable. — e.g. `on` |
| `label` | no | Set none to disable labels; default enables the endpoint’s label set. Equivalent to judgments=off. Accepted values: default, none. Case, spaces, hyphens and underscores are interchangeable. — e.g. `none` |
| `label_evidence` | no | Include exact supporting sentences and zero-based sentence indexes when a label has validated evidence. No extra charge or change to decisions. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |
| `exclude` | no | Optionally remove confidently labelled engagement bait. Uncertain and unclassified records stay; removed IDs and an owner-bound recall reference are returned. Accepted values: engagement_bait. Case, spaces, hyphens and underscores are interchangeable. — e.g. `engagement_bait` |
| `fit` | no | Use goal to replace confidently irrelevant records with recall stubs. Keeps first, last, relevant and uncertain records; preserves order. Full evidence is stored for 24 hours when available. Accepted values: goal. Case, spaces, hyphens and underscores are interchangeable. — e.g. `goal` |
| `goal` | no | Required with fit=goal: describe the task in at most 600 characters. Supplied text is task context, never permission to act on posts. — e.g. `Find concrete product complaints` |
| `tokens` | no | Optional soft response target for fit=goal, 256–32000. Safety and evidence retention take priority, so the returned result may exceed it. — e.g. `4000` |

### Useful optional inputs

- `limit`: Bound the returned rows to what your task needs. A smaller limit does not necessarily reduce source calls or price; inspect the quote.
- `fit`: Use fit=goal with a task description to replace confidently irrelevant records with recall stubs and reduce agent context. No fit surcharge; full evidence is retained for 24 hours when stored, and the response size target is soft.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/bluesky/user/posts?handle=bsky.app" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "items": [
    {
      "id": "at://did:plc:example/app.bsky.feed.post/example",
      "text": "Illustrative post",
      "author": {
        "id": "did:plc:example"
      },
      "is_repost": false
    }
  ],
  "cursor": null,
  "has_more": null
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/bluesky/user/posts#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/bluesky/user/posts.json)