# Mastodon Scraper: Posts, Profiles, Followers & Trends (`perconey/mastodon-scraper`) Actor Scrape any Mastodon instance (mastodon.social, hachyderm.io, infosec.exchange, fosstodon.org and 11,000+ others) via the official REST API. User profiles, statuses, followers, hashtag timelines, status threads, trending tags. No auth, no proxies, no cookies. Pay only per result item. - **URL**: https://apify.com/perconey/mastodon-scraper.md - **Developed by:** [Perconey](https://apify.com/perconey) (community) - **Categories:** Social media, Lead generation, Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing $1.00 / 1,000 result items This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.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 ### What does Mastodon Scraper do? **Mastodon Scraper** pulls structured data from any [Mastodon](https://joinmastodon.org/) instance through the **official REST API** (`/api/v1/*`). User profiles with follower counts and bio, public statuses with engagement (favourites, boosts, replies), entire threads, hashtag timelines, instance public timelines, trending tags. The actor hits the documented API directly, so no browser, no proxies, no cookies, no anti-bot fight, ever. One actor works with **all 11,000+ Mastodon-protocol servers** (mastodon.social, hachyderm.io, infosec.exchange, fosstodon.org, journa.host) and any Pleroma/Akkoma fork that implements the same API. Try it instantly: pick **getProfile**, set instance `https://mastodon.social`, type `Gargron` (Mastodon's founder), click Start. You get his profile with 380k+ followers, bio, fields, post count in under 5 seconds, for $0.001. ### Why use Mastodon Scraper? - **Federation researchers**: Map account migration patterns when a user moves from one instance to another. Track instance growth via `getPublicTimeline` cadence. - **Community managers**: Monitor mentions of your brand across instances using `getHashtagTimeline`. Schedule the actor on Apify to alert you on new boosts. - **DevRel and OSS maintainers**: Mastodon has heavy developer adoption. Use `getProfile` + `getUserStatuses` for high-follower-count developers tagged with your project to find advocates and detractors. - **Academic researchers**: Mastodon's protocol is open and federation creates a natural network-science dataset. `getTrendingTags` per instance per day is a research gold-mine. - **Content creators**: `getUserStatuses` for top creators in your niche to study posting cadence, what topics drive engagement. - **Open-source intelligence**: infosec.exchange has the entire infosec Twitter diaspora. Pull their posts to track CVE chatter without paying for X's API. ### How to use Mastodon Scraper 1. Open the **Input** tab. 2. Pick an **action**. `getProfile` is the simplest starting point. 3. Set **instance** (default `https://mastodon.social`). To scrape a different server, paste its full URL (e.g. `https://hachyderm.io`). 4. For most actions, fill **queries** (one entry per line). For `getPublicTimeline` and `getTrendingTags`, leave queries empty. 5. Tune **maxItems** (default 100), **local** (true for instance-only timelines vs. federated firehose), and the `includeReplies` / `includeReposts` toggles for user-status actions. 6. Click **Start**. Results stream to the dataset and you can preview them on the **Output** tab. ### Input Field | Required | Description --- | --- | --- `action` | yes | Which API call to make. Eight options. `instance` | yes | Mastodon instance URL. Defaults to https://mastodon.social. `queries` | sometimes | Required for profile/status/hashtag actions. Empty for getPublicTimeline / getTrendingTags. `maxItems` | no | Max items per query. Default 100. `local` | no | For timeline actions: true returns only the instance's own posts, false returns the federated timeline. `onlyMedia` | no | Skip text-only posts. `includeReplies` | no | For getUserStatuses: include posts that are replies. Default true. `includeReposts` | no | For getUserStatuses: include boosted posts. Default true. `token` | no | OAuth bearer token. Only needed if the instance restricts followers lists to logged-in users. #### Query format by action Action | Query format --- | --- getProfile | `Gargron`, `user@server.tld`, `https://mastodon.social/@Gargron`, or numeric id getUserStatuses | same as getProfile getUserFollowers | same as getProfile getStatusDetail | full status URL like `https://mastodon.social/@Gargron/110123456789012345` getStatusContext | same as getStatusDetail getHashtagTimeline | hashtag without `#` (e.g. `mastodonart`) getPublicTimeline | leave empty getTrendingTags | leave empty ### Output Every dataset item carries a `_type` field (`account`, `status`, `tag`, or `error`) plus `_action` and `_instance` so you can filter when one run mixes data from multiple instances. ```json { "_type": "account", "_action": "getProfile", "_instance": "https://mastodon.social", "id": "1", "username": "Gargron", "acct": "Gargron", "display_name": "Eugen Rochko", "url": "https://mastodon.social/@Gargron", "avatar": "https://files.mastodon.social/accounts/avatars/...", "followers_count": 380000, "following_count": 720, "statuses_count": 79000, "note": "Founder, CEO and lead developer @Mastodon.", "bot": false, "created_at": "2016-03-16T14:34:26.392Z", "fields": [ { "name": "Website", "value": "https://zeonfederated.com" } ] } ```` You can download the dataset in JSON, CSV, XML, Excel, RSS, or HTML format from the Output tab or the Apify API. ### Data fields Type | Key fields \--- | --- `account` | id, acct, username, display\_name, url, avatar, followers\_count, following\_count, statuses\_count, note (bio), fields, created\_at, bot, locked `status` | id, uri, url, content (HTML), created\_at, favourites\_count, reblogs\_count, replies\_count, visibility, language, media\_attachments, tags, mentions, account, reblog\_of (if it's a boost), card (preview) `tag` | name, url, history (per-day uses), total\_uses, total\_accounts ### Pricing **Pay-per-result: $0.001 per item.** One account = one event. One status = one event. One trending tag = one event. No flat monthly fee, no rental, no charge for the time the actor runs (just Apify's default compute, ~$0.0002 per typical run at 512 MB). Cost examples: - One profile lookup: **$0.001** - 1,000 posts from infosec.exchange's local timeline: **$1.00** - Following the #mastodonart hashtag (500 posts/day, scheduled daily): **$0.50/day** - 500 high-follower accounts (for community research, profile only): **$0.50** ### Tips - **Federated reach**: set `local: false` on `getPublicTimeline` or `getHashtagTimeline` to see posts the instance has *seen* from peers, not just posts authored locally. The federated firehose is broader but noisier. - **Cross-instance research**: schedule the same input with different `instance` values. infosec.exchange's local timeline is very different from mastodon.social's. - **Most followers lists are public**, but some instances restrict them to logged-in users. If you hit a 401/403, paste an OAuth token (any access token from the target instance) in the `token` field. - **Status IDs are not portable across instances** - `123456` on mastodon.social refers to a totally different post than `123456` on hachyderm.io. Always pass full URLs to `getStatusDetail` / `getStatusContext` so the actor uses the right instance. - **Pleroma/Akkoma instances** mostly speak the same API. Most actions just work. Trending tags is a Mastodon-specific endpoint; on Pleroma the actor returns an empty result with a log warning instead of crashing. ### FAQ, disclaimers, support **Is this legal?** The actor calls each instance's public REST API with documented endpoints. Public read access is the default behavior of any Mastodon server. We send a clear User-Agent identifying the actor and we honor `429`/`Retry-After` rate-limit headers. Each instance's admins set their own ToS - if you're scraping at scale from one instance, consider donating to it. **Why no `searchPosts` action?** Full-text post search requires an authenticated session on most instances (a deliberate privacy decision by the Mastodon project). Hashtag and timeline scraping are the public alternatives. **`getPublicTimeline` returns 422 on mastodon.social.** Mastodon.social blocks anonymous access to its public timeline. Use a different instance like `https://hachyderm.io`, `https://fosstodon.org`, `https://infosec.exchange`, or `https://mas.to` - they still allow anon reads. Profile, status, hashtag, and trending-tags actions DO work anon on mastodon.social. **Does it work with Pixelfed / Lemmy / GoToSocial?** Pixelfed and GoToSocial implement large parts of the Mastodon API and most actions work. Lemmy uses a different API and is NOT supported. **Will I get rate-limited?** Public reads have a generous limit (300 requests / 5 min on most instances). The actor honors `Retry-After` and retries 429/502/503/504 with exponential backoff. **Bug or feature request?** Open an Issue on the actor's Issues tab. I usually respond within a day. **Need a custom scraper for another federated platform?** Bluesky? Threads? See my other actors at https://apify.com/perconey, or open an Issue. # Actor input Schema ## `action` (type: `string`): Pick the type of data. getPublicTimeline and getTrendingTags work with no queries. The others require at least one entry in queries. ## `instance` (type: `string`): Which Mastodon-protocol server to query. Default https://mastodon.social. Examples: https://hachyderm.io, https://infosec.exchange, https://fosstodon.org. For getProfile with a full URL or acct (user@server), the actor uses that server automatically. ## `queries` (type: `array`): Depends on action. getProfile/getUserStatuses/getUserFollowers: handle (Gargron), acct (user@server), full profile URL (https://mastodon.social/@Gargron), or numeric id. getStatusDetail/getStatusContext: full status URL (https://mastodon.social/@user/123456...). getHashtagTimeline: hashtag without #. getPublicTimeline and getTrendingTags: leave empty. ## `maxItems` (type: `integer`): Stop after this many items per query. Use 0 for unlimited. ## `local` (type: `boolean`): For getPublicTimeline and getHashtagTimeline: true returns only posts from the instance you query, false returns the federated firehose (posts from peers the instance has seen). ## `onlyMedia` (type: `boolean`): For timeline-style actions: skip text-only posts. ## `includeReplies` (type: `boolean`): Set false to exclude posts that are replies to another user. ## `includeReposts` (type: `boolean`): Set false to exclude boosted (reblogged) posts. ## `token` (type: `string`): OAuth bearer token for the instance. Only needed for actions that the instance restricts to logged-in users (some lock followers lists). Most public reads work without it. ## Actor input object example ```json { "action": "getProfile", "instance": "https://mastodon.social", "queries": [ "Gargron" ], "maxItems": 100, "local": true, "onlyMedia": false, "includeReplies": true, "includeReposts": true } ``` # Actor output Schema ## `dataset` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "instance": "https://mastodon.social", "queries": [ "Gargron" ] }; // Run the Actor and wait for it to finish const run = await client.actor("perconey/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": "https://mastodon.social", "queries": ["Gargron"], } # Run the Actor and wait for it to finish run = client.actor("perconey/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": "https://mastodon.social", "queries": [ "Gargron" ] }' | apify call perconey/mastodon-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=perconey/mastodon-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Mastodon Scraper: Posts, Profiles, Followers & Trends", "description": "Scrape any Mastodon instance (mastodon.social, hachyderm.io, infosec.exchange, fosstodon.org and 11,000+ others) via the official REST API. User profiles, statuses, followers, hashtag timelines, status threads, trending tags. No auth, no proxies, no cookies. Pay only per result item.", "version": "0.1", "x-build-id": "bQyYgDBe3IAtWo8nG" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/perconey~mastodon-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-perconey-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/perconey~mastodon-scraper/runs": { "post": { "operationId": "runs-sync-perconey-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/perconey~mastodon-scraper/run-sync": { "post": { "operationId": "run-sync-perconey-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", "required": [ "action", "instance" ], "properties": { "action": { "title": "What do you want to scrape?", "enum": [ "getProfile", "getUserStatuses", "getUserFollowers", "getStatusDetail", "getStatusContext", "getHashtagTimeline", "getPublicTimeline", "getTrendingTags" ], "type": "string", "description": "Pick the type of data. getPublicTimeline and getTrendingTags work with no queries. The others require at least one entry in queries.", "default": "getProfile" }, "instance": { "title": "Mastodon instance", "type": "string", "description": "Which Mastodon-protocol server to query. Default https://mastodon.social. Examples: https://hachyderm.io, https://infosec.exchange, https://fosstodon.org. For getProfile with a full URL or acct (user@server), the actor uses that server automatically.", "default": "https://mastodon.social" }, "queries": { "title": "Queries", "type": "array", "description": "Depends on action. getProfile/getUserStatuses/getUserFollowers: handle (Gargron), acct (user@server), full profile URL (https://mastodon.social/@Gargron), or numeric id. getStatusDetail/getStatusContext: full status URL (https://mastodon.social/@user/123456...). getHashtagTimeline: hashtag without #. getPublicTimeline and getTrendingTags: leave empty.", "items": { "type": "string" } }, "maxItems": { "title": "Max items per query", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Stop after this many items per query. Use 0 for unlimited.", "default": 100 }, "local": { "title": "Local timeline only?", "type": "boolean", "description": "For getPublicTimeline and getHashtagTimeline: true returns only posts from the instance you query, false returns the federated firehose (posts from peers the instance has seen).", "default": true }, "onlyMedia": { "title": "Only posts with media", "type": "boolean", "description": "For timeline-style actions: skip text-only posts.", "default": false }, "includeReplies": { "title": "Include replies (getUserStatuses)", "type": "boolean", "description": "Set false to exclude posts that are replies to another user.", "default": true }, "includeReposts": { "title": "Include boosts/reposts (getUserStatuses)", "type": "boolean", "description": "Set false to exclude boosted (reblogged) posts.", "default": true }, "token": { "title": "Mastodon access token (optional)", "type": "string", "description": "OAuth bearer token for the instance. Only needed for actions that the instance restricts to logged-in users (some lock followers lists). Most public reads work without it." } } }, "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 } } } } } } } } } } ```