# Mastodon Scraper (`goat255/mastodon-scraper`) Actor Scrape Mastodon (fediverse) posts, profiles, hashtags, and account search without a login. Pull a user's posts by handle, a hashtag timeline, the public timeline, or matching profiles. Works against any instance and walks pagination up to your chosen limit. - **URL**: https://apify.com/goat255/mastodon-scraper.md - **Developed by:** [Goutam Soni](https://apify.com/goat255) (community) - **Categories:** Social media, News - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: 5.00 out of 5 stars ## 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 Scraper Scrape public Mastodon posts, profiles, hashtags, and account search from across the fediverse with no login and no API key required. Point it at any Mastodon instance and pull a user's posts by handle, a hashtag timeline, the public timeline, or matching profiles as clean structured JSON, CSV, or Excel. ### What it does - **Mastodon user posts by handle.** Works with a bare username on your chosen instance, a full `user@host` for a remote account, or a profile link. Pulls recent posts (statuses, boosts, replies) with engagement counts. - **Profile data.** Optionally emit a profile row per handle with display name, bio, follower count, following count, and post count. - **Hashtag scraper.** Pull every post on any instance's public hashtag timeline. - **Public timeline scraper.** Stream an instance's public timeline (where the server allows it). - **Profile search.** Find matching public Mastodon accounts by keyword. - **Automatic pagination.** Walks page after page up to the limit you set, deduplicates posts, and stops cleanly when a source is exhausted. - **Clean normalized output.** Plain-text post bodies, parsed media URLs, hashtags, mentions, and engagement metrics in one stable schema across every mode. No account, no password, no API key. Give it an instance plus handles, hashtags, or search terms and it returns structured rows. ### Use cases - **Social media monitoring.** Track a brand, topic, or hashtag across the fediverse and watch engagement over time. - **Lead generation and audience research.** Search profiles by keyword and export handles, bios, and follower counts for outreach lists. - **Market and competitor research.** Collect posts from accounts in your niche and analyze what resonates by favourites and boosts. - **News and trend tracking.** Stream a hashtag or public timeline to spot emerging stories and conversations early. - **Dataset building.** Assemble labeled post and profile datasets for sentiment analysis, content classification, or LLM training. ### Input | Field | Type | Description | |---|---|---| | `instance` | string | The Mastodon server to scrape from for hashtags, search, and bare usernames. Host or URL. Default `mastodon.social`. | | `handles` | array | Usernames to pull posts from. Bare username, `user@host`, or a profile link. | | `hashtags` | array | Hashtags to pull from the instance's public tag timeline. With or without the `#` prefix. | | `searchQueries` | array | Keywords to find matching public profiles on the chosen instance. | | `publicTimeline` | boolean | When on, also pull the instance's public timeline. | | `maxItemsPerSource` | integer | Cap per handle, hashtag, search, or timeline. Pagination is walked to reach it. Default `100`. | | `includeReplies` | boolean | Include a handle's reply posts, not just top-level posts. Default `false`. | | `includeReblogs` | boolean | Include posts a handle has boosted. Default `true`. | | `onlyMedia` | boolean | Restrict feeds and the public timeline to posts that carry an image or video. Default `false`. | | `includeProfile` | boolean | Emit one profile row per handle before its posts. Default `true`. | | `concurrency` | integer | How many sources to process in parallel. Default `5`. | | `proxyConfig` | object | Optional proxy. The public endpoints do not require one. | #### Example input ```json { "instance": "mastodon.social", "handles": ["example_user", "example_user@example.social"], "hashtags": ["opensource"], "maxItemsPerSource": 200, "includeProfile": true, "includeReplies": false, "includeReblogs": true } ```` ### Output Each post is one row. Fields are ordered identity first, then engagement metrics, then content and media: ```json { "type": "post", "id": "100000000000000000", "url": "https://example.social/@example_user/100000000000000000", "authorHandle": "example_user@example.social", "authorDisplayName": "Example User", "authorUrl": "https://example.social/@example_user", "favouritesCount": 42, "reblogsCount": 7, "repliesCount": 3, "quotesCount": 1, "text": "An example post about open source.", "language": "en", "tags": ["opensource"], "mentions": ["another_user@example.social"], "images": ["https://example.com/image.jpg"], "videos": [], "links": ["https://example.com"], "visibility": "public", "sensitive": false, "spoilerText": null, "isReply": false, "inReplyToId": null, "isReblog": false, "createdAt": "2026-06-01T12:00:00.000Z", "editedAt": null } ``` When `includeProfile` is on (or from profile search), a profile row carries: ```json { "type": "profile", "id": "1", "handle": "example_user@example.social", "url": "https://example.social/@example_user", "displayName": "Example User", "followersCount": 12000, "followingCount": 300, "statusesCount": 4500, "description": "Example bio.", "avatar": "https://example.com/avatar.png", "header": "https://example.com/header.png", "locked": false, "bot": false, "createdAt": "2020-01-01T00:00:00.000Z" } ``` #### Key fields - **`type`** tells `post` rows apart from `profile` rows. - **`url`** is the canonical link to the post or profile. - **`favouritesCount`, `reblogsCount`, `repliesCount`, `quotesCount`** are the engagement metrics at scrape time. - **`text`** is the post body as clean plain text. The original HTML is kept in `contentHtml`. - **`images`, `videos`, `links`** are arrays of media and card URLs (empty when the post has none). - **`isReblog`** marks a boosted post; **`isReply` / `inReplyToId`** mark replies. ### FAQ **Is this scraper free? How is it priced?** You pay only for what you run. There is no per-run start fee. See the pricing tab on this listing for the current rate. **Do I need a Mastodon account, login, or API key?** No. The scraper reads public data through the open fediverse endpoints. No account, password, or token is needed. **How many posts or profiles can I get?** Set `maxItemsPerSource` to any value up to 50000. The scraper walks pagination across as many pages as needed to reach your target or until the source runs out. Profile search returns up to the server's search limit. **Which Mastodon instances does it support?** Any instance. Set `instance` to the host you want (for example `mastodon.social` or `https://example.social`), and use `user@host` handles to reach accounts on other servers. **Can I scrape a hashtag across the whole fediverse?** You scrape a hashtag from the chosen instance's public tag timeline, which federates posts that instance has seen. Point at a larger, well-connected instance for broader coverage. **How fast is it?** Multiple sources run in parallel (set with `concurrency`), and each source pages until your limit. A typical handle or hashtag of a few hundred posts completes in seconds. **What if a server blocks the public timeline or search?** Some servers gate those endpoints. When one does, the run skips that mode and continues with your other handles, hashtags, and searches. # Actor input Schema ## `instance` (type: `string`): The Mastodon server to scrape from for hashtags, search, and bare usernames. A host name or URL. Example: mastodon.social, https://fosstodon.org. ## `handles` (type: `array`): Usernames to pull recent posts from. Use a bare username for the chosen instance, a full user@host for a remote account, or a full profile link. Example: example\_user, example\_user@example.social, https://example.social/@example\_user. ## `hashtags` (type: `array`): Hashtags to pull from the chosen instance's public tag timeline. With or without the # prefix. Example: opensource, photography. ## `searchQueries` (type: `array`): Keywords to search for matching public profiles on the chosen instance. Example: open source, journalism. ## `publicTimeline` (type: `boolean`): When on, also pull the chosen instance's public timeline. Some servers restrict this; if so the run continues with the other modes. ## `maxItemsPerSource` (type: `integer`): Cap on items returned per handle, hashtag, search, or timeline. Pagination is walked across multiple pages until this is reached or the source is exhausted. ## `includeReplies` (type: `boolean`): When on, a handle's reply posts are included alongside its top-level posts. ## `includeReblogs` (type: `boolean`): When on, posts a handle has boosted are included alongside their own posts. ## `onlyMedia` (type: `boolean`): When on, restrict user feeds and the public timeline to posts that carry an image or video. ## `includeProfile` (type: `boolean`): When on, each handle also emits one profile record (display name, bio, follower counts) before its posts. ## `concurrency` (type: `integer`): How many sources to process in parallel. ## `proxyConfig` (type: `object`): Optional proxy. The public read endpoints do not require a proxy, but you may route through one if you wish. ## Actor input object example ```json { "instance": "mastodon.social", "handles": [ "Gargron" ], "hashtags": [], "searchQueries": [], "publicTimeline": false, "maxItemsPerSource": 100, "includeReplies": false, "includeReblogs": true, "onlyMedia": false, "includeProfile": true, "concurrency": 5, "proxyConfig": { "useApifyProxy": 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 = { "instance": "mastodon.social", "handles": [ "Gargron" ], "hashtags": [], "searchQueries": [] }; // Run the Actor and wait for it to finish const run = await client.actor("goat255/mastodon-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 = { "instance": "mastodon.social", "handles": ["Gargron"], "hashtags": [], "searchQueries": [], } # Run the Actor and wait for it to finish run = client.actor("goat255/mastodon-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 '{ "instance": "mastodon.social", "handles": [ "Gargron" ], "hashtags": [], "searchQueries": [] }' | apify call goat255/mastodon-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=goat255/mastodon-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Mastodon Scraper", "description": "Scrape Mastodon (fediverse) posts, profiles, hashtags, and account search without a login. Pull a user's posts by handle, a hashtag timeline, the public timeline, or matching profiles. Works against any instance and walks pagination up to your chosen limit.", "version": "0.1", "x-build-id": "kJgwQcuSUDJyResfE" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/goat255~mastodon-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-goat255-mastodon-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/goat255~mastodon-scraper/runs": { "post": { "operationId": "runs-sync-goat255-mastodon-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/goat255~mastodon-scraper/run-sync": { "post": { "operationId": "run-sync-goat255-mastodon-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", "properties": { "instance": { "title": "Instance host", "type": "string", "description": "The Mastodon server to scrape from for hashtags, search, and bare usernames. A host name or URL. Example: mastodon.social, https://fosstodon.org.", "default": "mastodon.social" }, "handles": { "title": "Handles (user mode)", "type": "array", "description": "Usernames to pull recent posts from. Use a bare username for the chosen instance, a full user@host for a remote account, or a full profile link. Example: example_user, example_user@example.social, https://example.social/@example_user.", "default": [ "Gargron" ], "items": { "type": "string" } }, "hashtags": { "title": "Hashtags (tag mode)", "type": "array", "description": "Hashtags to pull from the chosen instance's public tag timeline. With or without the # prefix. Example: opensource, photography.", "items": { "type": "string" } }, "searchQueries": { "title": "Search queries (profile search)", "type": "array", "description": "Keywords to search for matching public profiles on the chosen instance. Example: open source, journalism.", "items": { "type": "string" } }, "publicTimeline": { "title": "Public timeline", "type": "boolean", "description": "When on, also pull the chosen instance's public timeline. Some servers restrict this; if so the run continues with the other modes.", "default": false }, "maxItemsPerSource": { "title": "Max items per source", "minimum": 1, "maximum": 50000, "type": "integer", "description": "Cap on items returned per handle, hashtag, search, or timeline. Pagination is walked across multiple pages until this is reached or the source is exhausted.", "default": 100 }, "includeReplies": { "title": "Include replies in user feeds", "type": "boolean", "description": "When on, a handle's reply posts are included alongside its top-level posts.", "default": false }, "includeReblogs": { "title": "Include boosts in user feeds", "type": "boolean", "description": "When on, posts a handle has boosted are included alongside their own posts.", "default": true }, "onlyMedia": { "title": "Only posts with media", "type": "boolean", "description": "When on, restrict user feeds and the public timeline to posts that carry an image or video.", "default": false }, "includeProfile": { "title": "Include a profile header row", "type": "boolean", "description": "When on, each handle also emits one profile record (display name, bio, follower counts) before its posts.", "default": true }, "concurrency": { "title": "Concurrency", "minimum": 1, "maximum": 20, "type": "integer", "description": "How many sources to process in parallel.", "default": 5 }, "proxyConfig": { "title": "Proxy configuration", "type": "object", "description": "Optional proxy. The public read endpoints do not require a proxy, but you may route through one if you wish.", "default": { "useApifyProxy": 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 } } } } } } } } } } ```