# Bluesky Post Search Scraper (`khadinakbar/search-bluesky-posts`) Actor Search public Bluesky posts by keyword, author, date, language, hashtag, mention, domain, or URL. Use for monitoring and research; not profiles, followers, feeds, or private data. Returns post text, author, time, engagement, media, and URL. 0.0035 USD/post + 0.00005 USD start; usage extra. - **URL**: https://apify.com/khadinakbar/search-bluesky-posts.md - **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community) - **Categories:** Social media, AI, MCP servers - **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $3.50 / 1,000 bluesky post scrapeds This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## 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. 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 Post Search Scraper Search public Bluesky posts by keyword or phrase and export one structured post per dataset row. This Actor is built for brand monitoring, journalism, market research, social listening, and AI-agent workflows that need current post text, author identity, timestamps, engagement metrics, media, hashtags, mentions, and source URLs. Use it when you need Bluesky's search index with optional author, date, language, hashtag, mention, linked-domain, or linked-URL filters. Do not use it for full user feeds, profiles, follower graphs, private data, or complete conversation threads. ### What data does it return? | Field group | Included fields | |---|---| | Post | `postUri`, `postCid`, `postUrl`, `text`, `createdAt`, `indexedAt` | | Author | `authorDid`, `authorHandle`, `authorDisplayName`, `authorAvatarUrl` | | Engagement | `likeCount`, `repostCount`, `replyCount`, `quoteCount`, `engagementCount` | | Conversation | `isReply`, `replyRootUri`, `replyParentUri`, `quotedPostUri` | | Rich text | `langs`, `links`, `mentionedDids`, `tags`, `labels` | | Media | `imageUrls`, `imageAltTexts`, video URLs, external link-card fields | | Provenance | `searchQuery`, `sort`, `rank`, `collectedAt`, `sourceEndpoint` | Every optional field has a stable explicit `null` or empty-array value, making rows consistent for CSV exports, databases, and agents. `OUTPUT` and `RUN_SUMMARY` are also written on every terminal path. ### Pricing This Actor uses **Pay per event + usage**: | Event | Price | |---|---:| | Actor start | $0.00005 per run, scaled by memory | | Bluesky post scraped | $0.0035 per persisted post | | Apify platform usage | Added separately by Apify | A 100-post run has at most **$0.35005 in Actor event charges**, plus Apify platform usage. Invalid input and valid-empty searches do not create per-post charges. A charge cap can stop persistence safely, and the final summaries disclose the actual post-event count. ### Input The only required field is `searchQuery`. ```json { "searchQuery": "open source", "sort": "latest", "maxResults": 100, "since": "2026-07-01", "until": "2026-07-15", "lang": "en", "author": "", "mentions": "", "domain": "github.com", "url": "", "tags": ["opensource"], "includeReplies": true } ```` Bluesky defines the query field but leaves exact phrase, boolean, and faceting syntax implementation-specific; Lucene-style syntax is recommended by the AT Protocol lexicon. If Bluesky rejects a query, the Actor returns `INVALID_INPUT` with a simpler working example. #### Important filter behavior - `since` is inclusive; `until` is exclusive. - Date filtering follows Bluesky's search timestamp, which may differ from a post's `createdAt`. - Multiple `tags` use AND matching and should not include `#`. - `mentions` matches structured rich-text mentions, not text that only resembles a handle. - `includeReplies: false` removes reply records after Bluesky returns the search page. - `maxResults` is capped at 100 because Bluesky's public search route currently rejects cursor continuation. Split larger research jobs with date, author, language, hashtag, or domain filters. ### Output example ```json { "searchQuery": "open source", "sort": "latest", "rank": 1, "postUri": "at://did:plc:example/app.bsky.feed.post/3abc", "postCid": "bafyreiexample", "postUrl": "https://bsky.app/profile/alice.bsky.social/post/3abc", "text": "A new open-source release is available today.", "authorDid": "did:plc:example", "authorHandle": "alice.bsky.social", "authorDisplayName": "Alice", "authorAvatarUrl": null, "createdAt": "2026-07-15T10:00:00.000Z", "indexedAt": "2026-07-15T10:00:01.000Z", "langs": ["en"], "likeCount": 42, "repostCount": 7, "replyCount": 5, "quoteCount": 2, "engagementCount": 56, "isReply": false, "replyRootUri": null, "replyParentUri": null, "links": ["https://example.com/release"], "mentionedDids": [], "tags": ["opensource"], "labels": [], "imageUrls": [], "imageAltTexts": [], "videoPlaylistUrl": null, "videoThumbnailUrl": null, "externalUrl": "https://example.com/release", "externalTitle": "Release notes", "externalDescription": "What's new in this version.", "externalThumbUrl": null, "quotedPostUri": null, "collectedAt": "2026-07-15T11:00:00.000Z", "sourceEndpoint": "https://api.bsky.app/xrpc/app.bsky.feed.searchPosts", "_note": null } ``` ### Run outcomes | Outcome | Run status | Meaning | |---|---|---| | `COMPLETE` | Succeeded | Search finished and all valid rows were persisted | | `PARTIAL` | Succeeded | Useful rows were saved before a charge cap or later failure | | `VALID_EMPTY` | Succeeded | Valid search completed with no matching posts | | `INVALID_INPUT` | Succeeded | Change the input using the actionable message | | `UPSTREAM_FAILED` | Failed | Both configured Bluesky AppView routes failed with no useful rows | | `CONFIG_ERROR` | Failed | Deployment, schema, or storage behavior prevented useful output | ### API Keep the Apify token in the Authorization header, never in a URL: ```bash curl -X POST \ 'https://api.apify.com/v2/acts/khadinakbar~search-bluesky-posts/runs?waitForFinish=300' \ -H "Authorization: Bearer $APIFY_TOKEN" \ -H 'Content-Type: application/json' \ -d '{"searchQuery":"open source","maxResults":25,"sort":"latest"}' ``` ### CLI ```bash apify call khadinakbar/search-bluesky-posts \ --input='{"searchQuery":"open source","maxResults":25,"sort":"latest"}' ``` ### MCP and AI agents Expose the Actor through Apify's hosted MCP server and call it with a focused query plus a bounded `maxResults`. The declared dataset schema gives agents stable post-level fields; use `get-actor-output` with the returned dataset ID to read or paginate the stored rows. ### Reliability and limitations - Source: Bluesky's public `app.bsky.feed.searchPosts` AppView XRPC endpoint at `api.bsky.app`. - Authentication: none for the current `api.bsky.app` public read route. - Fallback: a second Bluesky-hosted public AppView hostname is attempted after bounded retries; third-party provider routes are not used because they do not currently offer equivalent Bluesky post search. - Search coverage, ranking, and hit counts are controlled by Bluesky. `hitsTotal` may be rounded or truncated. Public cursor requests currently return HTTP 403, so one run returns at most the first 100 matches; use narrower filters for additional coverage. - Deleted, blocked, labeled, or unindexed content may be absent. Engagement counts are point-in-time observations. - The Actor searches public posts only and does not bypass privacy controls, moderation, or access restrictions. ### Legal and responsible use Use public Bluesky data in accordance with applicable law, the AT Protocol and Bluesky terms, and your own privacy and research obligations. Do not use this Actor for harassment, unlawful surveillance, discrimination, or attempts to identify private individuals. You are responsible for how collected data is stored, combined, and used. # Actor input Schema ## `searchQuery` (type: `string`): Use this when you need posts matching text, a phrase, or supported Lucene-style syntax. Enter a focused query such as 'open source' or '"climate change"'. The field is required and accepts up to 500 characters. This is not a profile handle or Bluesky post URL. ## `sort` (type: `string`): Use this when choosing how Bluesky ranks matching posts. Choose 'latest' for newest indexed posts or 'top' for relevance-ranked results. Defaults to 'latest'. This does not sort the finished dataset locally. ## `maxResults` (type: `integer`): Use this when bounding dataset size and per-post charges. Enter an integer from 1 to 100, such as 100. Defaults to 100 and the Console prefill is 25. Bluesky's public search route currently supports one page per query. ## `since` (type: `string`): Use this when restricting results to posts indexed at or after a date. Enter YYYY-MM-DD or an ISO 8601 timestamp, such as '2026-07-01'. Defaults to no lower date bound. This filter uses Bluesky search time and may differ from the post's createdAt value. ## `until` (type: `string`): Use this when restricting results to posts before a date. Enter YYYY-MM-DD or an ISO 8601 timestamp, such as '2026-07-15'. Defaults to no upper date bound and is exclusive. This must be later than Posts since. ## `lang` (type: `string`): Use this when you need posts tagged with one language. Enter a BCP 47 tag such as 'en', 'ja', or 'pt-BR'. Defaults to all languages. This is not a country or proxy location. ## `author` (type: `string`): Use this when limiting search to posts from one public Bluesky account. Enter a handle or DID such as 'jay.bsky.team'; a leading @ is accepted. Defaults to any author. This does not scrape a user's full feed or profile. ## `mentions` (type: `string`): Use this when finding posts that mention one Bluesky account through a rich-text mention facet. Enter a handle or DID such as 'bsky.app'; a leading @ is accepted. Defaults to any mention. Plain text that only resembles a handle may not match. ## `domain` (type: `string`): Use this when finding posts whose facets or embeds link to a hostname. Enter a domain such as 'github.com'; a full https URL is normalized to its hostname. Defaults to any linked domain. This is not a keyword search within page contents. ## `url` (type: `string`): Use this when finding posts that link to one absolute web URL. Enter an http or https URL such as 'https://example.com/report'. Defaults to any linked URL. This is not the URL of a Bluesky post to fetch directly. ## `tags` (type: `array`): Use this when posts must contain specific hashtags. Enter up to 10 tags without #, such as \['ai', 'opensource']; multiple tags use AND matching. Defaults to no hashtag filter. These are structured hashtag facets, not free-text keywords. ## `includeReplies` (type: `boolean`): Use this when deciding whether reply posts may appear in the dataset. Set false to drop posts containing Bluesky reply metadata after search. Defaults to true. This does not fetch complete reply threads. ## Actor input object example ```json { "searchQuery": "open source", "sort": "latest", "maxResults": 100, "since": "2026-07-01", "until": "2026-07-15", "lang": "en", "author": "jay.bsky.team", "mentions": "bsky.app", "domain": "github.com", "url": "https://example.com/report", "tags": [ "ai", "opensource" ], "includeReplies": true } ``` # Actor output Schema ## `results` (type: `string`): Search-matched posts with text, authors, timestamps, engagement, media, facets, and source URLs. ## `output` (type: `string`): Compact machine-readable run result with outcome, counts, warnings, and truncation state. ## `runSummary` (type: `string`): Detailed diagnostics including API attempts, filters, persisted rows, charges, and errors. # 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 = { "searchQuery": "artificial intelligence", "maxResults": 25 }; // Run the Actor and wait for it to finish const run = await client.actor("khadinakbar/search-bluesky-posts").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 = { "searchQuery": "artificial intelligence", "maxResults": 25, } # Run the Actor and wait for it to finish run = client.actor("khadinakbar/search-bluesky-posts").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 '{ "searchQuery": "artificial intelligence", "maxResults": 25 }' | apify call khadinakbar/search-bluesky-posts --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=khadinakbar/search-bluesky-posts", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Bluesky Post Search Scraper", "description": "Search public Bluesky posts by keyword, author, date, language, hashtag, mention, domain, or URL. Use for monitoring and research; not profiles, followers, feeds, or private data. Returns post text, author, time, engagement, media, and URL. 0.0035 USD/post + 0.00005 USD start; usage extra.", "version": "1.0", "x-build-id": "vSPbfTLGj4ytvZsrA" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/khadinakbar~search-bluesky-posts/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-khadinakbar-search-bluesky-posts", "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/khadinakbar~search-bluesky-posts/runs": { "post": { "operationId": "runs-sync-khadinakbar-search-bluesky-posts", "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/khadinakbar~search-bluesky-posts/run-sync": { "post": { "operationId": "run-sync-khadinakbar-search-bluesky-posts", "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": [ "searchQuery" ], "properties": { "searchQuery": { "title": "Post search query", "type": "string", "description": "Use this when you need posts matching text, a phrase, or supported Lucene-style syntax. Enter a focused query such as 'open source' or '\"climate change\"'. The field is required and accepts up to 500 characters. This is not a profile handle or Bluesky post URL." }, "sort": { "title": "Result order", "enum": [ "latest", "top" ], "type": "string", "description": "Use this when choosing how Bluesky ranks matching posts. Choose 'latest' for newest indexed posts or 'top' for relevance-ranked results. Defaults to 'latest'. This does not sort the finished dataset locally.", "default": "latest" }, "maxResults": { "title": "Maximum posts", "minimum": 1, "maximum": 100, "type": "integer", "description": "Use this when bounding dataset size and per-post charges. Enter an integer from 1 to 100, such as 100. Defaults to 100 and the Console prefill is 25. Bluesky's public search route currently supports one page per query.", "default": 100 }, "since": { "title": "Posts since", "type": "string", "description": "Use this when restricting results to posts indexed at or after a date. Enter YYYY-MM-DD or an ISO 8601 timestamp, such as '2026-07-01'. Defaults to no lower date bound. This filter uses Bluesky search time and may differ from the post's createdAt value.", "default": "" }, "until": { "title": "Posts until", "type": "string", "description": "Use this when restricting results to posts before a date. Enter YYYY-MM-DD or an ISO 8601 timestamp, such as '2026-07-15'. Defaults to no upper date bound and is exclusive. This must be later than Posts since.", "default": "" }, "lang": { "title": "Post language", "type": "string", "description": "Use this when you need posts tagged with one language. Enter a BCP 47 tag such as 'en', 'ja', or 'pt-BR'. Defaults to all languages. This is not a country or proxy location.", "default": "" }, "author": { "title": "Author handle or DID", "type": "string", "description": "Use this when limiting search to posts from one public Bluesky account. Enter a handle or DID such as 'jay.bsky.team'; a leading @ is accepted. Defaults to any author. This does not scrape a user's full feed or profile.", "default": "" }, "mentions": { "title": "Mentioned account", "type": "string", "description": "Use this when finding posts that mention one Bluesky account through a rich-text mention facet. Enter a handle or DID such as 'bsky.app'; a leading @ is accepted. Defaults to any mention. Plain text that only resembles a handle may not match.", "default": "" }, "domain": { "title": "Linked domain", "type": "string", "description": "Use this when finding posts whose facets or embeds link to a hostname. Enter a domain such as 'github.com'; a full https URL is normalized to its hostname. Defaults to any linked domain. This is not a keyword search within page contents.", "default": "" }, "url": { "title": "Linked URL", "type": "string", "description": "Use this when finding posts that link to one absolute web URL. Enter an http or https URL such as 'https://example.com/report'. Defaults to any linked URL. This is not the URL of a Bluesky post to fetch directly.", "default": "" }, "tags": { "title": "Hashtags", "maxItems": 10, "type": "array", "description": "Use this when posts must contain specific hashtags. Enter up to 10 tags without #, such as ['ai', 'opensource']; multiple tags use AND matching. Defaults to no hashtag filter. These are structured hashtag facets, not free-text keywords.", "items": { "type": "string" }, "default": [] }, "includeReplies": { "title": "Include replies", "type": "boolean", "description": "Use this when deciding whether reply posts may appear in the dataset. Set false to drop posts containing Bluesky reply metadata after search. Defaults to true. This does not fetch complete reply threads.", "default": true } } }, "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 } } } } } } } } } } ```