> **For coding agents and LLMs:** This is one Social Fetch marketing page (markdown export). For API orientation start with [`/llms.txt`](https://www.socialfetch.dev/llms.txt); for auth and crawl rules use [`/agents.txt`](https://www.socialfetch.dev/agents.txt); for every operation use [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt).

## This page

- **On-site (HTML):** <https://www.socialfetch.dev/platforms/twitter/search>
- **Markdown (.mdx) URL:** <https://www.socialfetch.dev/platforms/twitter/search.mdx>

---

# X (Twitter) Search API

Operator-first search over public posts on X — query in, structured tweet rows out, same envelope as the rest of the Twitter tag.

`GET /v1/twitter/search` takes a required `query` string and returns matching public posts in the shared Social Fetch envelope. Put supported X operators in `query` (`from:`, `OR`, quotes, `#hashtag`, `filter:`, `since:`, and more), or compile them in the [advanced search query builder](https://www.socialfetch.dev/tools/twitter-advanced-search). For post types, use `include:nativeretweets` to include native reposts, `filter:nativeretweets` for native reposts only, or `filter:retweets` only when you specifically want RT-style retweets and quote posts. In other words, plain “retweets only” should use `filter:nativeretweets`; `filter:retweets` is the broader RT/quote operator. `is:retweet` is not a supported post-type operator here. Optional `section` (`top`, `latest`, `people`, `photos`, `videos`) picks the feed style. Optional `limit` accepts up to 20 posts per request, but the actual page size may be smaller. When `data.page.hasMore` is true, pass `data.page.nextCursor` as `cursor` on the next call. Branch on `data.lookupStatus` before you write rows; bill from `meta.creditsCharged`.

Hashtag-only discovery is `GET /v1/twitter/hashtags`. Profile cards are `GET /v1/twitter/profiles/{handle}`. All sit on one Social Fetch API key — no X developer app required for these public lookups.

## Request

- **Endpoint:** `GET /v1/twitter/search`
- **Credits:** 1 credit
Failed requests are free
- **Input:** by query
- **Full reference:** [docs](https://www.socialfetch.dev/docs/api/v1/twitter/search/get)
- **Platform page:** [/platforms/twitter](https://www.socialfetch.dev/platforms/twitter)

## FAQ

### What does the X / Twitter Search API return?

A page of public posts that match your query under data.tweets, plus pagination under data.page (hasMore, nextCursor). People-section searches also return profiles under data.people. Each response uses the shared Social Fetch envelope with data.lookupStatus, meta.requestId, and meta.creditsCharged.

### How do I call Twitter search with operators?

Send GET /v1/twitter/search with x-api-key and a required query parameter. Put supported operators in query, for example from:nasa min_faves:100. For plain retweets-only searches use filter:nativeretweets; reserve filter:retweets for the broader RT-style retweet and quote-post bucket. Use include:nativeretweets when native reposts should remain in otherwise broad results. Do not use is:retweet. Optionally add section, limit, and cursor. Use the Query builder link on the API docs or playground query field, or open /tools/twitter-advanced-search, to compile operators into query + section.

### How much does Twitter post search cost?

Pricing is documented on the operation in the API registry (shown on this page). Confirm on every response with meta.creditsCharged — that field is the billing source of truth. Each paginated page is a separate billed request.

### What is the difference between section=latest and section=top?

section picks the search feed style. Use latest for crisis watches and frequent polls; use top for recap-style dashboards. Other values include people, photos, and videos. Omit section to use the default top feed.

### Can I filter by engagement, date, or language?

Yes. Write min_faves:, since:, until:, and lang: in query. Dates use YYYY-MM-DD. Language uses ISO codes such as en. Combine filters with the same query across paginated pages.

### How do I find or identify retweets?

For plain ‘retweets only’ use filter:nativeretweets, which returns native reposts. Use include:nativeretweets to keep native reposts in otherwise broad results. Use filter:retweets only when you specifically want the broader RT-style retweet and quote-post bucket. The isRetweet field on each returned post is response metadata; it tells you whether that individual row is a native repost. is:retweet is not a supported query filter for this endpoint.

### Can I request more than 20 posts per page?

No. limit accepts 1–20 posts per request, and the API may return fewer than requested. To retrieve more, keep the same query and filters and pass data.page.nextCursor as cursor while data.page.hasMore is true.

### How does pagination work on Twitter search?

When data.page.hasMore is true, pass data.page.nextCursor as the cursor query param on the next request. Keep the same query and filters across pages, and keep the cursor opaque.

### Is this the same as Twitter hashtag search?

No. GET /v1/twitter/search is operator-first search over posts — including #tag inside query when you need operators around a tag. Hashtag-only discovery is GET /v1/twitter/hashtags. Use the Twitter hub docs if your job needs both.

### Do I need an X developer app or Bearer token?

No. You authenticate to Social Fetch with an API key. The route reads public search results; it does not act on behalf of a logged-in X user or require elevated X API access.