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

# 追踪提及

`/mentions` 端点返回提及特定用户名的推文。可用于品牌提及监测、支持请求分流、衡量活动互动和关注竞品动态。它提供 Sorsa 搜索端点中最丰富的筛选条件：互动门槛和日期范围都可以直接作为请求体参数传入。结果分页返回，每页最多 20 条推文。

> **注意：** 包含生产代码、多渠道监测方式和竞品分析工作流的完整教程，请参阅博客上的[如何通过 API 追踪 Twitter 提及](https://api.sorsa.io/blog/twitter-mentions-api)。

## 快速开始

```bash theme={null}
curl -X POST https://api.sorsa.io/v3/mentions \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "AppleSupport",
    "order": "latest",
    "min_likes": 10,
    "since_date": "2026-03-01"
  }'
```

> **提示：** 更喜欢图形界面？在 [API Playground](https://api.sorsa.io/playground) 中无需代码即可运行 `/mentions`。每个账号初始包含 100 次免费请求，无需信用卡。

***

## 端点参考

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

| 参数             | 类型      | 必需 | 说明                                       |
| :------------- | :------ | :- | :--------------------------------------- |
| `query`        | string  | 是  | 要追踪的用户名，不含 @。例如 `"elonmusk"`。            |
| `order`        | string  | 否  | `"latest"`（默认，最新在前）或 `"popular"`（按互动排名）。 |
| `since_date`   | string  | 否  | 开始日期，格式为 `YYYY-MM-DD`。                   |
| `until_date`   | string  | 否  | 结束日期，格式为 `YYYY-MM-DD`。                   |
| `min_likes`    | integer | 否  | 提及的最少点赞数。                                |
| `min_retweets` | integer | 否  | 提及的最少转推数。                                |
| `min_replies`  | integer | 否  | 提及的最少回复数。                                |
| `next_cursor`  | string  | 否  | 上一响应返回的分页游标。                             |

每次调用只扣除一次请求配额，无论返回一条还是二十条提及。

***

## 响应

```json theme={null}
{
  "tweets": [
    {
      "id": "2031847200012345678",
      "full_text": "@AppleSupport My iPhone keeps restarting after the latest update. Anyone else?",
      "created_at": "2026-03-08T14:22:31Z",
      "lang": "en",
      "likes_count": 47,
      "retweet_count": 12,
      "reply_count": 8,
      "quote_count": 2,
      "view_count": 15200,
      "is_reply": false,
      "is_quote_status": false,
      "user": {
        "id": "9876543210",
        "username": "frustrated_user",
        "display_name": "Alex",
        "followers_count": 1240,
        "verified": false
      }
    }
  ],
  "next_cursor": "DAABCgABGSmiaxkA..."
}
```

每条提及包含完整互动指标和嵌入的作者资料。`user` 对象包含完整个人资料（上方为便于阅读已省略部分字段），所有时间戳使用 ISO 8601。`next_cursor` 存在表示还有更多页面，为 `null` 或缺失则表示已到末尾。处理方式见[分页](https://docs.sorsa.io/zh-Hans/pagination)，完整字段列表见[响应格式](https://docs.sorsa.io/zh-Hans/response-format)。

***

## /mentions 与 /search-tweets 的区别

两个端点解决不同问题：

* `/mentions` 用于标记特定用户名（`@brand`）的帖子，涵盖 @标记、回复和引用提及，支持直接传入 `min_likes`、`min_retweets`、`min_replies`、`since_date` 和 `until_date` 参数。
* [`/search-tweets`](https://docs.sorsa.io/zh-Hans/search-tweets) 用于不包含用户名的关键词匹配。例如 `"Nike" -from:Nike lang:en` 可找到正文中提到品牌的帖子。需要布尔逻辑、媒体筛选或 `/mentions` 不支持的运算符时，应使用此端点。

要完整覆盖品牌讨论，可以并行运行两个端点，并按推文 ID 去重。

***

## 常见用法

### 按互动筛选

只获取已经触达受众的提及，适用于声誉控制台和公关监测。

```python theme={null}
import requests

API_KEY = "YOUR_API_KEY"
URL = "https://api.sorsa.io/v3/mentions"

body = {"query": "nike", "order": "popular", "min_likes": 100}
resp = requests.post(URL, headers={"ApiKey": API_KEY, "Content-Type": "application/json"}, json=body)
resp.raise_for_status()
mentions = resp.json().get("tweets", [])
```

### 获取每条提及（支持队列）

去掉互动筛选并按时间排序，以捕获所有提及，包括零互动的帖子。

```python theme={null}
body = {"query": "YourBrandSupport", "order": "latest", "since_date": "2026-05-10"}
resp = requests.post(URL, headers={"ApiKey": API_KEY, "Content-Type": "application/json"}, json=body)
```

### 按日期窗口分析活动

通过 `since_date` 和 `until_date` 限定活动时间段，然后循环使用 `next_cursor`，直到没有更多结果。

```python theme={null}
import time

def all_mentions(handle, since, until, max_pages=50):
    out, cursor = [], None
    for _ in range(max_pages):
        body = {"query": handle, "order": "latest", "since_date": since, "until_date": until}
        if cursor:
            body["next_cursor"] = cursor
        resp = requests.post(URL, headers={"ApiKey": API_KEY, "Content-Type": "application/json"}, json=body)
        resp.raise_for_status()
        data = resp.json()
        out.extend(data.get("tweets", []))
        cursor = data.get("next_cursor")
        if not cursor:
            break
        time.sleep(0.1)
    return out
```

### 轮询新提及

在多轮轮询之间记录最新推文 ID，仅显示尚未见过的提及。ID 以字符串返回，因此比较时应按数字大小进行。

```python theme={null}
last_seen_id = None
while True:
    resp = requests.post(URL, headers={"ApiKey": API_KEY, "Content-Type": "application/json"},
                         json={"query": "yourbrand", "order": "latest"})
    resp.raise_for_status()
    tweets = resp.json().get("tweets", [])
    if tweets and last_seen_id is None:
        last_seen_id = max((t["id"] for t in tweets), key=int)
    elif tweets:
        new = [t for t in tweets if int(t["id"]) > int(last_seen_id)]
        # handle `new` mentions
        if new:
            last_seen_id = max((t["id"] for t in new), key=int)
    time.sleep(15)
```

这个只读首页的示例在启动时建立基线，不会输出现有页面。对于活跃信息流，应在更新检查点前分页补齐缺口，保留时间重叠并按 ID 去重，以处理延迟出现的结果。将 `last_seen_id` 持久化到磁盘或 Redis，使循环能够在重启后恢复；在请求外使用带退避的 `try`/`except`，防止临时错误终止进程。完整去重和退避模式请参阅[实时监测](https://docs.sorsa.io/zh-Hans/real-time-monitoring)。

***

## 常见问题

* **支持场景的 `min_likes` 设得过高。** 只有 2 个赞的错误报告可能比 500 个赞的表情包更重要。支持队列应将 `min_likes` 设为 0，并通过关键词分流。
* **高流量账号只读取一页。** 每次最多返回 20 条提及。每天有数百条提及的品牌应始终使用 `next_cursor` 分页。每页都扣除一次请求配额，请据此规划预算。
* **误以为 `/mentions` 能完全覆盖。** 它只捕获带 @标记的帖子，应结合 `/search-tweets` 获取未标记的品牌提及。
* **对低流量账号过于频繁轮询。** 根据提及量设置间隔：高流量品牌可每 15 秒，小账号可每一两分钟。所有套餐的速率限制均为每秒 20 次，见[速率限制](https://docs.sorsa.io/zh-Hans/rate-limits)。
* **重启时没有保留状态。** 如果没有持久化检查点，监测器重启后可能重复提醒旧提及，或跳过中间缺口。

***

## 后续步骤

* [搜索推文](https://docs.sorsa.io/zh-Hans/search-tweets)：按关键词搜索未标记的提及
* [搜索运算符](https://docs.sorsa.io/zh-Hans/search-operators)：媒体、地理、布尔等复杂查询
* [实时监测](https://docs.sorsa.io/zh-Hans/real-time-monitoring)：包含去重和退避的轮询架构
* [历史数据](https://docs.sorsa.io/zh-Hans/historical-data)：按日期范围获取旧推文
* [API 参考](https://docs.sorsa.io/zh-Hans/api-reference/search/search-mentions)：完整端点规范