# 🐘 Mastodon & Fediverse Monitor (`taroyamada/mastodon-activitypub-monitor`) Actor Track brand mentions, accounts, and trending hashtags across any Mastodon instance to extract statuses, engagement metrics, and public timeline data. - **URL**: https://apify.com/taroyamada/mastodon-activitypub-monitor.md - **Developed by:** [åĪŠéƒŽ åąąį”°](https://apify.com/taroyamada) (community) - **Categories:** Social media, Marketing - **Stats:** 2 total users, 1 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 ## Mastodon & Fediverse Monitor Navigating the decentralized web requires specialized tools. This Mastodon and Fediverse monitor is designed to scrape and extract public data from any ActivityPub-compatible instance using standard API endpoints. Whether you are conducting social listening for a brand, tracking trending hashtags across different servers, or building a dataset of public conversations, this scraper provides direct access to the decentralized social graph. Users rely on this tool to run daily or weekly schedules to monitor specific profiles, aggregate posts, and track engagement without needing any authentication. By simply inputting the target instance URLs, accounts, or hashtags, you can extract rich details from the public timelines. The results are highly structured, making it easy to analyze decentralized communities. You can scrape full status content, URL links, account handles, creation timestamps, and language tags. Furthermore, it accurately captures critical engagement data, including reblog, favourite, and reply counts, alongside a detailed summary of media attachments. Because the Fediverse operates differently than traditional platforms like Instagram or Facebook, capturing cross-instance chatter requires a targeted approach. This monitor bridges the gap, allowing marketers, researchers, and community managers to gather actionable insights, search for specific keywords, and export the scraped web data seamlessly for downstream analysis. ### 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 — the Mastodon API is a well-documented open standard exposed by every Fediverse instance; /api/v1/accounts, /api/v1/timelines/tag, and /api/v1/timelines/public require no authentication for public content.** ### V1 scope Mastodon-compatible public API only (/api/v1 endpoints). Per status: ID, URL, account handle, content, created-at, reblog/favourite/reply counts, media attachments summary, language. OUT OF SCOPE: authenticated home timeline, direct messages, follow requests, instance admin endpoints, ActivityPub inbox/outbox federation mechanics. ### Extraction surfaces - Account lookup: https://{instance}/api/v1/accounts/lookup?acct={user} - Account statuses: https://{instance}/api/v1/accounts/{id}/statuses - Hashtag timeline: https://{instance}/api/v1/timelines/tag/{tag} - Public timeline: https://{instance}/api/v1/timelines/public - Instance info: https://{instance}/api/v1/instance ### Known limitations and explicit warnings - Each Fediverse instance is independently operated — rate limits, up-time, and federation scope vary. - Not every Fediverse instance runs Mastodon; Pleroma, Akkoma, Misskey, GoToSocial expose compatible but not identical APIs (V1 targets the Mastodon-compatible subset). - Hashtag timelines only include statuses the queried instance has federated; global hashtag coverage requires querying multiple instances. - Public timelines exclude private / followers-only / unlisted posts by design. - Rate limits are typically 300 requests / 5 minutes for unauthenticated clients; the actor paces at â‰Ĩ250ms per request. - Instance admins can disable the public API entirely — the actor gracefully skips blocked instances and records the reason. - Boost (reblog) counts are per-instance and are not a global Fediverse-wide total. - Account lookups require webfinger resolution when the account is on a different instance — best-effort. - Content HTML is emitted verbatim; plain-text extraction is a convenience field only. - Media attachments return URLs only; bytes are not downloaded. ### Input - Fediverse instances / accounts / hashtags - Delivery mode (dataset or webhook) - Dry-run support for local validation ### Output - Normalized `statuses` 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/mastodon-activitypub-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/mastodon-activitypub-monitor/issues) of this actor. # Actor input Schema ## `instances` (type: `array`): Fediverse instance hostnames (e.g. 'fosstodon.org', 'hachyderm.io'). Note: mastodon.social now requires auth for /timelines/public; use a smaller instance or supply hashtags. ## `accounts` (type: `array`): Account handles in user@instance form (e.g. 'Gargron@mastodon.social'). ## `hashtags` (type: `array`): Hashtags to query on each instance's tag timeline. ## `maxStatusesPerSource` (type: `integer`): Cap on the number of statuses to collect per source. ## `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 { "instances": [ "fosstodon.org" ], "accounts": [], "hashtags": [], "maxStatusesPerSource": 40, "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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "instances": [ "fosstodon.org" ], "accounts": [], "hashtags": [] }; // Run the Actor and wait for it to finish const run = await client.actor("taroyamada/mastodon-activitypub-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "instances": ["fosstodon.org"], "accounts": [], "hashtags": [], } # Run the Actor and wait for it to finish run = client.actor("taroyamada/mastodon-activitypub-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 '{ "instances": [ "fosstodon.org" ], "accounts": [], "hashtags": [] }' | apify call taroyamada/mastodon-activitypub-monitor --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=taroyamada/mastodon-activitypub-monitor", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "🐘 Mastodon & Fediverse Monitor", "description": "Track brand mentions, accounts, and trending hashtags across any Mastodon instance to extract statuses, engagement metrics, and public timeline data.", "version": "0.1", "x-build-id": "gmHnweOrRLMv0fq9G" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/taroyamada~mastodon-activitypub-monitor/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-taroyamada-mastodon-activitypub-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~mastodon-activitypub-monitor/runs": { "post": { "operationId": "runs-sync-taroyamada-mastodon-activitypub-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~mastodon-activitypub-monitor/run-sync": { "post": { "operationId": "run-sync-taroyamada-mastodon-activitypub-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": { "instances": { "title": "Instance Hostnames", "type": "array", "description": "Fediverse instance hostnames (e.g. 'fosstodon.org', 'hachyderm.io'). Note: mastodon.social now requires auth for /timelines/public; use a smaller instance or supply hashtags.", "items": { "type": "string" } }, "accounts": { "title": "Account Handles", "type": "array", "description": "Account handles in user@instance form (e.g. 'Gargron@mastodon.social').", "items": { "type": "string" } }, "hashtags": { "title": "Hashtags", "type": "array", "description": "Hashtags to query on each instance's tag timeline.", "items": { "type": "string" } }, "maxStatusesPerSource": { "title": "Max Statuses per Source", "minimum": 1, "maximum": 200, "type": "integer", "description": "Cap on the number of statuses to collect per source.", "default": 40 }, "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 } } } } } } } } } } ```