Skip to content
scrapeatlas.Dashboard

Search X (Twitter) posts

Try in Playground

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.

GET/v1/twitter/search/postsx-api-key
x-api-keystringrequiredheader

Your ScrapeAtlas customer key. Create one on /account/ and set SCRAPEATLAS_API_KEY.

Query parameters
2
querystringrequiredquery

Keyword or phrase to find in public X posts; 1–300 characters.

min 1 chars · max 300 chars

Exampleexample research
cursorstringquery

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.

Response fields
28
requestIdstring

Request correlation identifier.

HTTP attempts, decoded bytes and duration for post discovery and tweet reads.

accounting.upstreamRequestsinteger

Always included.

≥ 0

accounting.responseBytesinteger

Always included.

≥ 0

accounting.durationMsnumber

Always included.

≥ 0

successboolean

True when usable data is returned; inspect status and coverage for omissions.

statusenum

success, partial, failed, or challenged. HTTP 200 can be partial.

one of: success, partial

sourceUrlstring

Search index URL used to discover the returned posts.

absolute HTTPS URL

fetchedAtstring

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.

coverage.sourcestring

Always included.

coverage.completeboolean

Always included.

coverage.warningsstring[]

Always included.

coverage.orderstring

Always included.

querystring

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

posts.__typenamestring

Always included.

posts.rest_idstring

Always included.

Always included.

Always included.

posts.core.user_results.resultobject

Always included.

Always included.

posts.legacy.full_textstring

Always included.

posts.legacy.id_strstring

Always included.

posts.legacy.created_atstring

Always included.

posts.legacy.user_id_strstring

Always included.

posts.urlstring

Always included.

absolute HTTPS URL

cursorstringnullable

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.

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.

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 operation’s response byte budget was exceeded.
502payload_too_complexThe response exceeded the JSON depth or node limits.
502request_limitThe upstream request budget was exhausted.
502upstream_errorNetwork failure, HTTP 5xx after the single retry, or X returned the post without its author and text.
503busyAll retrieval slots are busy.
504timeoutThe operation’s deadline elapsed.