How to Use the Mastodon Tag Following API for Automation

Mastodon users can follow hashtags to see public posts that include those tags in their home feed. This feature helps you monitor topics without manually searching or adding every user who posts about them. The Tag Following API exposes this functionality programmatically, allowing automation scripts to follow or unfollow tags for a given user account. This article explains how to authenticate with the Mastodon API, locate the correct endpoint, and write a basic script to follow or unfollow a hashtag.

What the Tag Following API Does and What You Need Before Using It

The Mastodon Tag Following API is part of the REST API v1. It lets you manage which hashtags your account follows. When you follow a hashtag, your home feed shows public posts that use that tag, as long as they come from accounts on your instance or are boosted by someone you follow.

Before you start, you need the following:

• A Mastodon account on any instance that supports API access (most do)
• An application registered on that instance to obtain an access token
• The access token with the read and write:follows scopes
• Basic familiarity with HTTP requests and a tool like curl or a programming language such as Python

The API endpoint for following a tag is POST /api/v1/tags/:id/follow, where :id is the URL-encoded name of the tag (without the leading #). For example, to follow the tag python, you call POST /api/v1/tags/python/follow. The response returns a Tag object with the following attribute set to true.

Unfollowing uses POST /api/v1/tags/:id/unfollow and returns the Tag object with following set to false. To list all tags you follow, call GET /api/v1/followed_tags with pagination support.

Steps to Automate Tag Following and Unfollowing

The following steps assume you have already registered an application and obtained an access token. If you have not done that, see the Mastodon API documentation for creating an app and requesting an OAuth token with the read and write:follows scopes.

1. Identify the tag name
   Decide which hashtag you want to follow or unfollow. Write the tag name without the # symbol. For instance, if the tag is #mastoadmin, use mastoadmin in the API call.
2. Construct the API endpoint URL
   Your instance base URL is something like https://mastodon.example. Append the endpoint path. For following: https://mastodon.example/api/v1/tags/mastoadmin/follow. For unfollowing: https://mastodon.example/api/v1/tags/mastoadmin/unfollow.
3. Set the Authorization header
   Every API call must include the header Authorization: Bearer YOUR_ACCESS_TOKEN. Replace YOUR_ACCESS_TOKEN with the token you obtained from your app.
4. Send the POST request
   Use curl or your preferred HTTP library. For curl, the command looks like this:
   curl -X POST "https://mastodon.example/api/v1/tags/mastoadmin/follow" -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
   The response JSON contains the tag object. Look for the following field. If it is true, the operation succeeded.
5. Verify the result
   To confirm the tag is now followed, call GET /api/v1/followed_tags with the same Authorization header. The response is an array of tag objects. Check that your tag appears in the list.

Python Script Example

The following Python script uses the requests library to follow a tag:

import requests

INSTANCE = "https://mastodon.example"
TOKEN = "YOUR_ACCESS_TOKEN"
TAG = "mastoadmin"

headers = {"Authorization": f"Bearer {TOKEN}"}
url = f"{INSTANCE}/api/v1/tags/{TAG}/follow"
response = requests.post(url, headers=headers)

if response.status_code == 200:
    data = response.json()
    print(f"Following tag: {data['following']}")
else:
    print(f"Error {response.status_code}: {response.text}")

Replace the placeholders with your instance URL and token. Run the script. The output shows whether the tag is now followed.

Unfollowing a Tag via Script

To unfollow, change the endpoint from /follow to /unfollow:

url = f"{INSTANCE}/api/v1/tags/{TAG}/unfollow"
response = requests.post(url, headers=headers)

The script works identically. After running it, the following field in the response is false.

Common Mistakes, Limitations, and Things to Avoid

Using the Wrong HTTP Method

The follow and unfollow endpoints require POST requests. Using GET returns a 404 or 405 error. Always verify your HTTP method before sending the request.

Missing or Incorrect Scopes

If your access token lacks the write:follows scope, the API returns a 403 Forbidden error. When you create the app, explicitly request the read and write:follows scopes. Regenerate the token if necessary.

Tag Name Encoding

If the tag contains special characters such as spaces or non-ASCII letters, you must URL-encode the tag name. For example, a tag #machine learning becomes machine%20learning in the endpoint path. Most HTTP libraries handle this automatically if you pass the tag name as a parameter.

Rate Limiting

Mastodon instances enforce rate limits on API calls. Following or unfollowing many tags in rapid succession may cause temporary blocks. Space your requests at least one second apart. Check the X-RateLimit-Remaining header in the response to monitor your quota.

Following a Tag That Does Not Exist

The API does not validate whether the tag has ever been used. You can follow a tag that has no posts. This is not an error, but it will not add any content to your feed until someone posts with that tag.

Mastodon API Methods for Tag Management

Item	Follow Tag	Unfollow Tag	List Followed Tags
HTTP Method	POST	POST	GET
Endpoint	/api/v1/tags/:id/follow	/api/v1/tags/:id/unfollow	/api/v1/followed_tags
Required Scope	write:follows	write:follows	read
Response	Tag object with following: true	Tag object with following: false	Array of Tag objects
Idempotent	Yes (repeating has no extra effect)	Yes	Yes

The table shows that both follow and unfollow use POST and require the same scope. The list endpoint uses GET and requires only the read scope. None of these operations are destructive beyond changing the follow state.

Now you can write automation scripts that manage hashtag subscriptions on Mastodon. Start by testing the API with a single tag using curl. After that, expand your script to follow a list of tags from a configuration file. For advanced scenarios, use the max_id and since_id pagination parameters on the followed_tags endpoint to process large lists efficiently.