How to Track Mastodon Hashtag Trends Over Time With API

You want to monitor how often a hashtag is used on Mastodon over days or weeks. Mastodon does not offer a built-in trend graph for hashtags inside the web interface. The Mastodon API provides the raw data you need to build your own tracking system. This article explains how to use the API to collect hashtag usage counts and store them for trend analysis.

Understanding the Mastodon API for Hashtag Tracking

Mastodon exposes a RESTful API that returns JSON data. For hashtag tracking, two endpoints are relevant. The /api/v1/trends/tags endpoint returns a list of currently trending hashtags with a history array that contains daily usage counts for the past 7 days. Each history entry includes day (Unix timestamp), uses (number of posts), and accounts (number of unique accounts).

The /api/v1/timelines/tag/:hashtag endpoint returns individual posts for a specific hashtag. You can paginate through these to count total posts per day. However, the trends endpoint is more efficient for trend tracking because it provides pre-aggregated daily counts.

To track trends over time longer than 7 days, you must collect snapshots of the trends endpoint at regular intervals, such as once per day. Store the returned history data in a database or CSV file. Over time, you will accumulate a dataset that shows how hashtag usage changes.

Prerequisites for Using the API

You need a Mastodon account on any instance. Generate an access token from Preferences > Development > New Application. Set the scope to read:search and read:statuses for hashtag timeline access. For the trends endpoint, the read:trends scope is required. No write scopes are needed because you are only reading public data.

You also need a programming environment. This guide uses Python 3 with the requests library. Install it with pip install requests. You will also need a way to store data, such as SQLite or a plain text file.

Steps to Collect Hashtag Trend Data Using the API

The following method uses the /api/v1/trends/tags endpoint to get daily usage counts for trending hashtags. You will write a Python script that fetches the data, extracts the history for your target hashtag, and appends it to a CSV file.

1. Create a new Python script file
   Open a text editor and create a file named track_hashtag.py. This script will contain all the logic for fetching and storing trend data.
2. Set your instance URL and access token
   At the top of the script, define variables for your Mastodon instance and the access token you generated. Example: instance = 'https://mastodon.social' and token = 'your_token_here'. Never share or commit this token to a public repository.
3. Define the API endpoint for trending tags
   Build the full URL: url = f'{instance}/api/v1/trends/tags'. Add the authorization header: headers = {'Authorization': f'Bearer {token}'}.
4. Send a GET request to the endpoint
   Use the requests.get method: response = requests.get(url, headers=headers). Check that response.status_code == 200 before processing the data.
5. Parse the JSON response
   The response is a list of tag objects. Each object has a name field and a history field. Loop through the list to find your target hashtag. Example: for tag in response.json(): if tag['name'] == 'mastodon': data = tag.
6. Extract the daily history for the target hashtag
   The history array contains objects with day, uses, and accounts. Convert the day Unix timestamp to a readable date using datetime.datetime.fromtimestamp(int(day)). Store each day’s uses count.
7. Append the data to a CSV file
   Open a CSV file in append mode. Write a header row if the file does not exist. Each row should contain the date, hashtag name, and uses count. Example: 2025-03-20,mastodon,142. Close the file after writing.
8. Schedule the script to run daily
   Use your operating system’s task scheduler. On Windows, use Task Scheduler. On Linux or macOS, use cron. Set the script to run once per day at the same time to capture consistent daily snapshots.

After running the script for several days, open the CSV file with spreadsheet software. You can graph the date column against the uses column to visualize the trend line.

Common Issues When Tracking Hashtag Trends With the API

Hashtag Not Appearing in the Trends Endpoint

The /api/v1/trends/tags endpoint only returns hashtags that are currently trending on the instance. If your hashtag has low usage, it may not appear. Switch to the timeline endpoint /api/v1/timelines/tag/:hashtag and count the posts yourself. Paginate through all pages using the Link header until you reach the end. Sum the total number of posts returned. This method is slower but works for any hashtag.

Rate Limits Blocking Frequent Requests

Mastodon instances enforce rate limits, typically 300 requests per 5 minutes per IP or token. If you make too many requests, the API returns HTTP 429. Check the response headers X-RateLimit-Remaining and X-RateLimit-Reset. Wait for the reset time before making another request. In your script, add a time.sleep delay between requests if you are paginating through many pages.

History Data Only Covers 7 Days

The trends endpoint provides history for the past 7 days. To track longer periods, you must collect data daily and merge it. Keep your CSV file and append new rows each day. When analyzing, remove duplicate date entries for the same hashtag by keeping only the most recent snapshot for each day.

Item	Trends Endpoint	Timeline Endpoint
Endpoint path	/api/v1/trends/tags	/api/v1/timelines/tag/:hashtag
Data provided	Pre-aggregated daily counts for trending hashtags only	Individual posts for any hashtag, requires manual counting
History length	7 days	Depends on pagination, up to 40 posts per page
Rate limit impact	1 request per check	Multiple requests to paginate through all posts
Best use case	Tracking popular hashtags with high usage	Tracking low-usage or niche hashtags

You can now collect hashtag usage data from Mastodon using the API and store it for trend analysis. Start with the trends endpoint for popular hashtags to get pre-aggregated daily counts. For niche hashtags, use the timeline endpoint and paginate through results. To visualize trends, import your CSV into a charting tool or spreadsheet. As an advanced step, set up the script to run multiple times per day and average the counts to smooth out hourly fluctuations.