Search X (Twitter) posts
Find public X posts by keyword and retrieve each matching tweet with its author, text, media, engagement counters and original URL. Results are ordered by relevance. Pass the returned cursor to retrieve another result page.
/v1/twitter/search/postsx-api-keyHeaders
Get your API keyYour ScrapeAtlas customer key. Create one on /account/ and set SCRAPEATLAS_API_KEY.
Keyword or phrase to find in public X posts; 1–300 characters.
min 1 chars · max 300 chars
example researchContinuation cursor returned by the previous response (engine and page, for example atlas:2), or null when there is no next page. Pass the value unchanged to request another page.
Request correlation identifier.
HTTP attempts, decoded bytes and duration for post discovery and tweet reads.
Always included.
≥ 0
Always included.
≥ 0
Always included.
≥ 0
True when usable data is returned; inspect status and coverage for omissions.
success, partial, failed, or challenged. HTTP 200 can be partial.
one of: success, partial
Search index URL used to discover the returned posts.
absolute HTTPS URL
UTC retrieval time.
The source is web_search and the result order is relevance; status and warnings describe the returned selection. web_index_fallback means the first index page held no status link and the next index served the posts.
Always included.
Always included.
Always included.
Always included.
Keyword or phrase to find in public X posts; 1–300 characters.
Matching public tweets with their author, text, media, engagement counters and original URLs.
up to 10 items
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
absolute HTTPS URL
Continuation cursor returned by the previous response (engine and page, for example atlas:2), or null when there is no next page. Pass the value unchanged to request another page.
No fields match.
HTTP 200 returns the success variant. Check status: partial means usable data with warnings, and failed or challenged requests carry a failure object described in Errors & responses.
| HTTP | failure.code | Meaning |
|---|---|---|
| 400 | invalid_request | Missing, duplicate, malformed or unsupported parameters, handles or URLs. |
| 401 | unauthorized | Invalid API key. |
| 404 | not_found | Unknown handle, tweet or community. |
| 403 | restricted_page | The account is suspended or unavailable, or the tweet is withheld, protected or age-restricted for logged-out visitors. |
| 429 | upstream_rate_limited | X rate limited guest activation or the GraphQL read. |
| 502 | upstream_challenged | X refused the guest token or the request (status challenged). |
| 502 | operation_unavailable | X no longer serves the pinned persisted query for this operation. |
| 502 | unsafe_redirect | X answered the API request with a redirect. |
| 502 | unsupported_page | The GraphQL result is missing, mismatched or structurally unsupported. |
| 502 | response_too_large | The operation’s response byte budget was exceeded. |
| 502 | payload_too_complex | The response exceeded the JSON depth or node limits. |
| 502 | request_limit | The upstream request budget was exhausted. |
| 502 | upstream_error | Network failure, HTTP 5xx after the single retry, or X returned the post without its author and text. |
| 503 | busy | All retrieval slots are busy. |
| 504 | timeout | The operation’s deadline elapsed. |