Skip to main content
/mentions 端点返回提及特定用户名的推文。可用于品牌提及监测、支持请求分流、衡量活动互动和关注竞品动态。它提供 Sorsa 搜索端点中最丰富的筛选条件:互动门槛和日期范围都可以直接作为请求体参数传入。结果分页返回,每页最多 20 条推文。
注意: 包含生产代码、多渠道监测方式和竞品分析工作流的完整教程,请参阅博客上的如何通过 API 追踪 Twitter 提及

快速开始

提示: 更喜欢图形界面?在 API Playground 中无需代码即可运行 /mentions。每个账号初始包含 100 次免费请求,无需信用卡。

端点参考

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

响应

每条提及包含完整互动指标和嵌入的作者资料。user 对象包含完整个人资料(上方为便于阅读已省略部分字段),所有时间戳使用 ISO 8601。next_cursor 存在表示还有更多页面,为 null 或缺失则表示已到末尾。处理方式见分页,完整字段列表见响应格式

/mentions 与 /search-tweets 的区别

两个端点解决不同问题:
  • /mentions 用于标记特定用户名(@brand)的帖子,涵盖 @标记、回复和引用提及,支持直接传入 min_likesmin_retweetsmin_repliessince_dateuntil_date 参数。
  • /search-tweets 用于不包含用户名的关键词匹配。例如 "Nike" -from:Nike lang:en 可找到正文中提到品牌的帖子。需要布尔逻辑、媒体筛选或 /mentions 不支持的运算符时,应使用此端点。
要完整覆盖品牌讨论,可以并行运行两个端点,并按推文 ID 去重。

常见用法

按互动筛选

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

获取每条提及(支持队列)

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

按日期窗口分析活动

通过 since_dateuntil_date 限定活动时间段,然后循环使用 next_cursor,直到没有更多结果。

轮询新提及

在多轮轮询之间记录最新推文 ID,仅显示尚未见过的提及。ID 以字符串返回,因此比较时应按数字大小进行。
这个只读首页的示例在启动时建立基线,不会输出现有页面。对于活跃信息流,应在更新检查点前分页补齐缺口,保留时间重叠并按 ID 去重,以处理延迟出现的结果。将 last_seen_id 持久化到磁盘或 Redis,使循环能够在重启后恢复;在请求外使用带退避的 try/except,防止临时错误终止进程。完整去重和退避模式请参阅实时监测

常见问题

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

后续步骤