Skip to main content

​
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

ParameterTypeRequiredDescription
querystringYesSearch keywords and operators. Supports the full set of native X search operators.
orderstringNo"popular" (default) for the Top tab equivalent, or "latest" for chronological order.
next_cursorstringNoPagination 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": "Fri Mar 06 13:38:49 +0000 2026",
      "lang": "en",
      "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,
      "conversation_id_str": "2029914600217473314",
      "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

CodeMeaning
200OK
400Bad request (invalid parameters)
401Unauthorized (missing or invalid API key)
429Too many requests (rate limit exceeded)
500Internal server error
See Error Codes for the full list.