Skip to content
scrapeatlas.Dashboard

Social networks

X (Twitter) API

Retrieve public X (Twitter) profiles, a user's ranked public tweets, single tweets and communities exactly as X's own web client receives them, without an account.

4 endpointsx-api-key

Retrieve public X profiles, tweets, timelines and communities, with optional compact records.

API availability: Coming soon

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

Endpoints

GET/v1/twitter/profile

Get an X (Twitter) profile

Retrieve a public X profile by handle: the raw UserByScreenName user object with identity, bio, entities, counters, images, verification and affiliation labels, tip jar, highlights and business fields.

Reference
GET/v1/twitter/user-tweets

List an X (Twitter) user's public tweets

Retrieve a profile's public tweets in ranked order, including its pinned tweet, with a URL for each tweet.

Reference
GET/v1/twitter/tweet

Get an X (Twitter) tweet

Retrieve one public tweet by permalink: the raw TweetResultByRestId tweet object with its author, text, entities, media, quoted or retweeted tweet, note text for long posts, engagement counters and views.

Reference
GET/v1/twitter/community

Get an X (Twitter) community

Retrieve a public X community by URL: the raw CommunityQuery object with name, description, member count, join policy, rules, creator, banners, member face pile and trending hashtags.

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/twitter/profile?handle=example" \
  -H "x-api-key: YOUR_API_KEY"

Coverage & limits

  • Independent worker on port 3036, TWITTER_API_KEY in x-api-key. No X account, login, cookie, storage, media download or product dependency; the public web-client bearer plus a fresh guest token per request is what a logged-out x.com visitor sends.
  • Four concurrent operations, 20-second deadline, at most four upstream requests per operation (guest activation, one or two GraphQL reads and one shared transient retry for network failures or HTTP 5xx). Challenges, rate limits and 4xx answers are never retried.
  • 4 MiB decoded response per operation, 400,000 JSON nodes, 64 levels, 200 tweets per timeline (X serves about 100 to guests).
  • The user-tweets timeline is X's ranked selection of about 100 public tweets with the pinned tweet first. Skipped cursor, module, promoted and unavailable entries are reported as coverage warnings.
  • Guest tokens call these four persisted documents.
  • Query IDs are pinned; when X retires one, the operation fails operation_unavailable instead of guessing.
  • Handles are 1–15 word characters (leading @ accepted), tweet URLs are x.com or twitter.com status permalinks (query strings and fragments ignored), community URLs are https://x.com/i/communities/{id}. Identity is verified against the request; mismatches fail unsupported_page.
  • Optional TWITTER_PROXY_URL (falling back to TWITCH_PROXY_URL, then REDDIT_PROXY_URL) routes every request through a fresh residential proxy session when the host's address is refused by X.
Error codes
15
HTTPfailure.codeMeaning
400invalid_requestMissing, duplicate, malformed or unsupported parameters, handles or URLs.
401unauthorizedInvalid API key.
404not_foundUnknown handle, tweet or community.
403restricted_pageThe account is suspended or unavailable, or the tweet is withheld, protected or age-restricted for logged-out visitors.
429upstream_rate_limitedX rate limited guest activation or the GraphQL read.
502upstream_challengedX refused the guest token or the request (status challenged).
502operation_unavailableX no longer serves the pinned persisted query for this operation.
502unsafe_redirectX answered the API request with a redirect.
502unsupported_pageThe GraphQL result is missing, mismatched or structurally unsupported.
502response_too_largeThe response exceeded 4 MiB.
502payload_too_complexThe response exceeded the JSON depth or node limits.
502request_limitThe upstream request budget was exhausted.
502upstream_errorNetwork failure or HTTP 5xx after the single retry.
503busyAll retrieval slots are busy.
504timeoutThe 20-second deadline elapsed.