X · Search
Search Tweets
Write a search, get posts. Costs 3 credits a post
01
Request
POST /api/x/tweets/search with your bearer API key.
Either search or search_url, never both — they are two ways of naming the same page, and a body carrying the pair has said two things and expects one answer.
| search | an advanced-search query, percent-encoded for you |
| search_url | X search URL with q and optional f: top, live, image, or video |
| pagination_token | the previous response’s token; leave out for the first page |
search takes X’s advanced-search syntax — send it exactly as you would type it into the site. The full vocabulary is catalogued at igorbrigadir/twitter-advanced-search, which is the reference worth keeping open while you write one.
| from: to: @ | by author, by recipient, by mention |
| filter: | images, videos, links, quote, replies, nativeretweets, verified |
| since: until: | a date window, inclusive then exclusive |
| min_faves: min_retweets: | engagement floors — negate them for a ceiling |
| lang: url: | language, and links to a domain |
Two warnings from testing rather than from the docs: card_name: no longer returns anything on current X, and anything time-limited — filter:nativeretweets among them — is only indexed for the last week or so, so a date window quietly empties it.
Bare queries use Latest. A search_url selects Top, Latest (f=live), Photos (f=image), or Videos (f=video). X decides which posts are indexed and returned.
Three credits per returned post. Each call fetches one page. X decides how many posts are returned.
If the wallet cannot cover the page, the call fails and its charge is refunded. Send data.pagination.pagination_token unchanged with the same query and tab to continue. A falsehas_next_page and null token mark the end.
02
Response sample
Response example for from:NASA since:2024-01-01 until:2024-06-01
▸ ▾ posts [] — one post from the captured JSON page
[
{
"id": "1750535619095273738",
"url": "https://x.com/NASA/status/1750535619095273738",
"posted_at": "2024-01-25T15:06:29Z",
"text": "Today is our annual Day of Remembrance. \n\n#NASARemembers the crews of Apollo 1, space shuttles Challenger and Columbia, and all members of the NASA family who lost their lives while furthering the cause of exploration and discovery. https://t.co/fR37ROiL1T https://t.co/hzkWnkj7Wk",
"lang": "en",
"author_name": "NASA",
"author_handle": "@NASA",
"author_url": "https://x.com/NASA",
"author_avatar": "https://pbs.twimg.com/profile_images/1321163587679784960/0ZxKlEKB_normal.jpg",
"author_verified": true,
"reply_count": 255,
"reposts": 1244,
"likes": 5380,
"quotes": 117,
"bookmarks": 106,
"views": 847321,
"conversation_id": "1750535619095273738",
"in_reply_to_id": null,
"in_reply_to_user_id": null,
"photos": [],
"videos": [
{
"additional_media_info": {
"description": "",
"embeddable": true,
"monetizable": false,
"title": "NASA Day of Remembrance 2024 – Honoring Our Fallen Heroes"
},
"allow_download_status": {
"allow_download": false
},
"display_url": "pic.x.com/hzkWnkj7Wk",
"expanded_url": "https://x.com/NASA/status/1750535619095273738/video/1",
"ext_media_availability": {
"status": "Available"
},
"id_str": "1749772280308133888",
"indices": [
257,
280
],
"media_key": "13_1749772280308133888",
"media_results": {
"result": {
"media_key": "13_1749772280308133888"
}
},
"media_url_https": "https://pbs.twimg.com/media/GEjCjzbWMAA3hod.jpg",
"original_info": {
"focus_rects": [],
"height": 1280,
"width": 1920
},
"sizes": {
"large": {
"h": 1280,
"resize": "fit",
"w": 1920
},
"medium": {
"h": 800,
"resize": "fit",
"w": 1200
},
"small": {
"h": 453,
"resize": "fit",
"w": 680
},
"thumb": {
"h": 150,
"resize": "crop",
"w": 150
}
},
"type": "video",
"url": "https://t.co/hzkWnkj7Wk",
"video_info": {
"aspect_ratio": [
16,
9
],
"duration_millis": 158725,
"variants": [
{
"content_type": "application/x-mpegURL",
"url": "https://video.twimg.com/amplify_video/1749772280308133888/pl/30d39u6Pw7NqnlUZ.m3u8?tag=14&v=bd0"
},
{
"bitrate": 288000,
"content_type": "video/mp4",
"url": "https://video.twimg.com/amplify_video/1749772280308133888/vid/avc1/480x270/e1o1JbPkkTeAyF7S.mp4?tag=14"
},
{
"bitrate": 832000,
"content_type": "video/mp4",
"url": "https://video.twimg.com/amplify_video/1749772280308133888/vid/avc1/640x360/2FqQ8PTRQdUvf90M.mp4?tag=14"
},
{
"bitrate": 2176000,
"content_type": "video/mp4",
"url": "https://video.twimg.com/amplify_video/1749772280308133888/vid/avc1/1280x720/iU2UEURPHEXk_Ae7.mp4?tag=14"
}
]
}
}
],
"quoted_text": null,
"possibly_sensitive": false,
"context": null,
"quoted_post_id": null,
"reposted_post_id": null,
"hashtags": [
"NASARemembers"
],
"mentions": null,
"links": [
{
"display_url": "nasa.gov/DoR",
"expanded_url": "http://nasa.gov/DoR",
"indices": [
233,
256
],
"url": "https://t.co/fR37ROiL1T"
}
]
}
]▸ ▾ pagination {} — pass the token from your own response unchanged; this example is abbreviated
{
"has_next_page": true,
"pagination_token": "…"
}03
Fields
data.posts is deduplicated by post ID within the page. Promoted posts are excluded. Counts are numbers, IDs are strings, verification is boolean, and text keeps emoji and long content. Missing values are null.
posts []
pagination {}