> ## 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.

# 搜索推文

> 通过关键词和运算符搜索 X（Twitter）推文的 POST 端点。

`/search-tweets` 端点使用关键词和运算符查询公开 X（Twitter）搜索索引，返回匹配推文及完整作者资料和互动指标。

端到端使用方式、查询模板和可运行代码，请参阅博客上的[如何通过 API 搜索推文](https://api.sorsa.io/blog/twitter-search-api)。

## 端点

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

## 身份验证

在 `ApiKey` 请求头中传入 API 密钥。HTTP 请求头名称不区分大小写，密钥值必须与获得的密钥完全一致。

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

详情请参阅[身份验证](https://docs.sorsa.io/zh-Hans/authentication)。

## 请求体

| 参数            | 类型     | 必需 | 说明                                        |
| :------------ | :----- | :- | :---------------------------------------- |
| `query`       | string | 是  | 搜索关键词和运算符。支持全部原生 X 搜索运算符。                 |
| `order`       | string | 否  | `"popular"`（默认）相当于热门标签页；`"latest"` 按时间排序。 |
| `next_cursor` | string | 否  | 上一响应返回的分页游标。首次请求省略。                       |

### 请求示例

```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"
  }'
```

## 响应

```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..."
}
```

每条推文都直接包含完整作者资料，无需额外查询用户数据。

> 完整字段参考请参阅[响应格式](https://docs.sorsa.io/zh-Hans/response-format)。

## 查询运算符

`query` 字段支持全部原生 X 搜索运算符，包括：

* **关键词与精确短语：**`"climate change"`
* **用户筛选：**`from:`、`to:`、`@mention`
* **互动筛选：**`min_faves:`、`min_retweets:`、`min_replies:`
* **内容筛选：**`filter:media`、`filter:images`、`filter:videos`、`filter:links`（前加 `-` 表示排除）
* **语言与日期：**`lang:en`、`since:2026-01-01`、`until:2026-03-01`
* **布尔逻辑：**`OR`、用于分组的括号、用于排除的 `-`

> 完整参考：[搜索运算符](https://docs.sorsa.io/zh-Hans/search-operators)。

## 分页

响应包含 `next_cursor` 字段。获取下一页时，发送相同请求，并将 `next_cursor` 设为该值。当它为 `null` 或缺失时，表示结果已全部读取。

> 游标分页方式与边界情况请参阅[分页](https://docs.sorsa.io/zh-Hans/pagination)。

## 速率限制

每个 API 密钥每秒 20 次请求，所有套餐相同。超过限制会返回 `429 Too Many Requests`。参阅[速率限制](https://docs.sorsa.io/zh-Hans/rate-limits)。

## 错误码

| 状态码   | 含义               |
| :---- | :--------------- |
| `200` | 成功               |
| `400` | 请求无效（参数错误）       |
| `401` | 未授权（API 密钥缺失或无效） |
| `403` | 禁止访问（配额耗尽或订阅过期）  |
| `429` | 请求过多（超过速率限制）     |
| `500` | 内部服务器错误          |

> 完整列表请参阅[错误码](https://docs.sorsa.io/zh-Hans/error-codes)。

## 相关端点

* [追踪提及](https://docs.sorsa.io/zh-Hans/api-reference/search/search-mentions)：专门追踪 `@handle`，请求体支持更丰富的筛选
* [用户推文](https://docs.sorsa.io/zh-Hans/api-reference/tweets/user-tweets)：单个用户的时间线
* [搜索用户](https://docs.sorsa.io/zh-Hans/api-reference/search/search-users)：按关键词查找账号