How to Build a Mastodon Hashtag-Based RSS Feed Using Public API

You want to monitor a specific Mastodon hashtag without logging into an account or refreshing a timeline manually. Mastodon’s public API lets you fetch posts by hashtag in JSON format, and you can convert that data into an RSS feed for your preferred reader. This article walks through the process using the public API endpoint, explains the required parameters, and shows how to generate a valid RSS XML output.

How the Mastodon Public Timeline API Works for Hashtags

Mastodon exposes a RESTful API that does not require authentication for reading public data. The endpoint GET /api/v1/timelines/tag/{hashtag} returns a JSON array of status objects for the given hashtag. Each status object contains the post content rendered as HTML, the account display name and username, the creation timestamp, and the post URL. The API respects the instance’s content and privacy settings, so only public posts that the instance has federated appear in the results.

The base URL for any Mastodon instance is typically https://<instance>.social. For example, using the flagship instance, the full URL becomes https://mastodon.social/api/v1/timelines/tag/technology. The hashtag in the URL does not include the hash symbol. The API returns up to 40 posts by default, and you can set the limit parameter to a value between 1 and 40. For a feed that updates frequently, you may want to request the maximum of 40 posts and then filter or truncate the feed as needed.

Required Data Fields for an RSS Feed

An RSS 2.0 feed requires at least a channel title, description, link, and one or more item elements. Each item should have a title, description, link, and publication date. From the Mastodon status object, you can map these fields:

• Item title: Use the account display name followed by a colon, then the first 80 characters of the content stripped of HTML tags.
• Item description: The full HTML content of the post, optionally sanitized to remove scripts and unwanted tags.
• Item link: The url field of the status object, which points to the post on the originating instance.
• Item publication date: The created_at ISO 8601 timestamp, which you can convert to RFC 822 format for RSS compliance.

Steps to Build the Hashtag RSS Feed

1. Choose a Mastodon instance and verify the API endpoint
   Select a Mastodon instance that federates the hashtag you want to track. Open a browser and navigate to https://<instance>.social/api/v1/timelines/tag/yourhashtag?limit=5. Replace yourhashtag with the exact hashtag text. If the browser displays a JSON array of status objects, the endpoint works. If you see an error, the instance may block public access or the hashtag may contain unsupported characters.
2. Write a script to fetch the JSON data
   Create a Python script using the requests library. Here is a minimal example:
   import requests
url = 'https://mastodon.social/api/v1/timelines/tag/technology?limit=40'
response = requests.get(url)
data = response.json()
   For Node.js, use the node-fetch package. The script should handle HTTP errors and timeouts gracefully.
3. Parse the status objects and extract feed items
   Loop through the JSON array. For each status object, extract the content field, url, created_at, and account.display_name. Strip HTML tags from the content to create a plain-text title. Use a library such as html2text in Python or he in Node.js to decode HTML entities.
4. Generate RSS XML output
   Construct an RSS 2.0 document with a channel element. Set the channel title to something like Mastodon hashtag: technology. The channel link should point to the hashtag page on the instance, for example https://mastodon.social/tags/technology. For each post, create an <item> element. Map the fields as described in the previous section. Use the email library in Python or the rss module in Node.js to format dates in RFC 822.
5. Host the feed as a static XML file or a dynamic endpoint
   Save the output as an .xml file and upload it to a web server. For a feed that updates automatically, set up a cron job (Linux) or Task Scheduler (Windows) to run the script every 15 to 30 minutes. Alternatively, deploy the script as a serverless function on platforms like AWS Lambda or Vercel that returns the RSS XML when accessed.

Common Issues When Building the Feed

The API returns an empty array for a popular hashtag

This usually happens when the instance you are querying does not federate with the instances where the posts originate. Try a different, larger instance such as mastodon.social or mastodon.online. You can also check the hashtag page on the instance’s web interface to confirm posts exist.

RSS feed does not validate in feed readers

Feed readers require strict RSS 2.0 compliance. Common mistakes include missing the <rss> version attribute, using a non-RFC 822 date format, or including raw HTML without proper escaping. Use an XML library to build the document instead of string concatenation. Validate your feed using the W3C Feed Validation Service.

Rate limiting blocks frequent requests

Mastodon instances impose rate limits on API calls. The default limit is 300 requests per 5 minutes per IP. If you run the script more often than every 30 seconds, you may hit the limit. Add a delay between requests and cache the feed output to reduce load. For high-frequency use, consider using a dedicated instance or contacting the admin for a higher limit.

RSS Feed Built Manually vs Using a Third-Party Service

Item	Manual API Script	Third-Party Service
Customization	Full control over item fields, formatting, and update frequency	Limited to the service’s template and update schedule
Cost	Free if you have a web server or serverless function	Often free with ads or paid for premium features
Privacy	Your IP and query patterns stay on your own infrastructure	Service provider logs your hashtag queries and usage
Setup time	30 to 60 minutes for a basic script and deployment	5 minutes to configure an account and select a hashtag
Reliability	Depends on your hosting uptime and script error handling	Service provider manages uptime and API changes

With the manual script approach, you can add advanced features such as filtering posts by language, removing boosts, or embedding media links in the feed description. The third-party service works best when you need a quick, no-code solution for a single hashtag.

You can now build a custom RSS feed for any Mastodon hashtag using the public API and a short script. Test the feed with a local reader like Thunderbird or a web-based service like Feedly to confirm it displays correctly. For a production deployment, add error logging and set up monitoring to restart the script if it fails. Consider extending the feed to include content warnings by reading the spoiler_text field from the status object, which gives you a more complete representation of the post.