Search
/tw-v2/search1 API unit per call · How billing works
Description
Search posts or people with the same query syntax and advanced operators as X search.
Make your first search
Send query=javascript and type=Latest with your TweetAPI key, as shown in the examples below. Start without cursor. Latest, Photos, and Videos return posts in data; People returns users. Top returns items with type and content fields.
To fetch another page, send the same query and type with the previous response's pagination.nextCursor as cursor. A null nextCursor means no next page was returned. Keep cursor values opaque; do not construct or modify them.
A billable Search request costs 1 API unit. Each page is a separate request and can use another unit; the number of posts returned does not determine the unit cost. The rate limit counts requests, while your plan's allowance is measured in API units. See Plan Limits for billing and retry rules.
For scheduled checks or managed alerts, see Real-Time Monitoring and Webhook Alerts.
Want to compose the query visually first? Use the free Twitter Advanced Search Query Builder to combine supported operators, validate the 512-character limit, and hand the finished query to this page's authenticated playground.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| querystringrequired | string | required | Search query string, 1-512 characters. Supports advanced search operators. |
| typestringrequired | string | required | Type of search results (Latest, Top, People, Photos, Videos) |
| cursorstringoptional | string | optional | Pagination cursor for fetching next page of results. Obtained from previous response. |
Code Examples
const params = new URLSearchParams({
query: 'javascript',
type: 'Latest'
});
const response = await fetch(`https://api.tweetapi.com/tw-v2/search?${params}`, {
method: 'GET',
headers: {
'X-API-Key': 'YOUR_API_KEY'
}
});
const data = await response.json();
console.log(data);
Search Operators
You can use advanced search operators in the query parameter to filter and refine your results. Combine multiple operators together for precise queries (e.g. from:sample_user_96991 min_faves:1000 filter:images).
Basic Query Syntax
| Operator | Description |
|---|---|
keyword1 keyword2 | Both terms must appear in the tweet (AND logic) |
"exact phrase" | Matches the exact phrase in the specified order |
keyword1 OR keyword2 | Either term must appear in the tweet |
-keyword | Excludes tweets containing the specified term. Also works with phrases: -"exact phrase" |
#hashtag | Matches tweets containing a specific hashtag |
$TSLA | Matches tweets containing a cashtag (stock ticker symbol) |
Users
| Operator | Description |
|---|---|
from:username | Returns tweets sent by a specific user |
to:username | Returns tweets that are replies to a specific user |
@username | Returns tweets mentioning a specific user. Use with -from:username to exclude their own tweets |
list:listId | Returns tweets from members of a given public list |
filter:verified | Limits results to legacy verified accounts |
filter:blue_verified | Limits results to users with a paid verification |
source:appName | Tweets posted from a specific app or client (e.g. source:Twitter_for_iPhone) |
Tweet Type
| Operator | Description |
|---|---|
filter:nativeretweets | Only native retweets (via the retweet button) |
include:nativeretweets | Includes native retweets in results (excluded by default) |
filter:retweets | Includes old-style "RT" retweets and quoted tweets |
filter:replies | Only tweets that are replies |
filter:self_threads | Only self-replies (tweets within a user's own thread) |
conversation_id:tweetId | All tweets within a specific conversation thread |
filter:quote | Only tweets that contain a quote tweet |
quoted_tweet_id:tweetId | Tweets that quote a specific tweet |
quoted_user_id:userId | Tweets that quote any tweet by a specific user |
card_name:animated_gif | Tweets containing GIFs |
card_name:poll2choice_text_only | Tweets with a 2-choice text poll |
card_name:poll3choice_text_only | Tweets with a 3-choice text poll |
card_name:poll4choice_text_only | Tweets with a 4-choice text poll |
card_name:summary | Tweets with a small image summary card |
card_name:summary_large_image | Tweets with a large image summary card |
card_name:player | Tweets with an embedded player card (audio/video) |
Date & Time
since: and until: take a date in US Pacific time, and both include the date you name. For example, since:2026-09-01 until:2026-09-30 covers September 1 at 00:00 through September 30 at 23:59 Pacific time. For an exact window in UTC, use since_time: and until_time: with Unix timestamps instead.
Need ID-based bounds for a specific time? Use the free converter to generate Snowflake boundary IDs from a date, then copy the matching TweetAPI time or ID filters.
| Operator | Description |
|---|---|
until:YYYY-MM-DD | Tweets up to the end of a date in US Pacific time (inclusive) |
since:YYYY-MM-DD | Tweets from the start of a date in US Pacific time (inclusive) |
since_time:timestamp | Tweets on or after a Unix timestamp (seconds). Exact, with no time zone shift |
until_time:timestamp | Tweets before a Unix timestamp (seconds). Exact, with no time zone shift |
since_id:tweetId | Tweets after a specific tweet ID (not inclusive) |
max_id:tweetId | Tweets at or before a specific tweet ID (inclusive) |
within_time:duration | Tweets from the last N days/hours/minutes/seconds (e.g. 2d, 5h, 30m) |
Content
| Operator | Description |
|---|---|
url:domain | Tweets containing a link to a specific domain or subdomain |
lang:code | Tweets in a specific language (ISO code, e.g. en, ja) |
Location
| Operator | Description |
|---|---|
near:city | Tweets geotagged near a specific location |
within:radius | Used with near: to set a search radius (e.g. 15mi) |
geocode:lat,long,radius | Tweets within a geographic radius of specific coordinates |
place:placeId | Tweets tagged with a specific place ID |
Engagement
| Operator | Description |
|---|---|
filter:has_engagement | Tweets with at least some engagement (replies, likes, or retweets) |
min_retweets:N | Tweets with at least N retweets |
min_faves:N | Tweets with at least N likes |
min_replies:N | Tweets with at least N replies |
-min_retweets:N | Tweets with fewer than N retweets |
-min_faves:N | Tweets with fewer than N likes |
-min_replies:N | Tweets with fewer than N replies |
Media & Links
| Operator | Description |
|---|---|
filter:media | Tweets containing any type of media |
filter:twimg | Tweets with native images (pic.twitter.com) |
filter:images | Tweets containing any images |
filter:videos | Tweets containing any video (native or external) |
filter:native_video | Tweets with hosted video only |
filter:consumer_video | Tweets with standard native video |
filter:pro_video | Tweets with pro video |
filter:periscope | Tweets with Periscope streams |
filter:vine | Tweets with Vine videos |
filter:spaces | Tweets linked to Spaces |
filter:links | Tweets containing any URL (including media links) |
filter:mentions | Tweets that mention any account |
filter:news | Tweets containing a link to a news article |
filter:safe | Excludes NSFW content from results |
filter:hashtags | Tweets containing at least one hashtag |
Response
Success Response (200 OK)
This Latest example shows the full post shape and the pagination object. Expand it to inspect fields or copy the JSON. Actual values and available fields vary by result.
Errors
Errors return { statusCode, message } with a non-2xx HTTP status. A 503 is temporary and isn't billed; wait for the seconds in Retry-After and try again.