API referenceX
X search
Keyword + (best-effort) geo search.
Geo note: X removed per-tweet coordinates, so true lat/long radius search is
impossible. When latitude/longitude are supplied they are reverse-geocoded to
a country (the reliable place_country: filter) and a primary city; results
are then filtered at city/country granularity per geo_filter. radius_km is
advisory only, there is no coordinate data to apply an exact radius against.
The example response below is real output from this endpoint, not an illustration. Long lists and long strings are shortened to keep the page readable, and each place that happens is marked. This example took 3.4s.
Authorization
ApiKeyAuth X-API-Key<token>
Your API key. Sent on every request.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/scrapers/twitter-search" \ -H "Content-Type: application/json" \ -d '{ "query": "\\"climate change\\" -filter:retweets min_faves:100" }'{ "request_id": "req_8f2c1d94e7b0", "success": true, "status": { "code": "OK", "message": "Scrape completed.", "retryable": false }, "data": { "data": { "additional": { "geo": { "geo_filter": "country", "mention_terms": null, "note": "X no longer exposes per-tweet coordinates, so radius_km is advisory. Results are filtered at country level via place_country.", "requested": { "latitude": null, "longitude": null, "radius_km": 30 }, "resolved_city": null, "resolved_country": null }, "product": "Latest", "query": "\"climate change\" -filter:retweets min_faves:100" }, "main": [ { "author_location": "", "caption": "The shortest version of my economic argument is simple:\n\n- globalisation is ending \n-climate change and resource depletion are real\n- our new technologies don’t produce much growth\n\nGrowth isn’t going up and interest rates aren’t coming down (…without financial repression)", "comment_count": 17, "creator_handle": "meadwaj", "hashtags": [], "in_reply_to_handle": null, "in_reply_to_post_id": null, "is_quote": false, "is_reply": false, "is_repost": false, "lang": "en", "like_count": 200, "location": null, "post_id": "2091436282677260364", "post_url": "https://x.com/meadwaj/status/2091436282677260364", "profile_picture_url": "https://pbs.twimg.com/profile_images/2053564932520579072/LCPdpTtT.jpg", "quoted_post": null, "reposted_post": null, "save_count": 33, "share_count": 22, "thumbnail_url": "", "upload_timestamp": 1787472241, "video_url": "", "video_urls_by_quality": { "high": null, "low": null, "medium": null, "watermarked": null }, "view_count": 10625 }, { "author_location": "", "caption": "🔥 Britain’s UNELECTED Climate Czar Rachel Kyte has flown more than 250,000 air miles, spending taxpayers money attending bollocks conferences discussing climate change projects … also funded by you! \n\nHere’s an incomplete list of some of these gravy train globalist events that haven’t changed the climate !\n\n▪️ Washingt… (+1081 chars)", "comment_count": 122, "creator_handle": "Artemisfornow", "hashtags": [], "in_reply_to_handle": null, "in_reply_to_post_id": null, "is_quote": false, "is_reply": false, "is_repost": false, "lang": "en", "like_count": 1906, "location": null, "post_id": "2091434648005976154", "post_url": "https://x.com/Artemisfornow/status/2091434648005976154", "profile_picture_url": "https://pbs.twimg.com/profile_images/2053230746404323329/eaGD4Zgb.jpg", "quoted_post": null, "reposted_post": null, "save_count": 34, "share_count": 801, "thumbnail_url": "https://pbs.twimg.com/media/HQZEucXWAAApAIc.jpg", "upload_timestamp": 1787471851, "video_url": "", "video_urls_by_quality": { "high": null, "low": null, "medium": null, "watermarked": null }, "view_count": 16804 }, "… 18 more items in the full response" ] }, "hasMore": true, "nextCursor": "DAADDAABCgABHQZGN9tXcEwKAAIdBY3Iv1th8AAIAAIAAAACCAADAAAAAAgABAAAAAAKAAUdBnzRGMAnEAoABh0GfNEYv9jwCwAHAAAA8EVtUEM2d0FBQWZRL2dHSk4wdkdwL0FBQUFCUWRCZFk4ZmxZUWpSMEZqY2kvVzJId0hRWVB2QlFhOGRjZEJqT2l4VlpReVIwRnlrTytWNkc5SFFaR045dFhjRXdkQmRvS2t0WkJueDBGajlTZkY3R21IUVl6Ulk4V01Gc2RCZ2FtUEplUWhoMEZyZEFJbDdFZUhRWEhWNTJXME5NZEJqVk9u… (+108 chars)" }, "error": null, "meta": { "client_id": "client_abc123", "scraper": "twitter-search", "billable": true, "duration_ms": 2639 }}