Mastodon Scraper

Scrape public Mastodon posts from any instance via its open REST API — no login, no API key, no anti-bot. Pull a hashtag timeline, an account's toots, or the instance public/federated timeline.

What it does

Given an instance host and a mode, the actor calls the public Mastodon API and returns clean, structured posts:

• Hashtag timeline — every recent post tagged with a hashtag.
• Account toots — resolves an @handle to its account, then pulls that account's statuses (reblogs included). For a reblog/boost row, the author and authorName fields show the reblogger (the account whose timeline it appeared on), while the text, mediaUrls and tags come from the original boosted post.
• Public timeline — the instance's public timeline; toggle local for the local-only vs. federated view.

It pages automatically (40 posts per request, following the Link rel="next" header or max_id) until it reaches your maxItems or the timeline runs out. Post HTML is converted to plain text with a small dependency-free stripper.

Input

Field	Type	Default	Notes
instance	string	mastodon.social	Instance host, no scheme (e.g. fosstodon.org).
mode	string	hashtag	hashtag, account, or public.
query	string	—	Hashtag (hashtag mode) or @handle (account mode). Ignored for public.
local	boolean	false	Public mode only: local timeline if on, federated if off.
maxItems	integer	100	Max posts to return.
proxyConfiguration	object	none	Optional. These endpoints have no anti-bot, so a proxy gives no benefit — leave it off unless you hit instance-level IP rate limits.

Examples

{ "instance": "mastodon.social", "mode": "hashtag", "query": "opensource", "maxItems": 100 }

{ "instance": "mastodon.social", "mode": "account", "query": "Mastodon", "maxItems": 50 }

{ "instance": "mastodon.social", "mode": "public", "local": true, "maxItems": 80 }

Output

Each successful row:

{
  "ok": true,
  "id": "string",
  "text": "HTML-stripped post text",
  "author": "user@instance",
  "authorName": "Display Name",
  "authorFollowers": 12345,
  "createdAt": "2026-06-11T12:34:56.000Z",
  "repliesCount": 3,
  "reblogsCount": 10,
  "favouritesCount": 42,
  "language": "en",
  "mediaUrls": ["https://..."],
  "tags": ["opensource"],
  "url": "https://mastodon.social/@user/123"
}

Posts are deduplicated by id. You are charged one post event per returned row. Diagnostic rows (ok: false) and empty/blocked runs are never charged.

Nullable fields: author, authorName, authorFollowers, language, and url can be null when the instance omits them for a given post (e.g. an account with a hidden display name, or a status without a canonical URL yet). mediaUrls and tags are always arrays (possibly empty); count fields default to 0.

Diagnostics

The actor never silently returns nothing. On a problem it pushes a single diagnostic row (ok: false) with an errorCode and never charges for it:

• BAD_INPUT — the input was invalid (unknown mode, or hashtag/account mode with no query). The row's error/hint explain how to fix it; the run finishes cleanly without charging.
• NOT_FOUND — account/handle or instance not found.
• NO_RESULTS — the request succeeded but the timeline was empty.
• RATE_LIMITED / SERVER_ERROR / BLOCKED — transient target issues (retried with backoff first).
• NETWORK — could not reach the instance.

Troubleshooting

• Got BLOCKED on public mode? Some large instances (notably mastodon.social) gate the public/federated timeline behind authentication for unauthenticated callers, so the actor surfaces a BLOCKED diagnostic. Workarounds: use hashtag or account mode instead, point instance at an instance that leaves its public timeline open (e.g. fosstodon.org, mas.to), or enable a residential proxy if the block is purely IP-based.
• Got BAD_INPUT? Check the error/hint fields in the diagnostic row — usually a missing query in hashtag/account mode.

Notes

• Sends User-Agent: dami-studios-actor.
• No third-party HTML parser — content HTML is converted to text in-house.
• Works against any Mastodon-compatible instance that exposes the standard public timelines.