> **For coding agents and LLMs:** This is one Social Fetch marketing page (markdown export). For API orientation start with [`/llms.txt`](https://www.socialfetch.dev/llms.txt); for auth and crawl rules use [`/agents.txt`](https://www.socialfetch.dev/agents.txt); for every operation use [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt).

## This page

- **On-site (HTML):** <https://www.socialfetch.dev/platforms/mastodon/timelines-public>
- **Markdown (.mdx) URL:** <https://www.socialfetch.dev/platforms/mastodon/timelines-public.mdx>

---

# 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?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.

## Request

- **Endpoint:** `GET /v1/mastodon/timelines/public`
- **Credits:** 1 credit
Failed requests are free
- **Input:** by server
- **Full reference:** [docs](https://www.socialfetch.dev/docs/api/v1/mastodon/timelines/public/get)
- **Platform page:** [/platforms/mastodon](https://www.socialfetch.dev/platforms/mastodon)

## 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.