Mastodon Instance Hashtag Monitor

Monitor public Mastodon conversations from a specific instance without a login.

What does it do?

This Actor collects public hashtag timelines and enriches explicit public account or status URLs. It uses Mastodon's documented v1 API endpoints rather than a browser. Choose an HTTPS instance such as https://mastodon.social and export structured data.

Who is it for?

• Social-listening agencies tracking recurring topics.
• Researchers studying public Fediverse conversations.
• Brand-safety teams reviewing public discussion and engagement.
• Analysts who need repeatable, instance-scoped exports.

Why use it?

Mastodon is federated, so public content lives on individual instances. This Actor keeps the instance visible on every record and follows public timeline pagination. It does not require credentials, cookies, DMs, or remote federated search.

Supported public data

Input	Result
Hashtag	Recent public statuses from that instance
Account URL	Public profile fields and counts
Status URL	One public status with author and media

Unified output dataset

All results are saved to the default dataset. Filter the required recordType column: post is a normalized public status and account is an explicitly requested public profile. This makes mixed monitoring runs exportable without hiding either entity type.

Post rows include contentText, hashtags, mediaAttachments, repliesCount, reblogsCount, favouritesCount, author details, public URL, instance, and timestamp. Account rows include public handle, displayName, bio, profile fields, public counts, bot/locked flags, avatar, header, source URL, and instance. Entity-specific columns are blank when they do not apply. HTML is retained in contentHtml; plain text is available in contentText or noteText.

Quick start

1. Select an HTTPS Mastodon instance.
2. Enter one or more hashtag names without #.
3. Start with a low maxItems value such as 10.
4. Run the Actor, then filter the default dataset by recordType before exporting posts or accounts.
5. Schedule the input for recurring monitoring when the output fits your workflow.

Input: instance URL

instanceUrl must be a plain HTTPS origin, for example https://mastodon.social. All account and status URLs must belong to this same instance. This prevents accidental remote-resolution calls that may require authentication.

Input: hashtags

Use hashtags for public timeline monitoring. Enter technology, not #technology. The Actor requests up to 40 records at a time and follows Mastodon's next-page link until it reaches maxItems or there are no additional public records.

Input: explicit URLs

Use accountUrls for profile links like https://mastodon.social/@Mastodon. Use statusUrls for status links like https://mastodon.social/@name/123456. These are optional and can be combined with hashtags within the shared result cap.

Input: maximum records

maxItems caps combined saved posts and accounts from 1 to 1,000. Keep test runs small, then increase only after confirming your target instance's policies. The cap makes scheduled monitoring predictable and cost-aware.

How much does it cost to monitor Mastodon hashtags?

The Actor charges a small start event and a tiered event for each saved public record. Pricing follows your Apify subscription tier; the current run page is authoritative. A record is charged only after it has been saved to the unified default dataset. Start with a small run to estimate the volume from your selected instance.

Pagination and freshness

Hashtag timelines use Mastodon's public max_id pagination exposed through Link headers. Results are newest-first as supplied by the instance at run time. The Actor does not deduplicate across separate scheduled runs; use status IDs downstream. Every output record has a scrapedAt timestamp for auditability.

Errors and rate limits

Instances can disable public endpoints or apply their own rate limits. The Actor reports the endpoint and HTTP status for 401, 403, 429, and other failures. A 429 means wait before retrying with fewer inputs; it is not solved by authentication here. Do not use this Actor for private, follower-only, or direct-message data.

Integrations

• Filter recordType=post and send those records to a warehouse for topic trend analysis.
• Use a scheduled task and webhooks to flag new posts mentioning a campaign keyword.
• Join accountAcct and engagement fields in a BI dashboard.
• Filter mediaAttachments before passing candidate posts to a moderation workflow.

API usage: Node.js

import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/mastodon-instance-hashtag-monitor').call({
  instanceUrl: 'https://mastodon.social', hashtags: ['technology'], maxItems: 25,
});
console.log(await client.dataset(run.defaultDatasetId).listItems());

API usage: Python

from apify_client import ApifyClient
client = ApifyClient('APIFY_TOKEN')
run = client.actor('automation-lab/mastodon-instance-hashtag-monitor').call(run_input={
    'instanceUrl': 'https://mastodon.social', 'hashtags': ['technology'], 'maxItems': 25,
})
print(list(client.dataset(run['defaultDatasetId']).iterate_items()))

API usage: cURL

curl "https://api.apify.com/v2/acts/automation-lab~mastodon-instance-hashtag-monitor/runs?token=$APIFY_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"instanceUrl":"https://mastodon.social","hashtags":["technology"],"maxItems":25}'

MCP

Use this Actor from Claude Desktop or Claude Code through Apify MCP. Add it in Claude Code with:

$claude mcp add --transport http apify https://mcp.apify.com?tools=automation-lab/mastodon-instance-hashtag-monitor

For a JSON configuration, use:

{"mcpServers":{"apify":{"type":"http","url":"https://mcp.apify.com?tools=automation-lab/mastodon-instance-hashtag-monitor"}}}

Example prompt: “Monitor public technology and opensource posts on mastodon.social and summarize engagement.” Only submit public, instance-scoped URLs and hashtags.

Responsible use and legality

Collect only public data you are entitled to process. Respect instance rules, applicable privacy law, and the context of profile information. Do not use this tool to access private content, bypass access controls, or identify people. Review and comply with each target instance's terms before scheduling large exports.

Limitations

Mastodon is federated: endpoint availability, retention, and rate limits vary by instance. This MVP intentionally does not authenticate, search remote federated resources, read DMs, or request follower-only statuses. A successful public API response is not a completeness claim. Content can be deleted or edited after collection.

Tips for reliable monitoring

Keep one instance per run and retain id, url, instance, and scrapedAt downstream. Use exact public URLs rather than attempting account discovery. Schedule several focused hashtag inputs instead of a single oversized catch-all run. If a timeline is empty, verify the tag has public posts on the chosen instance first.

Troubleshooting

Why did I get HTTP 401 or 403? The selected instance has restricted that endpoint; choose public content on an instance that permits it rather than adding credentials.

Why did I get HTTP 429? The instance rate-limited the request. Wait and retry later with a smaller input. The Actor does not bypass rate limits.

Why are account URLs rejected? Account and status URLs must be HTTPS and on instanceUrl. This is intentional so a run never invokes unauthenticated remote search.

FAQ

Does it search all of Mastodon? No. It monitors one explicit instance per run.

Can it read private posts or DMs? No. It only calls public v1 API endpoints.

Can I use a hashtag with #? Yes, the Actor removes a leading # automatically.

Are media files downloaded? No. Public media metadata and URLs are saved.

Related scrapers

For other public social workflows, browse Automation Lab actors. This Actor is purpose-built for instance-scoped Mastodon monitoring rather than broad cross-network discovery. Use it alongside your approved analytics and moderation tools.

Changelog

See .actor/CHANGELOG.md for user-facing release notes.

Support boundaries

When reporting a problem, include the instance origin, endpoint type, HTTP status, and a sanitized example input. Never include access tokens or private content in a support request. Public endpoint behavior is ultimately controlled by each Mastodon instance administrator.

Data retention

Save only the fields required for your approved research or monitoring purpose.