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 19 Aug 2026

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 19 Aug 2026, 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.

Alternatives to Mastodon API

If Mastodon does not fit, these social media apis cover similar ground. Every one was called before publishing, and each links to its own reference page with a working curl command and the response it returned.

API	What it does	Auth	CORS	Last verified
Lemmy	Free Lemmy API with no key: posts, comments, communities and site data from any federated Lemmy instance. A Reddit-style API without gatekeeping. Tested.	No key	No	19 Aug 2026
DEV Community	Free DEV.to API with no key for public content: articles, tags, users and comments from the developer community platform. Tested curl example and live JSON.	No key	Yes	19 Aug 2026
Bluesky Public API	Free Bluesky public API with no key: profiles, posts, followers and feeds from the AT Protocol network. No authentication for public data. Tested example.	No key	Yes	19 Aug 2026
Microlink	Free link preview API with no key for basic use: extract title, description, image, author and favicon from any URL. Powers unfurl previews. Tested example.	No key	Yes	19 Aug 2026
joinmastodon Servers	Free Mastodon server directory API with no key: browse vetted fediverse instances with user counts, languages, categories and open registration status. Tested.	No key	Yes	20 Aug 2026
Matrix Client-Server Versions	Free unauthenticated Matrix endpoint listing the spec versions and unstable features a homeserver supports — the first call any Matrix client makes. Tested example included.	No key	Yes	21 Aug 2026

All Social Media APIs

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