Mastodon Public Posts & Hashtags

Mastodon posts scraper returns public post fields, source context, and diagnostic rows from selected instances.

Mastodon posts scraper uses the public source named below and writes its results to the Actor dataset.

Build status: Files are prepared for review. Python tests, the local actor run and apify validate-schema could not launch because the terminal returned Windows Access denied. Available official schema structural checks passed; runtime behavior remains unverified. Nothing has been published.

What it returns

The examples below are projected from the saved source response through the normalizer; this actor output has not been verified by a local run.

Output field	Type	Example value or excerpt from saved sample
type	string	"post"
instance	string	"https://mastodon.social"
sourceType	string	"hashtag"
sourceValue	string	"python"
postId	string	"117388741522677691"
timelineId	string	"117388741522677691"
uri	string	"https://mastodon.social/users/hugovalters/statuses/117388741522677691"
url	string	"https://mastodon.social/@hugovalters/117388741522677691"
createdAt	string	"2026-10-05T14:20:45.242Z"
editedAt	null	null
fetchedAt	string	datetime.now(timezone.utc).isoformat() (from the normalizer)
visibility	string	"public"
text	string	"Trigger GitHub Actions workflows programmatically from CI pipelines, Slack bots, or cron jobs. 209 …
contentHtml	string	"<p>Trigger GitHub Actions workflows programmatically from CI pipelines, Slack bots, or cron jobs. 2…
spoilerText	string	""
sensitive	boolean	false
language	string	"en"
accountId	string	"114434182937791007"
accountAcct	string	"hugovalters@mastodon.social"
accountDisplayName	string	"Hugo | DevOps | Cybersecurity"
accountUrl	string	"https://mastodon.social/@hugovalters"
hashtags	array	["python"]
favouritesCount	integer	0
reblogsCount	integer	0
repliesCount	integer	0
inReplyToId	null	null
isBoost	boolean	false
boostedBy	null	null
media	array	[]
poll	null	null
errors	array	[]

Fields	Meaning
type	post for a saved public post; error for a source/input/item failure
instance	HTTPS instance that served the response
sourceType, sourceValue	Public, hashtag or account source and requested target; invalid list entries use an input index
postId, timelineId	Original post ID and timeline wrapper ID, kept as strings
uri, url	Original federated identity and link to the post
createdAt, editedAt, fetchedAt	Source publication/edit times and retrieval time
visibility	public for exported posts; unlisted/private/direct statuses are filtered
text, contentHtml	Readable text and source HTML; treat HTML as untrusted content
spoilerText, sensitive, language	Content warning, sensitivity flag and source language
accountId, accountAcct	Server-local author ID and federated handle
accountDisplayName, accountUrl	Public author name and profile link
hashtags	Hashtag names
favouritesCount, reblogsCount, repliesCount	Engagement counters as reported by the serving instance
inReplyToId	Replied-to status ID, if present
isBoost, boostedBy	Whether the source row was a boost and its public booster context
media	Media IDs/types, original/preview URLs, alt descriptions and available dimensions
poll	Public poll options, vote counts and expiry, when available
errors	Empty for post rows; one explanation for error rows

Boosts are normalized to the original post. The original URI is used for deduplication across pages, accounts and instances. The first source that delivers a post supplies its source context; matching sources are not aggregated. Error rows contain the relevant source and explanation and omit post-only fields.

Input example

{
  "instances": ["https://mastodon.social", "https://fosstodon.org"],
  "mode": "hashtag",
  "hashtags": ["python", "opensource"],
  "maxItems": 100,
  "concurrency": 3,
  "local": false,
  "maxPagesPerSource": 10,
  "includeBoosts": true,
  "excludeReplies": false
}

Modes:

• public: read each instance’s public timeline. The default local: true requests local posts; set false to include federated posts known to that instance.
• hashtag: read one timeline per instance and hashtag. A leading # is optional.
• account: read each requested account on each configured instance. accounts accepts a username, @user@domain, or id:13179 for a server-local account ID. Handles use the instance’s anonymous lookup endpoint; a remote account may not be known there. Supply an ID on the correct instance when lookup is unavailable.

Instance inputs accept hostnames or HTTPS origins on port 443, without credentials, paths or query strings. Private/local IP literals are rejected. There is no token or login input. Invalid instance entries become uncharged error rows if a valid instance remains; unusable top-level controls or a selected mode with no valid targets fail with a clear message.

Output example and sample provenance

