# 🦋 Bluesky Threads Monitor (`taroyamada/bluesky-threads-monitor`) Actor

Track public Bluesky conversations, trending posts, and profile metrics using unauthenticated AT Protocol XRPC endpoints to gather insights on social sentiment.

- **URL**: https://apify.com/taroyamada/bluesky-threads-monitor.md
- **Developed by:** [太郎 山田](https://apify.com/taroyamada) (community)
- **Categories:** Social media, Marketing
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, NaN 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/platform/actors/running/actors-in-store#pay-per-usage

## 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.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.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/platform/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 Threads Monitor

Track and extract data from Bluesky profiles, conversation threads, and keyword searches with lightning speed. As the AT Protocol ecosystem grows, gathering insights from the decentralized social web has become critical for marketers, researchers, and community managers. This monitor leverages Bluesky's public XRPC endpoints to pull comprehensive social data directly from the public appview, bypassing the need for complex API keys, rate-limit tokens, or authenticated sessions.

Whether you need to schedule weekly brand mentions reports or run daily checks on industry-specific conversations, this tool provides a seamless extraction pipeline. Users typically deploy this monitor to capture author handles, exact timestamps, and full post text alongside vital engagement signals like reply counts, reposts, and likes.

By targeting specific user feeds or broader search results, you can map out entire thread hierarchies and track viral content as it spreads across the network. The output includes highly structured details such as the post URI, content identifiers (CIDs), embedded media hints, and follower metrics. This rich dataset enables teams to build custom analytics dashboards, perform sentiment analysis on emerging trends, or archive vital public discourse without relying on restrictive, authenticated timelines.

### Status

Scaffolded as part of **Wave 17 Batch S — Tier 3 (strategic / emerging platforms + governance)**. Domain logic lives in `src/workflow.js`.

### Feasibility

**Very high — Bluesky exposes all public posts, profiles, and search via the unauthenticated AT Protocol XRPC layer at public.api.bsky.app. No login, no API key, no rate-limit token required.**

### V1 scope

Public AT Protocol appview (public.api.bsky.app) only. Per post: URI, CID, author handle, text, created-at, like/repost/reply counts, embedded media hints. OUT OF SCOPE: authenticated timelines, direct messages, private lists, moderation reports, custom feed creation.

### Extraction surfaces

- Author feed: https://public.api.bsky.app/xrpc/app.bsky.feed.getAuthorFeed?actor={handle}
- Profile: https://public.api.bsky.app/xrpc/app.bsky.actor.getProfile?actor={handle}
- Search posts: https://public.api.bsky.app/xrpc/app.bsky.feed.searchPosts?q={query}
- Thread: https://public.api.bsky.app/xrpc/app.bsky.feed.getPostThread?uri={uri}

### Known limitations and explicit warnings

- AT Protocol is still pre-1.0; endpoint shapes may evolve and parsers are best-effort.
- Public XRPC responses page at 50-100 items — large handles require cursor pagination.
- Like and repost COUNTS are returned on the post view; the LIST of likers/reposters requires authenticated endpoints and is out of V1 scope.
- Search is approximate — not a full-text index; recent posts are favored.
- Deleted posts disappear from the feed but leave holes in thread replies; the actor emits a placeholder when a reply parent is unreachable.
- Custom feed generators and private lists require authentication — out of V1 scope.
- Rate limits on the public appview are not published; polite pacing (≥250ms per request) is enforced.
- Embedded video bytes are not downloaded — only the embed URL is surfaced.
- DID resolution is trusted from the appview response; independent PLC-directory validation is not performed in V1.
- Quote posts are surfaced as a nested embed, not flattened into the parent text.

### Input

- Bluesky handles / search terms
- Delivery mode (dataset or webhook)
- Dry-run support for local validation

### Output

- Normalized `posts` array
- `meta` section with implementation status, feasibility note, V1 scope, warnings, and notes

### Local run

```bash
npm test
npm start
````

### ⭐ Was this helpful?

If this actor saved you time, please [**leave a ★ rating**](https://apify.com/taroyamada/bluesky-threads-monitor/reviews) on Apify Store. It takes 10 seconds, helps other developers discover it, and keeps updates free.

Bug report or feature request? Open an issue on the [Issues tab](https://apify.com/taroyamada/bluesky-threads-monitor/issues) of this actor.

# Actor input Schema

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

Handles (e.g. 'jay.bsky.social', 'bsky.app'). Leave empty to use searchQueries only.

## `searchQueries` (type: `array`):

Text queries to search across public Bluesky posts.

## `maxPostsPerSource` (type: `integer`):

Cap on the number of posts returned per handle / query.

## `delivery` (type: `string`):

Where to send results: dataset or webhook.

## `webhookUrl` (type: `string`):

Webhook URL to POST results to when delivery=webhook.

## `dryRun` (type: `boolean`):

Run without saving results to the dataset.

## Actor input object example

```json
{
  "handles": [
    "bsky.app"
  ],
  "searchQueries": [],
  "maxPostsPerSource": 50,
  "delivery": "dataset",
  "dryRun": false
}
```

# 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 = {
    "handles": [
        "bsky.app"
    ],
    "searchQueries": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("taroyamada/bluesky-threads-monitor").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 = {
    "handles": ["bsky.app"],
    "searchQueries": [],
}

# Run the Actor and wait for it to finish
run = client.actor("taroyamada/bluesky-threads-monitor").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"
  ],
  "searchQueries": []
}' |
apify call taroyamada/bluesky-threads-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=taroyamada/bluesky-threads-monitor",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "🦋 Bluesky Threads Monitor",
        "description": "Track public Bluesky conversations, trending posts, and profile metrics using unauthenticated AT Protocol XRPC endpoints to gather insights on social sentiment.",
        "version": "0.1",
        "x-build-id": "oyaBkDTF1DrqpSuBD"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/taroyamada~bluesky-threads-monitor/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-taroyamada-bluesky-threads-monitor",
                "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/taroyamada~bluesky-threads-monitor/runs": {
            "post": {
                "operationId": "runs-sync-taroyamada-bluesky-threads-monitor",
                "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/taroyamada~bluesky-threads-monitor/run-sync": {
            "post": {
                "operationId": "run-sync-taroyamada-bluesky-threads-monitor",
                "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",
                "properties": {
                    "handles": {
                        "title": "Bluesky Handles",
                        "type": "array",
                        "description": "Handles (e.g. 'jay.bsky.social', 'bsky.app'). Leave empty to use searchQueries only.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "searchQueries": {
                        "title": "Search Queries",
                        "type": "array",
                        "description": "Text queries to search across public Bluesky posts.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "maxPostsPerSource": {
                        "title": "Max Posts per Source",
                        "minimum": 1,
                        "maximum": 200,
                        "type": "integer",
                        "description": "Cap on the number of posts returned per handle / query.",
                        "default": 50
                    },
                    "delivery": {
                        "title": "Delivery",
                        "enum": [
                            "dataset",
                            "webhook"
                        ],
                        "type": "string",
                        "description": "Where to send results: dataset or webhook.",
                        "default": "dataset"
                    },
                    "webhookUrl": {
                        "title": "Webhook URL",
                        "type": "string",
                        "description": "Webhook URL to POST results to when delivery=webhook."
                    },
                    "dryRun": {
                        "title": "Dry Run",
                        "type": "boolean",
                        "description": "Run without saving results to the dataset.",
                        "default": false
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```