POST

Twitter Search

/v1/twitter/search

Search for tweets by keywords, hashtags, mentions, or advanced filters. Returns recent or top tweets matching your query.

At least one search field (keywords, hashtags, phrases, from_users, mentions, or cashtags) is required. Each filled group generates a separate query -- the limit applies per query.

Request Parameters

Parameter	Type	Required	Description
keywords	string[]	No*	Search keywords
hashtags	string[]	No*	Hashtags (without #)
phrases	string[]	No*	Exact phrases
from_users	string[]	No	Tweets from specific users
to_users	string[]	No	Tweets directed to users
mentions	string[]	No	Tweets mentioning users
cashtags	string[]	No	Cashtags ($SYMBOL)
search_type	string	No	"top" or "recent" (default: top)
limit	int	No	Max results (1-100) (default: 20)
min_faves	int	No	Minimum likes filter
min_retweets	int	No	Minimum retweets filter
min_replies	int	No	Minimum replies filter
since	string	No	Start date (YYYY-MM-DD)
until	string	No	End date (YYYY-MM-DD)
lang	string	No	Language code (en, es, fr...)
exclude_replies	bool	No	Exclude reply tweets (default: false)

Example

curl -X POST https://query-data-api.notpeople.ai/v1/twitter/search \
  -H "X-API-Key: tw_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "keywords": ["AI agents"],
    "min_faves": 100,
    "search_type": "top",
    "limit": 5
  }'

Response Schema

All responses include success, data, and usage fields.

Field	Type	Description
metadata.url	string	Search URL used
metadata.query	string	Search query string
metadata.search_type	string	Search type used (top or recent)
metadata.posts_found	int	Number of posts returned
metadata.elapsed_ms	int	Request duration in milliseconds
metadata.type_breakdown	object	Count of posts by type (tweet, retweet, reply, quote)
metadata.with_media	int	Number of posts with media attached
metadata.with_reply_to_post	int	Number of posts with linked reply context
post_id	string	Unique tweet ID
user_id	string	Author user ID
username	string	Author handle
name	string	Author display name
text	string	Tweet text content
created_at	string	Human-readable timestamp
timestamp	int	Unix timestamp
post_type	string	tweet \| retweet \| reply \| quote
likes_count	int	Number of likes
retweets_count	int	Number of retweets
replies_count	int	Number of replies
views_count	int	Number of views
is_blue_verified	bool	Author verification status
profile_image_url	string	Author profile picture URL
reply_to_post_id	string \| null	ID of the post being replied to
reply_to_user	string \| null	Username of the user being replied to
reply_to_post	object \| null	Full post object being replied to
is_pinned	bool	Whether the post is pinned
media	array	Attached media [{type, url}]
quoted_post	object \| null	Quoted tweet data if post_type is quote

Example Response

{
  "success": true,
  "metadata": {
    "url": "https://x.com/search?q=AI%20agents%20min_faves%3A100",
    "query": "AI agents min_faves:100",
    "search_type": "top",
    "posts_found": 1,
    "elapsed_ms": 5096,
    "type_breakdown": { "tweet": 1 },
    "with_media": 1,
    "with_reply_to_post": 0
  },
  "data": [
    {
      "post_id": "2036997818569957866",
      "user_id": "1536693901230321666",
      "username": "RoundtableSpace",
      "name": "0xMarioNawfal",
      "text": "EVERYTHING CLAUDE CODE JUST OPEN SOURCED...",
      "created_at": "Thu Mar 26 02:45:00 +0000 2026",
      "timestamp": 1774493100,
      "post_type": "tweet",
      "likes_count": 151,
      "retweets_count": 24,
      "replies_count": 20,
      "is_blue_verified": true,
      "profile_image_url": "https://pbs.twimg.com/profile_images/.../photo.jpg",
      "views_count": 50217,
      "reply_to_post_id": null,
      "reply_to_user": null,
      "reply_to_post": null,
      "is_pinned": false,
      "media": [
        { "type": "photo", "url": "https://pbs.twimg.com/media/.../photo.jpg" }
      ],
      "quoted_post": null
    }
  ],
  "usage": {
    "unique_posts": 81,
    "limit": 6000,
    "remaining": 5919
  }
}

Try this endpoint live

Create Free Account