How to Use the Mastodon Hashtag API for Trending Lookups

You want to retrieve trending hashtags from a Mastodon instance programmatically, but the standard web interface only shows the top few tags without any filtering or automation. The Mastodon API provides a dedicated endpoint that returns the current trending hashtags, along with their usage history and metadata, enabling you to build custom dashboards, content monitoring tools, or automated posting workflows. This article explains how to authenticate, request the trending tags endpoint, parse the response, and handle common errors when using the Mastodon Hashtag API for trending lookups.

Understanding the Mastodon Trending Hashtags API Endpoint

The Mastodon API exposes a dedicated endpoint at GET /api/v1/trends/tags that returns an array of hashtag objects currently trending on the instance. Each object includes the tag name, a URL to its local timeline, and a history array with daily usage counts for the last seven days. The endpoint is designed to reflect the instance’s local trending algorithm, which considers factors such as the number of posts using the tag within a recent time window, the rate of new posts, and the total post count for that tag.

To use this endpoint, you need a valid access token with the read:trends scope. Without authentication, some instances may return an empty array or a 401 Unauthorized error. The token can be obtained by registering an application on your Mastodon instance and then using OAuth 2.0 to authorize it. The response format is JSON, and each tag object follows this structure:

{
  "name": "mastodon",
  "url": "https://mastodon.social/tags/mastodon",
  "history": [
    {
      "day": "2025-03-20",
      "uses": "1234",
      "accounts": "567"
    },
    {
      "day": "2025-03-19",
      "uses": "1100",
      "accounts": "520"
    }
  ]
}

The history array contains objects for each of the past seven days. The uses field is the total number of posts that used the tag on that day, and the accounts field is the number of unique accounts that posted with the tag. The day field is a date string in YYYY-MM-DD format. The endpoint returns up to 10 trending tags by default, but this limit can be adjusted using the limit query parameter.

Steps to Perform a Trending Hashtag Lookup via the Mastodon API

1. Register a Mastodon application
   Go to your Mastodon instance’s Preferences > Development > New Application. Give your application a name, for example “Trending Hashtag Monitor”. Under Scopes, enable at least read:trends. Click Submit. Copy the Client Key and Client Secret values shown on the next page.
2. Obtain an access token via OAuth
   Use the client credentials to request an access token. Send a POST request to https://yourinstance.com/oauth/token with the following parameters: client_id, client_secret, grant_type=client_credentials, and scope=read:trends. The response will contain an access_token string. Save this token securely.
3. Send a GET request to the trends endpoint
   Using your preferred programming language or API client, send a GET request to https://yourinstance.com/api/v1/trends/tags. Include an Authorization header with the value Bearer YOUR_ACCESS_TOKEN. Optionally, add the limit query parameter to control the number of returned tags, for example ?limit=5.
4. Parse the JSON response
   The response body is a JSON array. Iterate over each object to extract the name and url fields. For trending analysis, process the history array: sum the uses across all days to get total usage, or compare the most recent day’s uses to the previous day’s to detect rising or falling trends.
5. Handle rate limits and errors
   Check the HTTP response status code. A 200 status indicates success. A 401 status means your token is invalid or expired. A 429 status means you have exceeded the rate limit for your instance. In that case, wait for the time specified in the Retry-After header before retrying.

Common Pitfalls When Using the Mastodon Trending API

Empty response or 401 Unauthorized error

If you receive an empty array or a 401 error, verify that your access token includes the read:trends scope. Some instances require authentication even for public endpoints. Also confirm that the token is not expired. Regenerate a new token if needed.

Trending tags differ between instances

Each Mastodon instance computes trending tags independently based on its own local posts. Tags trending on a large instance like mastodon.social may not appear on a smaller instance. To get a broader view, query multiple instances and aggregate the results.

Rate limiting causes intermittent failures

Mastodon instances impose rate limits on API requests. The default limit is 300 requests per 5 minutes per IP address, but this can vary. To avoid hitting the limit, cache the trending data locally and only refresh it every few minutes. Use the Retry-After header to respect backoff periods.

History data uses string values for numbers

The uses and accounts fields in the history array are strings, not integers. When performing calculations, convert them to numbers using parseInt or Number() to avoid string concatenation errors.

Mastodon API vs Third-Party Trending Services

Item	Mastodon API (Built-in)	Third-Party Services (e.g., Trendsmap)
Data source	Single Mastodon instance local posts	Aggregated across multiple instances or platforms
Authentication	Requires OAuth token with read:trends scope	May require API key or paid subscription
History granularity	Daily usage for past 7 days	Often provides hourly or real-time data
Rate limits	Instance-specific, typically 300 req/5 min	Varies by service, often higher limits
Cost	Free (instance resources)	Often paid or freemium

You can now programmatically retrieve trending hashtags from any Mastodon instance using the /api/v1/trends/tags endpoint. Start by registering an application and obtaining an access token with the read:trends scope. To build a more comprehensive trend analysis, consider polling multiple instances and aggregating the history data to detect cross-instance trending patterns. For advanced use, combine the trending tags endpoint with the search API to fetch recent posts for each trending tag and analyze their content.