# Bluesky Scraper - Posts, Profiles, Threads & Followers (`actorpilot/bluesky-scraper`) Actor

Extract public Bluesky posts, profiles, author feeds, threads, followers, follows, and custom feeds via the AT Protocol API. No login, no browser, no proxies. Includes stable IDs, hashes, timestamps, and run summaries for monitoring.

- **URL**: https://apify.com/actorpilot/bluesky-scraper.md
- **Developed by:** [S. Klein](https://apify.com/actorpilot) (community)
- **Categories:** Social media, Lead generation
- **Stats:** 3 total users, 2 monthly users, 78.9% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Bluesky Scraper - Posts, Profiles, Threads & Followers

Extract public Bluesky and AT Protocol data without a browser, proxy, cookie, or login.

This Actor uses the public Bluesky AppView XRPC API (`api.bsky.app`) and saves clean JSON/CSV-ready records for posts, profiles, author feeds, reply threads, followers, follows, and custom feeds. Every saved row includes stable IDs, a record hash, a scrape timestamp, and source metadata. Each run also writes a `RUN_SUMMARY` record to the key-value store.

### Use Cases

- Social listening and brand monitoring on Bluesky.
- Research datasets for posts, threads, hashtags, and mentions.
- Profile and audience analysis for journalists, agencies, and creators.
- Lead discovery from followers/following lists.
- Daily scheduled monitoring with dedupe by `recordId` or `recordHash`.
- AI/LLM workflows that need structured AT Protocol data.

### Modes

| Mode | What it collects | Best for |
|---|---|---|
| `profile` | Profile details for one or more handles | Fast health checks, profile enrichment |
| `searchPosts` | Posts matching a keyword, phrase, or hashtag | Social listening and trend monitoring |
| `authorFeed` | Posts from one or more accounts | Creator/account analysis |
| `postThread` | A post and nested replies | Conversation analysis |
| `followers` | Accounts following a handle | Audience research |
| `follows` | Accounts followed by a handle | Network mapping |
| `customFeed` | Posts from a public feed generator | Topic/feed monitoring |

The default input runs a tiny `profile` lookup for `bsky.app`. This is intentional: it gives Apify Store health checks a quick, reliable, low-cost run.

### Input

| Field | Type | Default | Description |
|---|---:|---:|---|
| `mode` | string | `profile` | One of `profile`, `searchPosts`, `authorFeed`, `postThread`, `followers`, `follows`, `customFeed` |
| `handles` | string array | `["bsky.app"]` | Handles without `@`, used by profile/feed/follower modes |
| `searchQuery` | string | `bluesky` | Keyword, phrase, hashtag, or Bluesky search syntax |
| `searchSort` | string | `latest` | `latest` or `top` |
| `searchSince` | string | empty | Optional start date, `YYYY-MM-DD` |
| `searchUntil` | string | empty | Optional end date, `YYYY-MM-DD` |
| `searchLang` | string | empty | Optional two-letter language code |
| `postUrl` | string | empty | Public bsky.app post URL or AT URI |
| `feedUri` | string | empty | Public feed generator AT URI |
| `maxItems` | integer | `10` | Maximum posts/profiles to save, 1 to 10000 |
| `includeReplies` | boolean | `false` | Include replies in `authorFeed` mode |
| `includeReposts` | boolean | `false` | Include reposts in `authorFeed` mode |
| `maxRetries` | integer | `3` | Retries for 429, 5xx, and timeout errors |
| `requestTimeoutSecs` | integer | `30` | Per-request timeout |
| `testMode` | boolean | `false` | Forces a tiny `bsky.app` profile lookup |

#### Default Example

```json
{}
```

#### Search Posts

```json
{
  "mode": "searchPosts",
  "searchQuery": "bluesky lang:en",
  "searchSort": "latest",
  "maxItems": 25
}
```

#### Profile And Audience Analysis

```json
{
  "mode": "followers",
  "handles": ["bsky.app"],
  "maxItems": 100
}
```

#### Thread Export

```json
{
  "mode": "postThread",
  "postUrl": "https://bsky.app/profile/pfrazee.com/post/3mnsxzydov22d",
  "maxItems": 100
}
```

### Output

Post records include:

- `recordType`, `recordId`, `recordHash`, `scrapedAt`, `source`, `scrapedMode`
- `postId`, `url`, `text`
- `authorHandle`, `authorDid`, `authorDisplayName`
- `likeCount`, `repostCount`, `replyCount`, `quoteCount`
- `createdAt`, `indexedAt`, `lang`
- `tags`, `mentionedDids`
- `hasMedia`, `mediaUrls`, `mediaAltTexts`
- reply and external-link metadata where available

Profile records include:

- `recordType`, `recordId`, `recordHash`, `scrapedAt`, `source`, `scrapedMode`
- `did`, `handle`, `displayName`, `description`
- `followerCount`, `followingCount`, `postCount`
- `avatarUrl`, `bannerUrl`, `createdAt`, `indexedAt`, `labels`

`RUN_SUMMARY` includes:

- `status`: `SUCCEEDED`, `NO_RESULTS`, or `FAILED`
- `mode`, `requested_items`, `saved_items`, `test_mode`
- `warnings`, `errors`, `dataset_fields_version`

### Example Output

```json
{
  "recordType": "profile",
  "recordId": "did:plc:z72i7hdynmk6r22z27h6tvur",
  "recordHash": "f0f0a9e2c1...",
  "scrapedAt": "2026-07-03T13:30:00.000Z",
  "source": "bluesky",
  "did": "did:plc:z72i7hdynmk6r22z27h6tvur",
  "handle": "bsky.app",
  "displayName": "Bluesky",
  "description": "Official Bluesky account",
  "followerCount": 1000000,
  "followingCount": 4,
  "postCount": 1000,
  "avatarUrl": "https://cdn.bsky.app/...",
  "bannerUrl": "https://cdn.bsky.app/...",
  "createdAt": "2023-04-12T04:53:57.057Z",
  "indexedAt": "2026-07-03T12:00:00.000Z",
  "labels": null,
  "scrapedMode": "profile"
}
```

### Scheduling And Automation

For daily monitoring:

1. Use a small `maxItems` value.
2. Schedule the Actor on Apify.
3. Dedupe by `recordId`.
4. Compare `recordHash` to detect changed profile/post metadata.
5. Read `RUN_SUMMARY` from the key-value store for alerting.

API example:

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/actorpilot~bluesky-scraper/runs" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode":"searchPosts","searchQuery":"bluesky lang:en","maxItems":25}'
```

### Limits And Notes

- Only public Bluesky data is returned.
- No private accounts, blocked content, or login-only data is accessed.
- Some Bluesky search behavior can change because it is controlled by the public AppView API.
- Very broad searches or large follower lists can take longer and cost more.
- Search results may return lighter author objects than profile/feed modes.
- `NO_RESULTS` means the source was reachable but the query/filter returned no items.
- True input or source failures still fail the run and write `RUN_SUMMARY.errors`.

### Why This Actor Instead Of Generic Social Scrapers?

- It uses the official public AT Protocol API instead of browser scraping.
- It includes stable AT URI/DID identifiers for reliable dedupe.
- It writes run summaries for scheduled automation.
- It supports profiles, posts, threads, followers, follows, and feeds in one Actor.
- It is designed for low-cost recurring runs, not heavyweight browser sessions.

# Actor input Schema

## `mode` (type: `string`):

Choose what public Bluesky data to collect.

## `searchQuery` (type: `string`):

Keyword, phrase, hashtag, or Bluesky search syntax. Example: bluesky lang:en

## `searchSort` (type: `string`):

Sort search results by latest or top.

## `searchSince` (type: `string`):

Only return posts on or after this date. Format: YYYY-MM-DD. Leave empty for no lower date limit.

## `searchUntil` (type: `string`):

Only return posts on or before this date. Format: YYYY-MM-DD. Leave empty for no upper date limit.

## `searchLang` (type: `string`):

Optional ISO 639-1 language code such as en, de, fr, es, or ja.

## `handles` (type: `array`):

Bluesky handles without @. Examples: bsky.app, atproto.com, nytimes.com.

## `includeReplies` (type: `boolean`):

Also collect reply posts in authorFeed mode.

## `includeReposts` (type: `boolean`):

Also collect reposts in authorFeed mode.

## `postUrl` (type: `string`):

A public bsky.app post URL or an at:// post URI.

## `feedUri` (type: `string`):

AT URI of a public Bluesky feed generator.

## `maxItems` (type: `integer`):

Maximum posts or profiles to save. Use a small value for scheduled monitoring and tests.

## `maxRetries` (type: `integer`):

Retries for temporary AT Protocol API failures such as 429, 5xx, or timeouts.

## `requestTimeoutSecs` (type: `integer`):

Timeout in seconds for each AT Protocol API request.

## `testMode` (type: `boolean`):

Use a tiny profile lookup for Apify health checks.

## Actor input object example

```json
{
  "mode": "profile",
  "searchQuery": "bluesky",
  "searchSort": "latest",
  "searchLang": "",
  "handles": [
    "bsky.app"
  ],
  "includeReplies": false,
  "includeReposts": false,
  "postUrl": "https://bsky.app/profile/pfrazee.com/post/3mnsxzydov22d",
  "feedUri": "at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.generator/whats-hot",
  "maxItems": 10,
  "maxRetries": 3,
  "requestTimeoutSecs": 30,
  "testMode": false
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `runSummary` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "profile",
    "searchQuery": "bluesky",
    "handles": [
        "bsky.app"
    ],
    "postUrl": "https://bsky.app/profile/pfrazee.com/post/3mnsxzydov22d",
    "feedUri": "at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.generator/whats-hot",
    "maxItems": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("actorpilot/bluesky-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "profile",
    "searchQuery": "bluesky",
    "handles": ["bsky.app"],
    "postUrl": "https://bsky.app/profile/pfrazee.com/post/3mnsxzydov22d",
    "feedUri": "at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.generator/whats-hot",
    "maxItems": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("actorpilot/bluesky-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "profile",
  "searchQuery": "bluesky",
  "handles": [
    "bsky.app"
  ],
  "postUrl": "https://bsky.app/profile/pfrazee.com/post/3mnsxzydov22d",
  "feedUri": "at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.generator/whats-hot",
  "maxItems": 10
}' |
apify call actorpilot/bluesky-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,actorpilot/bluesky-scraper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/DGAVpCx6fSPKBg09P/builds/jUj30fUDYA0er4iA6/openapi.json