Mastodon API

Read posts, accounts, hashtags and trends from any Mastodon server as clean JSON.

The API.SH Mastodon API returns public data from any Mastodon server, or other fediverse server running the Mastodon API, as structured JSON. Look up an account and its followers, following and posts; open a post and its full reply thread; read hashtag and public timelines; see what is trending; search accounts and hashtags; and get a server's details, rules and monthly active users.

Get a free API key Try it in the playground

11 endpoints
from $1 / 1,000 calls
1,000 free credits / month
failed calls free

Mastodon search

GET https://api.api.sh/mastodon/v1/search

{ "success": true }

1 credit · $1 per 1,000 calls

What you can build with the Mastodon API

Hashtag and topic monitoring

Follow a hashtag timeline on one or more servers, combined with other tags, to collect public posts on a topic as they appear.

/tag /timeline

Trend tracking across servers

Read trending hashtags, posts and news links per server, with daily uses and shares for the last week.

/trends

Account and audience analysis

Pull an account's profile, posts, followers and following to study reach, posting habits and who engages.

/account /statuses /followers /following

Conversation research

Open a post with its ancestors and every public reply to study how a discussion unfolds.

/status /status/replies

Fediverse server directories

Collect each server's title, version, languages, monthly active users, registration status and rules.

/instance

Finding accounts to follow

Search a server's accounts and hashtags for a keyword and return their profiles.

/search

Mastodon data you get

Field names from real responses. Numbers come parsed, URLs absolute, dates in ISO 8601.

Mastodon API endpoints and prices

Every Mastodon endpoint costs 1 credit per call: credits are $1 per 1,000 on a monthly plan, $2 pay-as-you-go. Pricing

Search and discovery2

Mastodon search /mastodon/v1/search	$1 · $2 PAYG 1 credit
Mastodon trends /mastodon/v1/trends	$1 · $2 PAYG 1 credit

Profiles and accounts2

Mastodon account /mastodon/v1/account	$1 · $2 PAYG 1 credit
Mastodon account posts /mastodon/v1/statuses	$1 · $2 PAYG 1 credit

Posts and media2

Mastodon post /mastodon/v1/status	$1 · $2 PAYG 1 credit
Mastodon post replies /mastodon/v1/status/replies	$1 · $2 PAYG 1 credit

More data5

Mastodon followers /mastodon/v1/followers	$1 · $2 PAYG 1 credit
Mastodon following /mastodon/v1/following	$1 · $2 PAYG 1 credit
Mastodon server info /mastodon/v1/instance	$1 · $2 PAYG 1 credit
Mastodon hashtag timeline /mastodon/v1/tag	$1 · $2 PAYG 1 credit
Mastodon public timeline /mastodon/v1/timeline	$1 · $2 PAYG 1 credit

Call the Mastodon API

Mastodon search: GET https://api.api.sh/mastodon/v1/search

curl "https://api.api.sh/mastodon/v1/search?q=photography" \
  -H "x-api-key: $APISH_KEY"

import os, requests

res = requests.get(
    "https://api.api.sh/mastodon/v1/search",
    params={"q": "photography"},
    headers={"x-api-key": os.environ["APISH_KEY"]},
    timeout=120,
)
res.raise_for_status()
data = res.json()

const url = new URL("https://api.api.sh/mastodon/v1/search");
url.searchParams.set("q", "photography");

const res = await fetch(url, { headers: { "x-api-key": process.env.APISH_KEY } });
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const data = await res.json();

# Google Sheets (API.SH add-on)
=APISH("/mastodon/v1/search", "q", "photography")

# Zapier, Make, n8n (verified node): pick the API.SH app,
# choose "Mastodon" and "Mastodon search".

# AI agents (Claude, ChatGPT, Cursor): add the
# API.SH MCP server https://api.sh/mcp

Create a free accountConfirm your email and get 1,000 free credits every month. No card needed.
Create an API keyOne key works for all 482 platforms.
Send the requestJSON back in one call. Add output=csv or output=ndjson for files.

Why API.SH for Mastodon data

Public data only: no Mastodon login, cookies or account needed
One key and one response shape for Mastodon and 481 other platforms
Built and maintained by API.SH, not third-party publishers
Pay per call; errors on our side cost nothing
Live status for every endpoint

API.SH vs the official Mastodon API

Yes. Mastodon has an open, documented REST API on every server, and many read methods work without a login, with libraries for Python, Ruby and JavaScript. API.SH adds one key that works across servers by handle, flattened JSON in the same shape as its other social sites, cursor paging and no-code tools, without registering an app on each server.

Instead of writing a Mastodon scraper or wiring Mastodon.py per server, call one API.SH endpoint per question with fixed pricing and one JSON format across social platforms.

Mastodon API questions

What Mastodon data can I get?+

Accounts (/mastodon/v1/account), followers and following (/mastodon/v1/followers, /mastodon/v1/following), account posts (/mastodon/v1/statuses), one post and its replies (/mastodon/v1/status, /mastodon/v1/status/replies), hashtag and public timelines (/mastodon/v1/tag, /mastodon/v1/timeline), trends (/mastodon/v1/trends), search (/mastodon/v1/search) and server info (/mastodon/v1/instance).

How much does the Mastodon API cost?+

Every Mastodon endpoint costs 1 credit per call. On a monthly plan 1,000 credits cost $1 (Starter is $50/month for 50,000 credits). Pay-as-you-go is $2 per 1,000 credits, with top-ups from $15 that never expire.

Is there a free trial?+

Yes. Every account gets 1,000 free credits every month. That is 1,000 calls to /mastodon/v1/account at 1 credit each.

Is there an official Mastodon API?+

Yes. Every Mastodon server exposes the documented Mastodon REST API, and it is free to use within each server's limits. API.SH is a convenience layer: one key for every server, the same JSON shape as other platforms, and SDKs, Sheets, Zapier and MCP support.

Do I need a Mastodon account or API key?+

No. API.SH reads public data only and needs just your API.SH key. Searching post text needs a login on Mastodon, so /mastodon/v1/search covers accounts and hashtags. Servers that keep timelines for members only answer 403.

Which servers does it work with?+

Any server running Mastodon or the Mastodon API. Pass an account as user@server, a post url, or the instance name for timelines, trends, search and server info.

Can I use it from Python?+

Yes. Use the Python SDK or any HTTP client. For example, call /mastodon/v1/statuses with acct and pass next_cursor back as cursor to page through an account's posts.

How do I get started?+

1. Sign up at api.sh. 2. Copy your API key. 3. Call /mastodon/v1/account with acct set to a handle such as user@mastodon.social. Docs are at https://api.sh/docs, with JS and Python SDKs, Google Sheets, Zapier, Make, n8n and the MCP server at https://api.sh/mcp.