Mastodon Posts Scraper — Hashtags & Accounts

---

🎯 What this scrapes

Mastodon is federated — thousands of independently-run instances, no single "Twitter-style" global feed. This Actor targets the two query modes that stay reliably open across the network without authentication:

1. Hashtag timeline — GET /api/v1/timelines/tag/<tag> on your chosen instance, walked backward through history via Link-header pagination.
2. Account timeline — resolves an @handle (bare or federated user@remote.instance form) to its numeric id, then walks that account's public statuses.

Run any mix of hashtags and accounts in a single job; each query is independently fault-isolated, so one dead hashtag or mistyped handle never sinks the whole run.

🔥 Features

• 🛡️ Browser fingerprint impersonation — curl-cffi replays a real Chrome TLS handshake for every request.
• 🔁 Retries with exponential backoff on 429 / 5xx, honouring Retry-After and x-ratelimit-reset — the tag and account endpoints share one rate-limit bucket, so we pace accordingly.
• 🧱 Fault isolation per query — a bad hashtag, a typo'd handle, or a dead custom instance is logged and skipped, never a crashed run.
• 🌍 Multi-instance support — point at mastodon.social or any other federated host; not locked to one server.
• 🧊 Clean, typed dataset rows — Pydantic-validated, ISO-8601 timestamps, stable ids, both raw HTML and stripped plain text for every post.
• 💰 Pay-Per-Event pricing — $0.20 to start a run, then $0.002 per post row written.
• 🌐 Optional Apify Proxy routing — off by default for the public API; switch on for small self-hosted instances that rate-limit by source IP.

💡 Use cases

• Social listening — track a hashtag your brand or product cares about across the fediverse, not just one instance.
• Community/brand monitoring — watch what a competitor's or partner's Mastodon account is posting without checking manually.
• Fediverse research — build a longitudinal dataset of hashtag or account activity for academic or journalistic analysis.
• Content curation — pull recent posts under a topic hashtag to seed a newsletter, digest, or aggregator feed.
• Sentiment / NLP pipelines — feed content_text straight into a classifier without writing your own HTML stripper.

⚙️ How to use it

1. Open the Actor input form.
2. Set Instance to the federated host you want to query (default mastodon.social).
3. Add one or more Hashtags and/or Accounts — at least one of the two must be non-empty.
4. Adjust Results per query to cap how many posts are pulled per hashtag/account (default 40, max 2000).
5. Leave Proxy configuration off unless you're hitting a small self-hosted instance that rate-limits by IP.
6. Click Start. Results stream into the default dataset and can be exported as JSON, CSV, Excel, or XML.

📥 Input

Field	Type	Required	Default	Description
instance	string	no	mastodon.social	Federated host to query, no scheme/trailing slash
hashtags	array<string>	no*	[]	Hashtag names, with or without leading #
accounts	array<string>	no*	[]	Account handles, bare or user@remote.instance form
results_per_query	integer	no	40	Max post rows per hashtag/account (1–2000)
proxyConfiguration	object	no	{"useApifyProxy": false}	Apify Proxy config

* At least one of hashtags or accounts must be non-empty.

{
  "instance": "mastodon.social",
  "hashtags": ["python", "fediverse"],
  "accounts": ["Mastodon"],
  "results_per_query": 5,
  "proxyConfiguration": { "useApifyProxy": false }
}

📤 Output

One row per post, tagged with which query produced it.

{
  "id": "117243600697061639",
  "instance": "mastodon.social",
  "source_type": "hashtag",
  "source_query": "fediverse",
  "created_at": "2026-09-09T23:09:30.904Z",
  "content_html": "<p>...</p>",
  "content_text": "I've spent half of today trying to get more of my YouTube videos uploaded to @samxaviagaming ...",
  "visibility": "public",
  "favourites_count": 0,
  "reblogs_count": 1,
  "is_reblog": false,
  "account_acct": "sam@solent.social",
  "account_display_name": "Sam",
  "mentions": [{"id": "116954324987104741", "username": "samxaviagaming", "acct": "samxaviagaming@solent.social", "url": "https://solent.social/@samxaviagaming"}],
  "tags": [{"name": "fediverse", "url": "https://mastodon.social/tags/fediverse"}],
  "scraped_at": "2026-09-10T12:00:00+00:00"
}

💰 Pricing

Pay-Per-Event (PPE) — you pay only for what lands in your dataset:

Event	Price (USD)	When
actor-start	$0.20	Once per run, at boot
post-scraped	$0.002	Per post row written to the dataset

At 1,000 posts a run costs about $2.20 total. Zero rows written means you pay only the $0.20 start fee.

🚧 Limitations

• No public/global timeline — Mastodon's /api/v1/timelines/public endpoint requires authentication on many instances (confirmed on mastodon.social itself); only hashtag and account timelines ship in this version.
• Shared rate-limit bucket — hashtag and account queries on the same instance share one bucket (300 requests / 5 minutes on mastodon.social); running many hashtags/accounts with a high results_per_query may take longer as the Actor backs off.
• No streaming API — this Actor polls the REST API; it does not subscribe to /api/v1/streaming for live updates.
• Custom-emoji shortcodes stay literal — content_text/content_html keep :shortcode: text as the API sends it; no image substitution is performed.

❓ FAQ

Do I need a Mastodon account or API key?

No. Every endpoint this Actor calls — tag timelines and account lookups/statuses — is public and unauthenticated.

Can I scrape more than one instance in a single run?

Not in one run — instance is a single federated host per run. Run the Actor multiple times (or on a schedule) with different instance values to cover several servers.

What happens if a hashtag or account doesn't exist?

That one query is logged as a warning and skipped; the rest of your configured hashtags/accounts still run. The run only fails if every configured query fails outright.

What happens if my hashtag or account has zero matching posts?

The run succeeds with zero rows for that query and a status message describing what was searched — that's a genuine empty result, not a failure.

💬 Your feedback

Found a bug, hit a rate limit, or need a new field on the output row? Open an issue on the Actor's Apify Store page or contact the Devil Scrapes team at apify.com/DevilScrapes. We ship updates within days of validated reports.