/mentions 端点返回提及特定用户名的推文。可用于品牌提及监测、支持请求分流、衡量活动互动和关注竞品动态。它提供 Sorsa 搜索端点中最丰富的筛选条件:互动门槛和日期范围都可以直接作为请求体参数传入。结果分页返回,每页最多 20 条推文。
注意: 包含生产代码、多渠道监测方式和竞品分析工作流的完整教程,请参阅博客上的如何通过 API 追踪 Twitter 提及。
快速开始
提示: 更喜欢图形界面?在 API Playground 中无需代码即可运行 /mentions。每个账号初始包含 100 次免费请求,无需信用卡。
端点参考
每次调用只扣除一次请求配额,无论返回一条还是二十条提及。
响应
user 对象包含完整个人资料(上方为便于阅读已省略部分字段),所有时间戳使用 ISO 8601。next_cursor 存在表示还有更多页面,为 null 或缺失则表示已到末尾。处理方式见分页,完整字段列表见响应格式。
/mentions 与 /search-tweets 的区别
两个端点解决不同问题:/mentions用于标记特定用户名(@brand)的帖子,涵盖 @标记、回复和引用提及,支持直接传入min_likes、min_retweets、min_replies、since_date和until_date参数。/search-tweets用于不包含用户名的关键词匹配。例如"Nike" -from:Nike lang:en可找到正文中提到品牌的帖子。需要布尔逻辑、媒体筛选或/mentions不支持的运算符时,应使用此端点。
常见用法
按互动筛选
只获取已经触达受众的提及,适用于声誉控制台和公关监测。获取每条提及(支持队列)
去掉互动筛选并按时间排序,以捕获所有提及,包括零互动的帖子。按日期窗口分析活动
通过since_date 和 until_date 限定活动时间段,然后循环使用 next_cursor,直到没有更多结果。
轮询新提及
在多轮轮询之间记录最新推文 ID,仅显示尚未见过的提及。ID 以字符串返回,因此比较时应按数字大小进行。last_seen_id 持久化到磁盘或 Redis,使循环能够在重启后恢复;在请求外使用带退避的 try/except,防止临时错误终止进程。完整去重和退避模式请参阅实时监测。
常见问题
- 支持场景的
min_likes设得过高。 只有 2 个赞的错误报告可能比 500 个赞的表情包更重要。支持队列应将min_likes设为 0,并通过关键词分流。 - 高流量账号只读取一页。 每次最多返回 20 条提及。每天有数百条提及的品牌应始终使用
next_cursor分页。每页都扣除一次请求配额,请据此规划预算。 - 误以为
/mentions能完全覆盖。 它只捕获带 @标记的帖子,应结合/search-tweets获取未标记的品牌提及。 - 对低流量账号过于频繁轮询。 根据提及量设置间隔:高流量品牌可每 15 秒,小账号可每一两分钟。所有套餐的速率限制均为每秒 20 次,见速率限制。
- 重启时没有保留状态。 如果没有持久化检查点,监测器重启后可能重复提醒旧提及,或跳过中间缺口。