Mastodon Scraper

The same hashtag, two servers, two different sets of posts. A Mastodon instance only holds what has been federated to it, so the instance field is the setting that matters most: mastodon.social shows you what that server has received, while fosstodon.org and mas.to will each show you something else.

Every instance runs its own public REST API, and this reads it. Three things you can ask for: a hashtag timeline, one account's posts, or the instance's public timeline. Post text comes back as plain text with the HTML already stripped.

What you get back

{
  "ok": true,
  "id": "117134387141087848",
  "text": "Terminal Browser punta su velocità, semplicità e workflow da riga di comando. #Linux #OpenSource",
  "author": "linuxeasy@mastodon.uno",
  "authorName": "Linux Easy",
  "authorFollowers": 1757,
  "createdAt": "2026-08-21T16:15:03.000Z",
  "repliesCount": 0,
  "reblogsCount": 0,
  "favouritesCount": 0,
  "language": "it",
  "mediaUrls": [],
  "tags": ["linux", "opensource", "terminal"],
  "url": "https://mastodon.uno/@linuxeasy/117134387047787209"
}

author is the full user@host handle when the post came from another server, or just the username when it's local. authorName is the display name and is often null — plenty of people never set one. mediaUrls holds the direct file URLs for any attached images or video.

Input

{
  "instance": "fosstodon.org",
  "mode": "hashtag",
  "query": "opensource",
  "maxItems": 500
}

Field	Default	Notes
instance	mastodon.social	Bare host, no https://.
mode	hashtag	hashtag, account or public.
query	empty	The hashtag in hashtag mode, the handle in account mode. # and @ are optional. Ignored in public mode. The Console prefills opensource; an API call has to send its own.
local	false	Public mode only. true restricts to posts made on this instance; false gives the federated firehose.
maxItems	100	1 to 2,000. Fetched 40 at a time.
proxyConfiguration	off	The API has no anti-bot. Only useful if an instance rate-limits your IP.

Account mode takes either a local handle (Mastodon) or a full remote one (user@otherinstance.social).

Three catches

Public timelines are often closed. A lot of instances, mastodon.social included, require authentication for the public timeline. In public mode against one of those you get a BLOCKED diagnostic row instead of posts. Hashtag and account modes still work there. If you specifically want a federated timeline, pick an instance that leaves it open.

Boosts credit the booster. When someone boosts another person's post, Mastodon's API gives you the booster as the account and the original text underneath. This actor reads the text from the original, so boosted rows aren't blank. But author, authorName and authorFollowers still describe the person who boosted it, not the person who wrote it. Check for that before you build any kind of "who said this" report.

Counts are that instance's counts. Replies, boosts and favourites are whatever the host you queried has received over federation so far. For a post that originated elsewhere, those numbers can trail the origin server's. They're a signal, not an audit.

Other limits

• A hashtag timeline is only posts the queried instance has seen. A small instance federated with few peers will show you less than a large one.
• Posts are deduplicated on ID within a run.
• Bad input, no results, or a blocked endpoint each produce one diagnostic row with an errorCode. None of them are billed.

Billing

$1.50 per 1,000 posts, so $0.0015 each, with no run-start fee. Only posts actually returned are charged. A run that gets blocked or finds nothing costs nothing.

Delivery

Dataset export in JSON, CSV, Excel or XML. notionConnector and notionParentId will additionally write one Notion page per post at the end of the run. Authorize the connector once under Settings → API & Integrations → MCP connectors, or leave the fields empty to skip.

What it's for

Brand monitoring, mostly. Pick the two or three instances your users are likely on and watch a hashtag on each. Running two is worth it: a hashtag timeline only holds what that host has federated, so the second instance regularly catches posts the first one never saw.

Archiving is the other one. Accounts and whole instances go dark on the fediverse with very little notice, and account mode with a high maxItems is a cheap way to keep a copy while it's still there.

For a text corpus, tags is populated on every row and language on most of them. Remote posts sometimes arrive with no language set at all, so budget for nulls in that column rather than assuming it's labelled for you.