> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sorsa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Tweets

> POST endpoint for keyword and operator-based tweet search on X (Twitter).

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](https://api.sorsa.io/blog/twitter-search-api) guide on the blog.

## Endpoint

```text theme={null}
POST https://api.sorsa.io/v3/search-tweets
```

## Authentication

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

```text theme={null}
ApiKey: YOUR_API_KEY
```

See [Authentication](https://docs.sorsa.io/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

```bash theme={null}
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

```json theme={null}
{
  "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](https://docs.sorsa.io/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](https://docs.sorsa.io/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](https://docs.sorsa.io/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](https://docs.sorsa.io/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](https://docs.sorsa.io/error-codes) for the full list.

## Related endpoints

* [Track Mentions](https://docs.sorsa.io/api-reference/search/search-mentions) - purpose-built `@handle` tracking with a richer body-level filter set
* [User Tweets](https://docs.sorsa.io/api-reference/tweets/user-tweets) - timeline of a single user
* [Search Users](https://docs.sorsa.io/api-reference/search/search-users) - find accounts by keyword