Skip to content
scrapeatlas.Dashboard

Social networks

Mastodon API

Retrieve public Mastodon profiles, posts, replies, boosts and favourites, followers, hashtags, search, trends and server details.

10 endpointsx-api-key

Ten authenticated endpoints read Mastodon’s public API on 28 major servers and reach accounts on any other server through mastodon.social’s federated view.

API availability: Available

Base URL · local workerhttp://localhost:3044Public API: https://api.scrapeatlas.com.
Authenticationx-api-keyCustomer key from your account. See Authentication.

Endpoints

GET/v1/mastodon/profile

Get a Mastodon profile

Retrieve a public Mastodon account by address or profile URL: names, bio, images, profile fields, verified links, follower/following/post counts and account flags.

Reference
GET/v1/mastodon/user/posts

Get a Mastodon user’s posts

Retrieve up to 40 public posts and boosts from an account, newest first. Filter to original posts, posts without replies, media posts or pinned posts, and page with the returned cursor.

Reference
GET/v1/mastodon/user/connections

Get Mastodon followers or following

Retrieve up to 80 accounts that follow, or are followed by, a public Mastodon account, with each account’s profile and counters. Page with the returned cursor.

Reference
GET/v1/mastodon/post

Get a Mastodon post

Retrieve one public Mastodon post from its URL with content, media, link preview, poll, hashtags, mentions and reply/boost/favourite/quote counts. The author and ID must match the URL.

Reference
GET/v1/mastodon/post/replies

Get Mastodon post replies

Retrieve the conversation around a public Mastodon post: the posts it replies to and up to 60 replies. Rebuild the reply tree from in_reply_to_id.

Reference
GET/v1/mastodon/post/interactions

Get Mastodon post boosts or favourites

Retrieve up to 80 accounts that boosted or favourited a public Mastodon post, with each account’s profile and counters. Page with the returned cursor.

Reference
GET/v1/mastodon/hashtag

Get Mastodon hashtag posts

Retrieve up to 40 recent public posts with a hashtag as a Mastodon server sees them, newest first. The first page adds daily usage for the last seven days.

Reference
GET/v1/mastodon/search

Search Mastodon accounts and hashtags

Search a Mastodon server for accounts or hashtags. Returns up to 40 accounts with profiles and counters, or up to 40 hashtags with daily usage.

Reference
GET/v1/mastodon/trends

Get Mastodon trends

Retrieve what is trending on a Mastodon server: up to 40 posts, 20 hashtags with daily usage, or 20 news links with share history. Page with the returned cursor.

Reference
GET/v1/mastodon/server

Get a Mastodon server

Retrieve a Mastodon server’s public details: title, description, version, monthly active users, languages, rules, registration settings and contact, plus up to 12 weeks of post, login and sign-up counts.

Reference

Quick start

Create an API key on your account page, then call the public API. Values below are placeholders.

Terminal
curl "https://api.scrapeatlas.com/v1/mastodon/profile?handle=example%40mastodon.social" \
  -H "x-api-key: YOUR_API_KEY"

Coverage & limits

  • Independent, stateless worker: eight concurrent operations with a queue of 32 waiting up to 8 seconds; 20-second total deadline including the queue; at most four upstream HTTP requests per operation.
  • Fixed HTTPS origins: the 28 supported Mastodon servers. Caller input becomes a validated path or query value, never a destination. No login, cookies, browser, outbound link visits, media downloads or result storage.
  • Each upstream request is retried at most once, on a network failure, 5xx, broken body or 429; a 429 retry uses a different network identity when one is configured.
  • The worker reads each server’s published rate-limit headers and rests its direct address on a server whose window is nearly spent; with no other identity configured, those requests fail as upstream_rate_limited without contacting the server.
  • At most 4 MiB decoded JSON per operation, depth 32 and 100,000 parsed nodes. Page sizes: 40 posts, 80 accounts, 40 search results, 40 trending posts, 20 trending hashtags or links, 40 ancestors and 60 replies.
  • Posts embed the author’s identity only; follower, following and post counts are returned by profile, connections, interactions and search records. A boost is returned as a thin entry around the boosted post.
  • A bounded in-process map of account address to account ID (5,000 entries, 6-hour lifetime) saves the lookup request on repeat reads; a miss performs the lookup.
Error codes
12
HTTPfailure.codeMeaning
200partialUsable data with federated_view, counters_hidden, reply_limit, ancestor_limit, activity_unavailable or unsupported_*_omitted warnings.
400invalid_requestMissing, duplicate, unsafe or unsupported parameters, a post URL outside the supported servers or an invalid cursor.
401unauthorizedMissing or invalid worker API key.
403restricted_pageThe server does not share this data without login, or the account hides its followers and following.
404not_foundUnknown or removed account, post or hashtag.
429upstream_rate_limitedThe server’s rate limit is exhausted for every available network identity.
502upstream_challengedThe server answered with a challenge or non-JSON page.
502unsupported_pageMalformed, mismatched or looping source data.
502response_too_large payload_too_complexResponse exceeded byte or parsing limits.
502unsafe_redirect request_limit upstream_errorBounded source retrieval could not complete.
503busyAll worker slots and queue places are occupied.
504timeoutTotal request deadline expired.