Twitter Search API (X Search API)

Twitter Search API (X Search API) — search tweets with every X search operator, or search accounts. Top, latest, people, or media results as JSON for $0.01 per call.

POST/v1/twitter/search

$0.01/call

The Twitter Search API (X Search API) runs any X search and returns structured tweets — full text, author profile, engagement counts, media, and URLs. All of X's search operators work in query: from:NASA, #rust, "exact phrase", min_faves:100, lang:en, since:2026-01-01, -filter:replies, and more. Set type: "people" to search accounts instead of tweets.

No X developer account, approval, or monthly plan is needed — one YepAPI key, $0.01 per call.

Usage

const res = await fetch('https://api.yepapi.com/v1/twitter/search', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"query": "from:NASA", "type": "latest", "count": 20}),
});
const { data } = await res.json();
console.log(data);

curl -X POST https://api.yepapi.com/v1/twitter/search \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "from:NASA", "type": "latest", "count": 20}'

import requests

res = requests.post(
    "https://api.yepapi.com/v1/twitter/search",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={"query": "from:NASA", "type": "latest", "count": 20},
)
print(res.json()["data"])

Request Body

Parameter	Type	Required	Description	Default
`query`	`string`	Yes	Search query with any X search operators (max 512 characters)	—
`type`	`string`	No	One of: `top`, `latest`, `people`, `media`	`top`
`count`	`number`	No	Page size hint, 1–100	`20`
`cursor`	`string`	No	`cursor` from the previous response, to fetch the next page	—

Response

{
  "ok": true,
  "data": {
    "cursor": "DAADDAABCgABHV56yQtXUQIKAAIdWUjIHdZhqgAIAAIAAAACCAADAAAAAAgABAAAAAAKAAUdXr25WwAnEAoABh1evbla_9jwCwAHAAAA8EVtUEM2d0FBQWZRL2dHSk4wdkdwL0FBQUFCUWRXcXp1dXBxQkZoMWN6UGhaMnJEV0hWNXp6c3RXa0I0ZFhQM3FhSnJSSXgx…",
    "tweets": [
      {
        "author": {
          "avatar": "https://pbs.twimg.com/profile_images/1321163587679784960/0ZxKlEKB_400x400.jpg",
          "banner": null,
          "created_at": "2007-12-19T20:20:32+00:00",
          "description": "Making the seemingly impossible, possible. ✨",
          "followers_count": null,
          "following_count": null,
          "id": "11348282",
          "is_blue_verified": true,
          "likes_count": null,
          "listed_count": null,
          "location": "Pale Blue Dot",
          "media_count": null,
          "name": "NASA",
          "pinned_tweet_ids": [],
          "protected": false,
          "tweet_count": null,
          "url": "https://x.com/NASA",
          "username": "NASA",
          "verified": false,
          "verified_type": "Government",
          "website": null
        },
        "bookmarks": 29,
        "conversation_id": "2116263878807998722",
        "created_at": "2026-10-30T20:20:01+00:00",
        "hashtags": [],
        "id": "2116263878807998722",
        "in_reply_to_tweet_id": null,
        "in_reply_to_username": null,
        "is_quote": false,
        "is_retweet": false,
        "lang": "en",
        "likes": 682,
        "media": [
          {
            "alt_text": "Three jet aircraft, each with a white nose and blue body, fly in a triangle formation against a clear blue sky. White trails follow each jet. ",
            "duration_ms": null,
            "height": 1280,
            "type": "photo",
            "url": "https://pbs.twimg.com/media/HV56yHnXcAAwYJ2.jpg",
            "video_url": null,
            "width": 1920
          }
        ],
        "mentions": [],
        "possibly_sensitive": false,
        "quoted_tweet": null,
        "quotes": 4,
        "replies": 38,
        "retweeted_tweet": null,
        "retweets": 86,
        "text": "MAX POWER, America’s newest aerospace expo and air show, is just a week away!\n\nThis showcase will be packed with events—from aircraft flyovers to a chance to meet NASA astronauts and experts. Here's w…",
        "url": "https://x.com/NASA/status/2116263878807998722",
        "urls": [
          "https://go.nasa.gov/4zjj9BD"
        ],
        "views": 202974
      }
    ]
  }
}

With type: "people" the response has users (same fields as the Twitter User API) instead of tweets.

Response Fields

Field	Type	Description
`ok`	`boolean`	Whether the request succeeded
`data.tweets`	`object[]`	Matching tweets (`type` `top`, `latest`, or `media`)
`data.tweets[].id`	`string`	Tweet ID
`data.tweets[].url`	`string`	x.com URL of the tweet
`data.tweets[].text`	`string`	Full text
`data.tweets[].created_at`	`string`	ISO 8601 timestamp
`data.tweets[].lang`	`string \| null`	Language code detected by X
`data.tweets[].author`	`object`	Author profile — same fields as `/v1/twitter/user`
`data.tweets[].likes`	`number`	Like count
`data.tweets[].retweets`	`number`	Repost count
`data.tweets[].replies`	`number`	Reply count
`data.tweets[].quotes`	`number`	Quote count
`data.tweets[].bookmarks`	`number`	Bookmark count
`data.tweets[].views`	`number \| null`	View count
`data.tweets[].conversation_id`	`string`	ID of the thread's first tweet
`data.tweets[].in_reply_to_tweet_id`	`string \| null`	Tweet this one replies to
`data.tweets[].in_reply_to_username`	`string \| null`	Handle this one replies to
`data.tweets[].is_retweet`	`boolean`	This is a repost — the original is in `retweeted_tweet`
`data.tweets[].is_quote`	`boolean`	This quotes another tweet — see `quoted_tweet`
`data.tweets[].possibly_sensitive`	`boolean`	Flagged as sensitive media
`data.tweets[].hashtags`	`string[]`	Hashtags without `#`
`data.tweets[].mentions`	`string[]`	Mentioned handles
`data.tweets[].urls`	`string[]`	Expanded links
`data.tweets[].media`	`object[]`	Photos, videos, GIFs: `type` (`photo`, `video`, `animated_gif`), `url`, `video_url` (MP4), `duration_ms`, `width`, `height`, `alt_text`
`data.tweets[].quoted_tweet`	`object \| null`	The quoted tweet, same shape
`data.tweets[].retweeted_tweet`	`object \| null`	The reposted tweet, same shape
`data.users`	`object[]`	Matching accounts — only with `type: "people"`
`data.cursor`	`string \| null`	Cursor for the next page

Pagination

Each response includes a cursor. Send the same request again with that value in cursor to get the next page; cursor is null when there is nothing more (or the page came back empty). count is a page-size hint — X may return a few more or fewer items than you ask for. Every page is a separate $0.01 call.

Caching

Responses are cached for 10 minutes; type: "latest" results are cached for 2 minutes.

Errors

Status	Code	When
`400`	`VALIDATION_ERROR`	`query` is missing or too long, or `type` is invalid
`429`	`RATE_LIMITED_UPSTREAM`	Too many requests in a short burst — retry after a few seconds
`502` / `503`	`UPSTREAM_ERROR` / `SERVICE_UNAVAILABLE`	Temporary problem fetching data from X — retry later

Failed calls are not charged.

A search with no matches returns 200 with an empty list.

Tweet API — one tweet by ID or URL
Tweet Scraper API — an account's timeline
Twitter Trends API — what's trending, to feed into searches

Twitter Search API (X Search API)

On this page