Mastodon API

Free Mastodon API: public timelines, instance metadata, trending hashtags and account data from any Mastodon server with no key for public endpoints. Tested.

No API key requiredHTTPSFree tier

Endpoint tested and returned HTTP 200 on 2026-08-19

What is the Mastodon API?

The Mastodon API is a free, open API available on every Mastodon instance. Public endpoints — instance metadata, public timelines, trending hashtags and public account data — require no API key or authentication.

Mastodon is decentralised, which changes how you think about its API: there is no single endpoint, but every instance runs the same API at its own domain. Code written against mastodon.social works unchanged against any other server by swapping the hostname.

A good deal is readable without authentication — instance stats, public timelines, trending tags and hashtag feeds. Only user-specific actions like posting or reading a home timeline need OAuth, which makes Mastodon far more accessible than the commercial platforms it replaced.

Quick facts

Base URL: https://mastodon.social/api
Authentication: Public endpoints need no auth. Posting and account-specific reads require OAuth. Each instance sets its own policy.
Rate limit: Typically 300 requests per 5 minutes per IP, configurable per instance.
Pricing: Free and open source.
CORS: Not enabled — call it from your server
Official docs: Read the docs

How to use the Mastodon API

Every request below was executed against the live API on 2026-08-19, and the response shown is the real body it returned — not an illustration.

1. Fetch instance metadata

GET https://mastodon.social/api/v2/instance

curl

curl 'https://mastodon.social/api/v2/instance'

JavaScript (fetch)

const res = await fetch("https://mastodon.social/api/v2/instance");
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const data = await res.json();
console.log(data);

Python (requests)

import requests

res = requests.get("https://mastodon.social/api/v2/instance", timeout=20)
res.raise_for_status()
print(res.json())

Response — HTTP 200 (truncated)

