Social Fetch
Start for freeStart free
Mastodon hub

Mastodon Public Timeline API

A server's live public feed, filtered to local or remote accounts, paged with a cursor.

GET /v1/mastodon/timelines/public

1 credit Failed requests are free

Try in playgroundFull API docs

About this endpoint

GET /v1/mastodon/timelines/public?host=fosstodon.org returns the server's public timeline, newest first, in data.posts. scope=all (the default) is everything the server shows, local keeps the server's own accounts and remote keeps accounts from other servers. mediaOnly=true keeps posts with an attachment.

About a third of servers restrict the public timeline. Those come back lookupStatus: restricted, with reason.code and, when the server reports it, declaredAccess holding the operator's local and remote settings. Follow page.nextCursor while page.hasMore is true; limit accepts 1 to 40 and defaults to 20. The timeline shows what the server shows, so two servers return different posts.

Mastodon Public Timeline API FAQ

Why is the public timeline restricted?

The operator set the timeline to authenticated or disabled, so it is not public. reason.code says which, and declaredAccess reports the local and remote settings on Mastodon 4.5 and later.

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 is the difference between all, local and remote?

all is everything the server shows, local keeps posts from accounts on that server, and remote keeps posts from accounts on other servers.

How do I page through the timeline?

Pass page.nextCursor from the previous response while page.hasMore is true. limit accepts 1 to 40; each page is a separate billed request. New posts do not shift the cursor.

Other Mastodon endpoints