Social Fetch
Start for freeStart free
Mastodon hub

Mastodon Profile Directory API

The accounts a server chooses to show: active or newest, local or federated, paged by cursor.

GET /v1/mastodon/directory

1 credit Failed requests are free

Try in playgroundFull API docs

About this endpoint

GET /v1/mastodon/directory?host=mastodon.social returns data.accounts from the server's profile directory. order=active (the default) lists the most recently active first, new lists the newest first. scope=all (the default) includes accounts from other servers, local keeps the server's own accounts. Each account is the same full record the profile route returns, with counters, flags and fields.

The directory only lists accounts whose owner opted in, so it is smaller than the server's user count and says nothing about accounts that opted out. It is cursor-paged: read data.page.hasMore and pass page.nextCursor as cursor for the next slice. The offset parameter also works. Mastodon orders the directory live, so an account can move between requests and appear on two pages; remove repeats by id. limit accepts 1 to 80 and defaults to 40. Servers that switched the directory off return lookupStatus: unsupported.

Mastodon Profile Directory API FAQ

Why are some accounts missing?

The directory only includes accounts whose owner made themselves discoverable. An account that opts out is still reachable by handle, but it is not listed here.

How many credits does a page 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. Each paginated page is a separate billed request.

What do order and scope change?

order=active sorts by recent activity and order=new by join date. scope=all includes remote accounts, scope=local keeps the server's own accounts.

Why is the directory unsupported?

The operator switched the profile directory off, or the software does not offer it. The response is unsupported with an empty list, not an error.

Other Mastodon endpoints