{
  "domain": "mastodon.social",
  "title": "Mastodon",
  "version": "4.7.0-rc.1",
  "source_url": "https://github.com/mastodon/mastodon",
  "description": "The original server of Mastodon, operated by Mastodon GmbH for the common good.\r\n\r\n",
  "usage": {
    "users": {
      "active_month": 269804
    }
  },
  "thumbnail": {
    "url": "https://files.mastodon.social/site_uploads/files/000/000/001/@1x/57c12f441d083cde.png",
    "blurhash": "UeKUpFxuo~R%0nW;WCnhF6RjaJt757oJodS$",
    "versions": {
      "@1x": "https://files.mastodon.social/site_uploads/files/000/000/001/@1x/57c12f441d083cde.png",
      "@2x": "https://files.mastodon.social/site_uploads/files/000/000/001/@2x/57c12f441d083cde.png"
    },
    "description": "Colourful illustration of a Mastodon (a sort of elephant) carrying a bindle and joining a group of other Mastodons. The other Mastodons have many different colours and are holding up a Welcome sign."
  },
  "icon": [
    {
      "src": "https://mastodon.social/packs/assets/android-chrome-36x36-DLiBQg3N.png",
      "size": "36x36"
    },
    {
      "src": "https://mastodon.social/packs/assets/android-chrome-48x48-C7lKWFwX.png",
      "size": "48x48"
    },
    {
      "src": "https://mastodon.social/packs/assets/android-chrome-72x72-9LRpA3QN.png",
      "size": "72x72"
    },
    {
      "src": "https://mastodon.social/packs/assets/android-chrome-96x96-BKKwkkY-.png",
      "size": "96x96"
    },
    {
      "src": "https://mastodon.social/packs/assets/android-chrome-144x144-D-ewI-KZ.png",
      "size": "144x144"
    },
    {
      "src": "https://masto

2. Fetch currently trending hashtags

GET https://mastodon.social/api/v1/trends/tags?limit=2

curl

curl 'https://mastodon.social/api/v1/trends/tags?limit=2'

JavaScript (fetch)

const res = await fetch("https://mastodon.social/api/v1/trends/tags?limit=2");
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const data = await res.json();
console.log(data);

Python (requests)

import requests

res = requests.get("https://mastodon.social/api/v1/trends/tags?limit=2", timeout=20)
res.raise_for_status()
print(res.json())

Response — HTTP 200

[
  {
    "id": "4837659",
    "name": "MeerMittwoch",
    "url": "https://mastodon.social/tags/meermittwoch",
    "history": [
      {
        "day": "1787097600",
        "accounts": "118",
        "uses": "127"
      },
      {
        "day": "1787011200",
        "accounts": "0",
        "uses": "0"
      },
      {
        "day": "1786924800",
        "accounts": "0",
        "uses": "0"
      },
      {
        "day": "1786838400",
        "accounts": "0",
        "uses": "0"
      },
      {
        "day": "1786752000",
        "accounts": "0",
        "uses": "0"
      },
      {
        "day": "1786665600",
        "accounts": "0",
        "uses": "0"
      },
      {
        "day": "1786579200",
        "accounts": "5",
        "uses": "5"
      }
    ]
  },
  {
    "id": "20730707",
    "name": "NewlywedsDisagreeASong",
    "url": "https://mastodon.social/tags/newlywedsdisagreeasong",
    "history": [
      {
        "day": "1787097600",
        "accounts": "64",
        "uses": "278"
      },
      {
        "day": "1787011200",
        "accounts": "0",
        "uses": "0"
      },
      {
        "day": "1786924800",
        "accounts": "0",
        "uses": "0"
      },
      {
        "day": "1786838400",
        "accounts": "0",
        "uses": "0"
      },
      {
        "day": "1786752000",
        "accounts": "0",
        "uses": "0"
      },
      {
        "day": "1786665600",
        "accounts": "0",
        "uses": "0"
      },
      {
        "day": "1786579200",
        "accounts": "0",
        "uses": "0"
      }
    ]
  }
]

Parameters

Parameter	Type	Required	Description
`v2/instance`	path	Optional	Instance metadata, rules and statistics. `v2/instance`
`v1/trends/tags`	path	Optional	Currently trending hashtags. `v1/trends/tags`
`v1/timelines/public`	path	Optional	The public federated or local timeline. `v1/timelines/public`
`limit`	integer	Optional	Number of results on list endpoints. `20`
`local`	boolean	Optional	Restrict a public timeline to that instance only. `true`

Response fields

domainstring: Instance domain.
title / descriptionstring: Instance name and description.
versionstring: Mastodon software version — useful for feature detection.
rulesarray: Instance-specific rules users agree to.
namestring: On trends endpoints, the hashtag name.
historyarray: Per-day usage and account counts for a trending tag.

What you can build with the Mastodon API

Display a public Mastodon timeline or hashtag feed on a website
Track trending topics across the fediverse
Build a cross-instance search or aggregator
Monitor mentions of a brand or topic without platform gatekeeping

Common errors and how to fix them

401

The endpoint requires authentication.

Fix: Only public endpoints work unauthenticated; timelines scoped to a user need an OAuth token.

429

Instance rate limit exceeded.

Fix: Typically 300 requests per 5 minutes. Back off and cache; limits vary by instance.

404 on an instance

That server does not exist, is defederated, or runs different software.

Fix: Not every fediverse server is Mastodon — Pleroma and Misskey have overlapping but different APIs.

Mastodon API — frequently asked questions

Does the Mastodon API need an API key?

Not for public endpoints such as instance metadata, public timelines and trending hashtags. Posting or reading a user's home timeline requires OAuth.

Which instance should I query?

Any. Mastodon is decentralised and every instance exposes the same API at its own domain — swap the hostname and the same code works.

Can I search across the whole fediverse?

Not from one endpoint. Each instance only knows about content it has federated, so cross-fediverse search means querying multiple instances and merging results.

What is the rate limit?

Usually around 300 requests per 5 minutes per IP, but each instance operator can configure it, so do not assume a fixed value.

Tools that pair with this API

JSON Formatter

Format, beautify and minify JSON online with 2-space, 4-space or tab indentation. Sort keys alphabetically and catch syntax errors instantly — free and private.

Word Counter

Count words, characters, sentences, paragraphs and estimated reading time instantly. Free online word counter for essays, blogs and social media.

Mastodon is an independent third-party service and is not affiliated with ByteTools or ByteVancer. Details on this page were verified on 2026-08-19; always check the official documentation before relying on this API in production, as terms and limits can change.