How to search recent posts with the X API
Short answer
Call GET https://api.x.com/2/tweets/search/recent with a query built from operators such as from:, -is:retweet and lang:. It searches the last 7 days, returns up to 100 posts per request, accepts queries up to 512 characters, and gives you a next_token in meta to fetch the next page.
Key takeaways
- Recent search covers 7 days; full-archive search goes back to March 2006 but needs pay-per-use or Enterprise access.
- Queries are limited to 512 characters on recent search, so operators matter more than long keyword lists.
- Excluding retweets with
-is:retweetis usually the first filter to add. - Pagination uses
next_token; stop when the response no longer includes one. - Reads are billed per returned post, so a tight query is also a cheap one.
Search is the endpoint most small tools need sooner or later: a mention tracker, a keyword alert, a dashboard for a launch hashtag. The X API offers two search endpoints, and for most personal tools the recent one is enough. Here is how to call it, how to write queries that return what you want, and how to page through results without paying for posts you throw away.
Which search endpoint should you use?
Use recent search for anything in the last 7 days and full-archive search only when you truly need older posts.
| Recent search | Full-archive search | |
|---|---|---|
| Path | GET /2/tweets/search/recent |
GET /2/tweets/search/all |
| Time range | Last 7 days | Back to March 2006 |
| Access | All developers | Pay-per-use and Enterprise |
| Posts per request | Up to 100 | Up to 500 |
| Max query length | 512 characters | 1,024 characters |
Enterprise accounts get 4,096-character queries on both. These figures come from X’s search documentation as of November 2026.
How do you make the first request?
Send the query as a URL-encoded parameter with an app-only Bearer token, and request the fields you need.
const q = encodeURIComponent('"open source" client lang:en -is:retweet');
const url = `https://api.x.com/2/tweets/search/recent?query=${q}` +
"&max_results=50&tweet.fields=created_at,author_id,public_metrics";
const res = await fetch(url, { headers: { Authorization: `Bearer ${BEARER}` } });
const { data = [], meta } = await res.json();
Search reads public data, so an app-only Bearer token works. As with every v2 endpoint, the response is minimal until you ask for fields; the post on what changed in API v2 explains tweet.fields and expansions in more detail.
Which query operators cut the noise?
Combine a few precise operators instead of listing many keywords. The ones small tools use most:
from:usernameandto:usernamefor posts by or replying to an account.-is:retweetto drop retweets,-is:replyto keep only original posts.has:media,has:linkswhen you only want posts with attachments or URLs.lang:ento restrict by detected language.conversation_id:123to pull every reply in one thread.- Quoted phrases such as
"rate limit"for exact matches, and parentheses withORfor alternatives.
A space between terms means AND. So (itwtr OR "x client") -is:retweet lang:en returns English posts that mention either term and are not retweets. Write the query in a test script first and log how many results it returns per hour before you wire it into anything that runs on a schedule.
How does pagination work in search?
Each response includes meta.next_token while more results exist; pass it back as the next_token parameter to get the next page. When the field is missing, you have reached the end. Note that timeline endpoints use a parameter called pagination_token instead, which the posting and reading guide covers. Mixing the two names is a common source of “why do I keep getting page one” bugs.
For polling, there is a better tool than pagination. Store the newest post ID you have processed and pass it as since_id on the next run. The API then returns only posts newer than that ID, which keeps each poll small.
How do you keep search costs and rate limits down?
Ask for fewer posts, filter in the query rather than in your code, and poll with since_id. On pay-per-use, reads are billed per returned post, $0.005 each as of November 2026, and X deduplicates the same post within a UTC day. A query that returns 100 posts which your code then filters down to 5 costs twenty times what a precise query would.
- Set
max_resultsto what you will show, not the maximum. - Push filters into the query: language, retweets, replies, media.
- Poll on a timer with
since_id, never in a tight loop. - Read the rate-limit headers and back off before a 429, as the rate limits chapter describes.
Sources
- Search Posts introduction, X Developer Platform documentation.
- X API pricing, X Developer Platform documentation.
Frequently asked questions
How far back does X API recent search go?
Recent search covers the last 7 days. For anything older you need full-archive search at GET /2/tweets/search/all, which X offers to pay-per-use and Enterprise customers.
How long can a search query be?
Recent search accepts queries up to 512 characters, or 4,096 on Enterprise. Full-archive search allows 1,024 characters on pay-per-use.
How many posts does one search request return?
Up to 100 per request for recent search. Use the next_token from the response to request the following page.
Why does my search return retweets I did not want?
Retweets match by default. Add -is:retweet to the query to exclude them, and -is:reply if you only want original posts.
Does every search cost money?
On pay-per-use, reads are billed per returned post, $0.005 each as of November 2026. A request that returns nothing returns no billable posts, so narrow queries are cheaper.