Social Fetch
Start for freeStart free
Mastodon hub

Mastodon Trending Posts API

What one server's community is sharing most right now, as full post records.

GET /v1/mastodon/trends/posts

1 credit Failed requests are free

Try in playgroundFull API docs

About this endpoint

GET /v1/mastodon/trends/posts?host=mastodon.social returns data.posts, most popular first, with the same fields as any post: contentHtml, text, author, stats (replies, boosts, favourites, quotes), media, hashtags, card and poll. The list is the server's own view, so it differs from server to server.

Trends are cursor-paged: data.page carries hasMore and nextCursor, and you pass nextCursor back as cursor for the next slice. The offset parameter also works. Mastodon orders trends live, so a post can move between requests and appear on two pages; remove repeats by id. limit accepts 1 to 40 and defaults to 20. Servers that turned trends off, and older software that does not offer them, return lookupStatus: unsupported with an empty list.

Mastodon Trending Posts API FAQ

Which posts appear?

The server's own trending selection, most popular first. It reflects that server's community, not a global ranking, so two servers return different lists.

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.

How does cursor paging work?

Read page.hasMore and pass page.nextCursor as cursor for the next slice. Trends can shift between requests, so a shifted list can repeat or skip an item.

Why is the list empty with unsupported?

The server does not offer trending posts, either because the operator turned trends off or the software has no such route. That is not an error and not a missing host.

Other Mastodon endpoints