sample_output.json is an unedited live Mastodon source response, containing two public hashtag statuses fetched on October 5, 2026. It is not a claimed actor dataset export: process-launch restrictions prevented the local actor run. evidence/sample-provenance.json records its URL and retrieval date.

Actual source excerpt from that file:

{
  "id": "117388741522677691",
  "visibility": "public",
  "account": {"acct": "hugovalters"}
}

The dataset fields the actor is designed to emit are listed above. Before publication, run the actor and replace the sample with at most 20 actual dataset items. The default local input requests five public posts from fosstodon.org.

Pricing

Proposed primary event: post, USD 0.0004 per saved distinct post, equivalent to USD 0.40 per 1,000 posts. No custom event is proposed for error rows, empty feeds, filtered statuses or duplicate originals. There is no proposed custom startup fee. Platform usage treatment is not yet configured.

The recorded comparable leader, newpo/mastodon-scraper, charges USD 0.001 per result. See PRICING.md and its dated Store API receipts. These are proposed prices for an unpublished actor.

Limits and rate handling

• maxItems is a global dataset-row cap, including error rows, from 1 to 100,000; default 100.
• concurrency is from 1 to 10 sources; default 3. Requests to one instance are serialized and share a cooldown.
• A request asks for at most 40 statuses. maxPagesPerSource bounds pagination independently; default 10, maximum 1,000.
• HTTP 429, HTTP 5xx and network failures have bounded retries with exponential backoff. Retry-After and exhausted X-RateLimit-Remaining / X-RateLimit-Reset headers set shared instance cooldowns.
• If a server asks for a wait longer than maxRateLimitWaitSecs (default 300), that source stops with an uncharged error row; it is not retried early.
• onlyMedia, includeBoosts, excludeReplies and optional numeric sinceId control collection. Status/account IDs are local to the serving instance.
• The API endpoint and user-defined page cap determine history coverage. This is not a complete archive or a network-wide search. Engagement, federation visibility and remote caches can differ across instances.
• Timelines or account APIs requiring authentication are skipped visibly. Empty public feeds are legitimate. Redirects are not followed; use the canonical HTTPS origin.

Local use and tests

Use the existing environment; do not install packages into the shared virtualenv. The actor requires apify and httpx; pytest is used for tests.

From this actor directory in PowerShell:

$env:APIFY_LOCAL_STORAGE_DIR = "$PWD/storage"
& C:/GritWork/earn/.venv/Scripts/python -m src
& C:/GritWork/earn/.venv/Scripts/python -m pytest -q -m "not live"
& C:/GritWork/earn/.venv/Scripts/python -m pytest -q -m live
apify validate-schema

storage/key_value_stores/default/INPUT.json is included. The actor saves dataset items under local storage and writes RUN_SUMMARY with row/post/error counts, elapsed time and requested post events. Use a fresh storage directory for independent runs to avoid mixing old dataset rows.

The live-marked tests call public timeline, hashtag and account APIs. They require network access and an instance that still exposes the chosen endpoint. Failed startup attempts are in evidence/execution-attempts.json; no passing test or timing claim is made.

FAQ

What limits a run? maxItems caps saved rows and maxPagesPerSource caps each source. Non-public posts and duplicate originals are filtered.

Do I need a proxy or login? No credentials or proxy are configured. An instance may restrict anonymous public timelines or account lookup.

How is it priced? The proposed pay-per-event model charges post for each distinct public post saved. Errors, filtered statuses, and duplicates have no custom post charge.

How are instance rate limits handled? Requests to each instance are serialized and respect its rate headers. If the requested wait exceeds maxRateLimitWaitSecs, that source stops with an error.

How fresh are posts? createdAt and editedAt are source timestamps; fetchedAt is assigned when a status is normalized. Source posts may later be edited or removed.

Can I display contentHtml directly? Treat it as untrusted source content and sanitize it; use text for plain-text processing. Respect content warnings and media rights.

Use with AI agents / MCP

After the owner publishes the actor, an Apify-connected agent can pass this input schema, run the actor and retrieve the default dataset through the output’s dataset link. Ask the agent to keep maxItems bounded, inspect error rows and retain original post URLs for attribution. Feed text, hashtags and counters into summarization or topic analysis; treat public post text as data rather than instructions. This actor does not include a separate MCP server or any model calls.

Verification still required before publication

Run the offline tests, live tests, local actor and exact schema CLI command, then verify the produced dataset and cloud post-event billing. No Docker/cloud run, independent code review or runtime performance measurement has completed in this restricted session.