Search Tweets

The /search-tweets endpoint runs keyword and operator-based queries against the public X (Twitter) search index and returns matching tweets with full author profiles and engagement metrics. For end-to-end usage patterns, query templates, and working code, see the How to Search Tweets via API guide on the blog.

Endpoint

POST https://api.sorsa.io/v3/search-tweets

Authentication

Pass your API key in the ApiKey header (case-sensitive).

ApiKey: YOUR_API_KEY

See Authentication for details.

Request body

Parameter	Type	Required	Description
`query`	string	Yes	Search keywords and operators. Supports the full set of native X search operators.
`order`	string	No	`"popular"` (default) for the Top tab equivalent, or `"latest"` for chronological order.
`next_cursor`	string	No	Pagination cursor returned in the previous response. Omit on the first request.

Example request

curl -X POST https://api.sorsa.io/v3/search-tweets \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "artificial intelligence lang:en",
    "order": "latest"
  }'

Response

{
  "tweets": [
    {
      "id": "2029914600217473314",
      "full_text": "The latest breakthroughs in AI are reshaping automation.",
      "created_at": "2026-03-06T13:38:49Z",
      "lang": "en",
      "conversation_id_str": "2029914600217473314",
      "likes_count": 142,
      "retweet_count": 38,
      "reply_count": 12,
      "quote_count": 5,
      "view_count": 28400,
      "bookmark_count": 19,
      "is_reply": false,
      "is_quote_status": false,
      "entities": [],
      "user": {
        "id": "1422280682240450563",
        "username": "tech_insider",
        "display_name": "Tech Insider",
        "followers_count": 84200,
        "verified": true
      }
    }
  ],
  "next_cursor": "DAABCgABGSmiaxkAAgoAAgjEJ..."
}

Each tweet includes the full author profile inline. No additional lookup is required to attach user data to tweets.

For the complete field reference, see Response Format.

Query operators

The query field accepts the full set of native X search operators, including:

Keywords and exact phrases: "climate change"
User filters: from:, to:, @mention
Engagement filters: min_faves:, min_retweets:, min_replies:
Content filters: filter:media, filter:images, filter:videos, filter:links (prefix with - to exclude)
Language and date: lang:en, since:2026-01-01, until:2026-03-01
Boolean logic: OR, parentheses for grouping, - for exclusion

Full operator reference: Search Operators.

Pagination

The response includes a next_cursor field. To fetch the next page, send the same request with next_cursor set to that value. When next_cursor is null or absent, the result set is exhausted.

See Pagination for cursor-based pagination patterns and edge cases.

Rate limit

20 requests per second per API key, universal across all plans. Exceeding the limit returns 429 Too Many Requests. See Rate Limits.

Error codes

Code	Meaning
`200`	OK
`400`	Bad request (invalid parameters)
`401`	Unauthorized (missing or invalid API key)
`403`	Forbidden (quota exhausted or subscription expired)
`429`	Too many requests (rate limit exceeded)
`500`	Internal server error

See Error Codes for the full list.

Track Mentions - purpose-built @handle tracking with a richer body-level filter set
User Tweets - timeline of a single user
Search Users - find accounts by keyword

Getting started

Core Mechanics

Solution Guides

Support & Resources

Endpoint

Authentication

Request body

Example request

Response

Query operators

Rate limit

Error codes

​Endpoint

​Authentication

​Request body

​Example request

​Response

​Query operators

​Pagination

​Rate limit

​Error codes

​Related endpoints

Endpoint

Authentication

Request body

Example request

Response

Query operators

Pagination

Rate limit

Error codes

Related endpoints