Twitter Search API for public posts by keyword

curl --get 'https://api.xfetch.io/v1/search/recent' \
  -H "Authorization: Bearer $XFETCH_API_KEY" \
  --data-urlencode 'query="AI agents" lang:en -filter:replies' \
  --data 'limit=20'

import os
import requests

response = requests.get(
    "https://api.xfetch.io/v1/search/recent",
    headers={"Authorization": "Bearer " + os.environ["XFETCH_API_KEY"]},
    params={"query":"\"AI agents\" lang:en -filter:replies","limit":20},
    timeout=30,
)
response.raise_for_status()
result = response.json()
for post in result["data"]:
    print(post["id"], post["text"])

Let your HTTP client encode the query so spaces, # and $reach the API correctly. The Python example uses the requests package. For all request parameters, see the recent-search API reference.

{
  "data": [
    {
      "id": "1234567890123456789",
      "text": "xfetch ships /v1 today.",
      "author_id": "783214",
      "created_at": "2026-05-23T12:00:00.000Z",
      "lang": "en",
      "conversation_id": "1234567890123456789",
      "possibly_sensitive": false,
      "like_count": 5,
      "retweet_count": 1,
      "reply_count": 0,
      "quote_count": 0,
      "bookmark_count": 0,
      "is_quote_status": false,
      "entities": {
        "hashtags": [],
        "urls": [],
        "mentions": []
      }
    }
  ],
  "meta": {
    "request_id": "req_01HXFETCHEXAMPLE",
    "credits": {
      "charged": 2,
      "remaining": 998
    },
    "pagination": {
      "next_token": "tok_2"
    }
  }
}

Take a complete research task further

Collect matching posts and author profiles, follow pages, remove duplicates, and download a readable report with JSON/CSV files.

Refine your results

Twitter search operators for useful queries

These are xfetch search-query examples. A date filter narrows results within available recent coverage; it does not turn this endpoint into a full archive. For an existing official API integration, see the separate X API compatibility guide.

A priced item is a returned post in both modes. Join enriched results using tweet.author_id = author.id; handle a missing author when a profile is unavailable. Successful pages use the returned count, including the base charge for an empty page. Failed requests are not charged. Check credit packs and estimate your budget with the pricing calculator.

Before you integrate

Twitter Search API questions

What is a Twitter Search API?

A Twitter Search API retrieves public posts matching a query so you can use them in software. xfetch returns post text, IDs, author IDs, timestamps and available engagement metrics as JSON for social listening, research and AI applications.

Can I search tweets by keyword, hashtag or username?

Yes. Put keywords, quoted phrases, #hashtags or $cashtags in query. Use from:username for posts from a known account, lang:en for English, and -filter:replies to exclude replies. This searches posts; it does not search a directory of user profiles.

Do I need an X developer account or an API key?

Custom queries use an xfetch API key in the Authorization: Bearer header. You do not supply X developer credentials. You can inspect the fixed public Search Demo without signing in; create an xfetch account to run your own query.

Can I search historical tweets or get every matching post?

This endpoint is for recent public search. Date operators narrow a query, but do not provide a guaranteed historical lookback or an exhaustive archive. Check returned created_at values against the period your research needs. For a known account's new-post alerts, use account monitoring.

How do I paginate Twitter search results?

Pass meta.pagination.next_token unchanged as next_token on your next request. Keep the same endpoint, query, limit and sort_order. Stop when the token is absent. Store post IDs to deduplicate records when you run the query again later.

When should I use enriched search?

Choose basic search when post records are enough. Choose enriched search when you also need author bios or public follower metrics: it returns data.tweets and data.authors, joined by tweet.author_id and author.id. Some author profiles may be unavailable, so handle missing matches.

Are empty results and failed requests charged?

A successful empty search still uses the base charge shown in the pricing table. A failed request is not charged. Check meta.credits.charged for the amount charged on each successful page.