Twitter / X Search Scraper API
Our Twitter search scraper takes a keyword, hashtag, or query and a search tab, then returns the tweets X embeds for that query as structured JSON: text, author, language, and engagement per result. This endpoint is in beta because X aggressively walls logged-out search, so we return what is available and report clearly when a query comes back empty.
Quickstart
curl "https://api.twitterscraperapi.com/api/v1/xtwitter/search?q=nasa&f=top&api_key=$API_KEY"import requests, os
BASE = "https://api.twitterscraperapi.com"
API_KEY = os.environ["API_KEY"]
# Query plus a search tab: top | live | user | image | video.
resp = requests.get(
f"{BASE}/api/v1/xtwitter/search",
params={
"q": "nasa",
"f": "top",
"limit": 20,
"api_key": API_KEY,
},
timeout=30,
)
data = resp.json()
# X walls logged-out search hard, so always check results_count first.
print(data["query"], "->", data["results_count"], "tweets")
for t in data["results"]:
print(t["position"], t["author"], "-", t["full_text"])Response
{
"query": "nasa",
"page": 1,
"results_count": 1,
"total_results": 1,
"results": [
{
"position": 1,
"id": "20",
"title": "just setting up my twttr",
"url": "https://x.com/jack/status/20",
"author": "jack",
"full_text": "just setting up my twttr",
"lang": "en",
"retweet_count": null,
"favorite_count": 308537,
"reply_count": 17947,
"created_at": "2006-03-21T20:50:14.000Z"
}
]
}| Field | Type | Description |
|---|---|---|
query | string | The query that was searched, echoed back from your q input. |
page | integer | The result page number, currently 1 per request. |
results_count | integer | Number of tweets returned in this response. Check this first, since a walled query can return 0. |
total_results | integer | Total tweets parsed from the page before any limit slice was applied. |
results | array | The matched tweets. Each item carries position, id, title, url, author, full_text, lang, created_at, and engagement counts. |
results[].author | string | The screen_name of the tweet's author. |
results[].full_text | string | The tweet body. title carries the same text for cross-category consistency. |
results[].favorite_count | integer or null | Likes on the tweet when X embeds the figure, otherwise null. |
Use it for
Keyword and brand monitoring
Hashtag tracking
Topic and trend sampling
Media discovery
Pricing
| Plan | Price | Best for |
|---|---|---|
| Free | 1,000 requests | Testing and small jobs |
| Pro | $0.60 / 1k | Production workloads |
| Pay-as-you-go | $0.90 / 1k | Spiky or one-off volume |
Median response 2.6s. You only pay for successful requests.
FAQ
What is a Twitter search scraper?
A Twitter search scraper is a tool that runs a keyword, hashtag, or query against X's search and returns the matching tweets in a structured format. Our search endpoint takes a q query and an f tab, fetches X's public search page, parses the tweet objects embedded in its state, and returns them as JSON with text, author, language, and engagement per result.
Why is the search endpoint marked beta?
Because X is one of the most aggressive logged-out walls on the web. A guest request to the search page usually returns a JavaScript shell with a login gate and no tweet data embedded, since results stream in later over X's authenticated API. Our endpoint parses whatever tweets X does embed in the initial page and reports a clear diagnostic when a query comes back empty, so we keep it labelled beta rather than promising a full public search feed.
How do I know if a query returned real results?
Check results_count on the response before reading results. It is the number of tweets we parsed for that query. When X serves only a login shell, results_count is 0 and the response includes a diagnostic noting the page length and which markers were present, so you can tell an empty result apart from a genuine no-match.
Which search tabs are supported?
The f parameter accepts the same tabs X uses on /search: top, live, user, image, and video. It defaults to top. The tab is passed straight through to X, so image and video bias the query toward tweets with media when X embeds them.
Do I need an X developer account or paid API to search?
No. You authenticate with a single twitterscraperapi key. There is no X developer account and no paid X API tier, which for search starts around 100 dollars a month. The free tier includes 1,000 requests. For a reliable single-tweet read, the tweet endpoint is far more consistent than search because it uses X's public syndication payload.
Can I get every tweet for a hashtag?
No tool can guarantee that from logged-out access, and we do not claim to. X only exposes a slice of matching tweets to guests, and often none, so this endpoint returns the tweets embedded in the search page up to your limit rather than a complete historical set. For exhaustive archive search you would need X's paid full-archive API tier.