# Bluesky Followers Scraper (`fetch_cat/bluesky-followers-scraper`) Actor Export public Bluesky followers and following lists with profile metadata for audience research and social graph monitoring. - **URL**: https://apify.com/fetch\_cat/bluesky-followers-scraper.md - **Developed by:** [Hanna Nosova](https://apify.com/fetch_cat) (community) - **Categories:** Social media, Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $0.02 / 1,000 graph record extracteds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md). If your project is in a different language, use 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 Followers Scraper Export public Bluesky followers and following graph records from handles, profile URLs, or DIDs. Use it to map public audience relationships, build lead lists, monitor communities, and analyze account growth on Bluesky. ### What does Bluesky Followers Scraper do? Bluesky Followers Scraper collects public graph records from the Bluesky API. It can export: - Followers of a public Bluesky profile - Accounts a public Bluesky profile follows - Both followers and following records in one run - Profile metadata for each related account - Cursor metadata for auditability and resumable workflows The actor does not require Bluesky login cookies. ### Who is it for? This actor is useful for: - Social media analysts mapping public communities - Creator and agency teams researching audience overlap - Journalists studying public account networks - Developer-relations teams finding relevant builders - Growth teams building Bluesky prospect lists - Researchers tracking public social graph changes - Community managers exporting follower lists for enrichment ### Input recipes #### Export followers for one account ```json { "handles": ["bsky.app"], "mode": "followers", "maxItemsPerProfile": 20, "includeProfileDetails": true } ```` #### Export following records ```json { "handles": ["apify.com"], "mode": "following", "maxItemsPerProfile": 50, "includeProfileDetails": true } ``` #### Export both directions ```json { "handles": ["bsky.app", "apify.com"], "mode": "both", "maxItemsPerProfile": 100, "includeProfileDetails": true, "requestDelayMs": 150 } ``` ### Input fields | Field | Type | Description | | --- | --- | --- | | `handles` | array | Bluesky handles, profile URLs, or DIDs. | | `mode` | string | `followers`, `following`, or `both`. | | `maxItemsPerProfile` | integer | Maximum graph records per input profile and selected mode. | | `includeProfileDetails` | boolean | Include bio, avatar, counters, labels, and verification payloads. | | `sinceCursor` | string | Optional Bluesky cursor to resume one handle and one direction. | | `requestDelayMs` | integer | Delay between paginated graph requests. | | `maxRuntimeSeconds` | integer | Optional 60–270 second work cap that saves a cursor checkpoint before cutoff. | ### Output fields Each dataset item is one public graph relationship. | Field | Description | | --- | --- | | `sourceHandle` | Source account whose graph was exported. | | `sourceDid` | Source account DID. | | `mode` | Whether the row came from followers or following. | | `profileDid` | Related profile DID. | | `profileHandle` | Related profile handle. | | `displayName` | Public display name when available. | | `description` | Public profile bio when available. | | `avatarUrl` | Public avatar URL when available. | | `followersCount` | Related profile follower count. | | `followsCount` | Related profile following count. | | `postsCount` | Related profile post count. | | `createdAt` | Related profile creation timestamp when returned by Bluesky. | | `indexedAt` | Related profile index timestamp when returned by Bluesky. | | `verificationStatus` | Verification payload returned by Bluesky. | | `labels` | Public labels returned by Bluesky. | | `cursorPage` | Cursor used to request the page that produced the row. | | `scrapedAt` | Timestamp when the row was saved. | ### Example output ```json { "sourceHandle": "bsky.app", "sourceDid": "did:plc:z72i7hdynmk6r22z27h6tvur", "mode": "followers", "profileDid": "did:plc:example", "profileHandle": "example.bsky.social", "displayName": "Example User", "description": "Public Bluesky profile bio", "followersCount": 1200, "followsCount": 300, "postsCount": 450, "scrapedAt": "2026-07-12T00:00:00.000Z" } ``` ### API usage You can run the actor from the Apify Console, Apify API, Apify CLI, or the official clients. #### Node.js ```js import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: process.env.APIFY_TOKEN }); const run = await client.actor('fetch_cat/bluesky-followers-scraper').call({ handles: ['bsky.app'], mode: 'followers', maxItemsPerProfile: 20, }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); console.log(items); ``` #### Python ```python from apify_client import ApifyClient import os client = ApifyClient(os.environ['APIFY_TOKEN']) run = client.actor('fetch_cat/bluesky-followers-scraper').call(run_input={ 'handles': ['bsky.app'], 'mode': 'followers', 'maxItemsPerProfile': 20, }) items = client.dataset(run['defaultDatasetId']).list_items().items print(items) ``` #### cURL ```bash curl -X POST 'https://api.apify.com/v2/acts/fetch_cat~bluesky-followers-scraper/runs?token='$APIFY_TOKEN \ -H 'Content-Type: application/json' \ -d '{"handles":["bsky.app"],"mode":"followers","maxItemsPerProfile":20}' ``` ### MCP usage You can use this actor through the Apify MCP server from compatible AI tools. 1. Configure the Apify MCP server with your Apify API token. 2. Ask your AI tool to run `fetch_cat/bluesky-followers-scraper`. 3. Provide the same JSON input you would use in the Apify Console. 4. Use the returned dataset items in your analysis or workflow. Claude Desktop / Claude Code example: ```bash claude mcp add apify -- npx -y @apify/actors-mcp-server --actors fetch_cat/bluesky-followers-scraper ``` Generic MCP JSON configuration: ```json { "mcpServers": { "apify": { "command": "npx", "args": ["-y", "@apify/actors-mcp-server", "--actors", "fetch_cat/bluesky-followers-scraper"], "env": { "APIFY_TOKEN": "YOUR_APIFY_TOKEN" } } } } ``` Example prompt: > Run Bluesky Followers Scraper for `bsky.app`, collect 20 followers, and summarize common profile themes. ### Pricing This actor uses pay-per-event pricing on Apify. A start event is charged once per valid run, and the primary event is charged for each saved follower/following graph record. | Event | What is charged | Price | | --- | --- | --- | | Start | One valid Actor run | $0.005 | | Graph record extracted | Each saved public follower/following row | Free $0.00002762875; Bronze $0.000024025; Silver $0.0000187395; Gold $0.000014415; Platinum $0.00000961; Diamond $0.000006727 | At the Free tier, 1,000 saved graph records cost about $0.03, plus the run start event. Failed lookups and malformed records are not saved as graph records. To control costs: - Start with `maxItemsPerProfile` set to 20. - Use `followers` or `following` instead of `both` unless you need both directions. - Test one handle before adding larger batches. - Increase limits only after confirming the output shape suits your workflow. ### Data source The actor uses public Bluesky endpoints for public profiles and public graph pages. It only collects data returned by Bluesky for public accounts. ### Legality and responsible use You are responsible for using the exported data lawfully and in line with your use case. Avoid collecting unnecessary personal data, respect applicable privacy rules, and follow Bluesky and Apify terms. Do not use the actor for harassment, spam, or abusive targeting. ### Performance tips - Keep the default `requestDelayMs` for larger runs. - Split very large account lists into smaller runs. - Use `includeProfileDetails: false` when you only need handles and DIDs. - Use profile URLs only when convenient; handles and DIDs are simpler. - A run accepts up to 100 unique source profiles and up to 5,000 records per source and selected direction. - Large lists stop before the run timeout so saved rows and a checkpoint can be persisted. ### Reliable pagination and checkpoints The Actor follows Bluesky cursors, deduplicates profile DIDs within each source and direction, and stops on a repeated cursor instead of looping. It checks successful API responses for the expected graph shape and retries temporary API/network failures with bounded backoff. When a large run reaches its safe deadline, already saved rows remain available. Set `maxRuntimeSeconds` (60–270) when you want a predictable work cap; the Actor always uses the earlier of that cap and the platform timeout. `RUN_SUMMARY` records the result, warnings, and any source-level failures. If a graph page remains, `PENDING_WORK` records its source handle, DID, direction, cursor, and remaining limit. To resume, start a new run with that one source handle, the recorded direction, and the cursor in `sinceCursor`. ### Troubleshooting If a handle returns no records, verify that the account exists and is public. A valid public account can legitimately have an empty follower/following list. If every requested source is unavailable or rejected, the run fails and `RUN_SUMMARY` lists the source-level errors. If a run stops early, inspect `PENDING_WORK`, then resume the affected source and direction with its cursor. If Bluesky temporarily rate-limits requests, retry later with a delay. ### FAQ #### Do I need a Bluesky account? No. The actor collects public graph records and does not require login. #### Can I scrape private accounts? No. The actor only exports public data returned by Bluesky. #### Can I resume a run? Advanced users can pass a `sinceCursor` value from `PENDING_WORK` to resume one source and one direction. Most users should leave it empty. For `both`, resume followers and following in separate runs so the cursor cannot be applied to the wrong graph. #### Does it use a browser? No. It is an HTTP/API actor designed for low memory usage and fast runs. #### Can I export both followers and following? Yes. Set `mode` to `both`. Each selected direction can save up to `maxItemsPerProfile` records per source profile. #### What happens when one source profile fails in a batch? The Actor preserves successful public graph rows from other source profiles and records the failed source in `RUN_SUMMARY`. A batch fails rather than reporting a misleading empty success when every requested source fails. # Actor input Schema ## `handles` (type: `array`): Public Bluesky accounts to inspect. Examples: bsky.app, apify.com, https://bsky.app/profile/bsky.app, did:plc:z72i7hdynmk6r22z27h6tvur ## `mode` (type: `string`): Choose whether to export followers, accounts the profile follows, or both. ## `maxItemsPerProfile` (type: `integer`): Maximum followers/following records to save for each input profile and selected mode. ## `includeProfileDetails` (type: `boolean`): Include display name, bio, avatar, counters, labels, and verification details for each graph profile. ## `sinceCursor` (type: `string`): Optional Bluesky pagination cursor to resume one handle and one direction from a prior page. Leave empty for normal runs; run followers and following separately when resuming. ## `requestDelayMs` (type: `integer`): Optional delay between paginated API requests. Increase if you collect many records from many accounts. ## `maxRuntimeSeconds` (type: `integer`): Optional safety cap for this run. The Actor stops admitting new graph pages early enough to save progress; use 60–270 seconds. Leave empty to use the platform timeout. ## Actor input object example ```json { "handles": [ "bsky.app" ], "mode": "followers", "maxItemsPerProfile": 20, "includeProfileDetails": true, "requestDelayMs": 150 } ``` # Actor output Schema ## `overview` (type: `string`): No description ## `runSummary` (type: `string`): No description ## `pendingWork` (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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "handles": [ "bsky.app" ] }; // Run the Actor and wait for it to finish const run = await client.actor("fetch_cat/bluesky-followers-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "handles": ["bsky.app"] } # Run the Actor and wait for it to finish run = client.actor("fetch_cat/bluesky-followers-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "handles": [ "bsky.app" ] }' | apify call fetch_cat/bluesky-followers-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=fetch_cat/bluesky-followers-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Bluesky Followers Scraper", "description": "Export public Bluesky followers and following lists with profile metadata for audience research and social graph monitoring.", "version": "0.1", "x-build-id": "cNpAo0E384QfBTJke" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/fetch_cat~bluesky-followers-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-fetch_cat-bluesky-followers-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/fetch_cat~bluesky-followers-scraper/runs": { "post": { "operationId": "runs-sync-fetch_cat-bluesky-followers-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/fetch_cat~bluesky-followers-scraper/run-sync": { "post": { "operationId": "run-sync-fetch_cat-bluesky-followers-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "handles" ], "properties": { "handles": { "title": "Handles, profile URLs, or DIDs", "type": "array", "description": "Public Bluesky accounts to inspect. Examples: bsky.app, apify.com, https://bsky.app/profile/bsky.app, did:plc:z72i7hdynmk6r22z27h6tvur", "items": { "type": "string" } }, "mode": { "title": "Graph mode", "enum": [ "followers", "following", "both" ], "type": "string", "description": "Choose whether to export followers, accounts the profile follows, or both.", "default": "followers" }, "maxItemsPerProfile": { "title": "Maximum graph records per profile and mode", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Maximum followers/following records to save for each input profile and selected mode.", "default": 20 }, "includeProfileDetails": { "title": "Include profile details", "type": "boolean", "description": "Include display name, bio, avatar, counters, labels, and verification details for each graph profile.", "default": true }, "sinceCursor": { "title": "Start cursor", "type": "string", "description": "Optional Bluesky pagination cursor to resume one handle and one direction from a prior page. Leave empty for normal runs; run followers and following separately when resuming." }, "requestDelayMs": { "title": "Delay between graph pages (ms)", "minimum": 0, "maximum": 5000, "type": "integer", "description": "Optional delay between paginated API requests. Increase if you collect many records from many accounts.", "default": 150 }, "maxRuntimeSeconds": { "title": "Maximum active work time (seconds)", "minimum": 60, "maximum": 270, "type": "integer", "description": "Optional safety cap for this run. The Actor stops admitting new graph pages early enough to save progress; use 60–270 seconds. Leave empty to use the platform timeout." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```