Social Fetch
Start for freeStart free
Mastodon hub

Mastodon Search API

Search one server for accounts, hashtags or posts, with the same typed records as the lookup routes.

GET /v1/mastodon/search

1 credit Failed requests are free

Try in playgroundFull API docs

About this endpoint

GET /v1/mastodon/search?host=mastodon.social&q=gargron searches one server. Without type, the server returns accounts and hashtags; type=accounts, type=hashtags and type=posts narrow it. The answer is always the same shape: data.query, data.type, data.accounts, data.hashtags and data.posts, with full records for whatever matched.

Post search is the exception. Mastodon keeps post search for logged-in users, so type=posts returns lookupStatus: restricted with reason.code: login_required on those servers; Pleroma, Akkoma and some other software answer it. Search has no paging: limit accepts 1 to 40 and defaults to 20, and there is no cursor or offset. Search is local to the server, so the same query gives different results elsewhere.

Mastodon Search API FAQ

Why does post search return restricted?

Mastodon keeps post search for logged-in users. On those servers type=posts comes back restricted with reason.code login_required rather than an empty success. Pleroma and Akkoma can answer it.

How many credits does a search cost?

Pricing is documented on the operation in the API registry (shown on this page). Confirm on every response with meta.creditsCharged: that field is the billing source of truth.

Can I page through results?

No. Servers do not offer paging for public search. limit accepts 1 to 40 and defaults to 20, and the response has no page object.

What can I search for?

q is free text up to 300 characters. Without type the server returns accounts and hashtags. Use type to ask for accounts, hashtags or posts only.

Are results global?

No. Search runs against one server's index, which covers accounts and posts that server knows. Search another server for a different view.

Other Mastodon endpoints