获取任意 X 账号提及的 Twitter 提及 API

#Twitter 提及 API 返回什么

Twitter 提及 API 是这样一个接口：给它一个账号，它就以 JSON 分页返回标记了该账号 @用户名 的公开帖子，最新的在前。标记出现在哪里都算：回复的开头、句子中间，或一排多个用户名之中。

想不写代码查看某个账号最近的提及，免费的 Twitter 提及查询工具可以按时间段和最低点赞数列出它们。本指南其余部分用代码完成同样的工作，适用于任意数量的账号和任意多的页数。

每条提及都以完整帖子的形式返回：它的文字和时间，它的点赞、回复、转发、引用和浏览量，是否回复了某人，以及作者是谁。受保护账号的帖子从不出现。一条提到了品牌名但没有写 @ 的帖子根本不算提及：那需要关键词搜索，下文会讲到。

在官方 X API 上，提及来自 GET /2/users/{id}/mentions（X 的参考文档（在新标签页打开））。它接收账号的数字用户 ID，所以用户名需要先做一次用户查询。每次请求返回 5 到 100 条帖子，时间线只保存一个账号最近的 800 条提及（X 的时间线概览（在新标签页打开））。一条帖子只带着它的 ID 和文字返回；日期、计数和作者，只有在 tweet.fields、expansions 和 user.fields 提出要求时才会出现。

时间是官方接口唯一接受的过滤条件：start_time、end_time、since_id 和 until_id。它没有针对点赞或回复的设置，所以客服团队和公关团队下载的是同一份数据，各自在本地排序。

#用 Sorsa API 按用户名获取提及

想用代码拉取提及，可以用 Sorsa API，一款 Twitter（X）API 与爬虫：POST /mentions 返回任意账号的提及，每 1,000 条 $0.07 起，而官方 X API 是 $5.00。它接受你原样输入的用户名，并在同一个 JSON 请求体里按点赞、回复、转发和日期过滤。一个 ApiKey 请求头取代了开发者账号和 OAuth，也不会牵涉你的 X 账号。

1. 获取密钥。 注册后从控制台复制 API 密钥。100 次免费请求已经在上面了。

2. 指定账号。 把用户名放进 query，不带 @，例如 northwind_billing。它可以是你的品牌、客户或竞争对手：任何公开账号都行。

3. 发送请求。 把请求体 POST 到 POST /mentions（在新标签页打开），并用 "order": "latest" 让最新的提及排在前面。

   curl -X POST "https://api.sorsa.io/v3/mentions" \
     -H "ApiKey: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"query": "northwind_billing", "order": "latest"}'
   

   {
     "tweets": [
       {
         "id": "2116933823886904728",
         "full_text": "@northwind_billing invoices still pending, is sync down?",
         "created_at": "2026-11-01T16:42:09Z",
         "lang": "en",
         "likes_count": 14,
         "retweet_count": 2,
         "reply_count": 3,
         "quote_count": 0,
         "view_count": 2310,
         "bookmark_count": 1,
         "is_reply": false,
         "is_quote_status": false,
         "conversation_id_str": "2116933823886904728",
         "entities": [],
         "user": {
           "id": "1587702913445103616",
           "username": "ops_notes_by_priya",
           "display_name": "Priya, ops notes",
           "followers_count": 4180,
           "verified": false,
           "created_at": "2022-11-02T08:31:44Z"
         }
       },
       {
         "id": "2116909085882164728",
         "full_text": "@northwind_billing the usage export saved me an afternoon",
         "created_at": "2026-11-01T15:03:51Z",
         "lang": "en",
         "likes_count": 87,
         "retweet_count": 9,
         "reply_count": 4,
         "quote_count": 1,
         "view_count": 11920,
         "bookmark_count": 6,
         "is_reply": true,
         "in_reply_to_username": "northwind_billing",
         "in_reply_to_tweet_id": "2116851177420881920",
         "is_quote_status": false,
         "conversation_id_str": "2116851177420881920",
         "entities": [],
         "user": {
           "id": "1371240448912351233",
           "username": "dana_ships_daily_x",
           "display_name": "Dana Okafor",
           "followers_count": 12650,
           "verified": true,
           "created_at": "2021-03-15T00:00:00Z"
         }
       }
     ],
     "next_cursor": "DAADDAABCgABHWD2c1tQkCsKAAIdYAk3gl1QYQ"
   }
   

   显示完整响应

4. 沿着 cursor 往下读。 一页最多 20 条提及，每条的 user 里都带着作者的完整资料。把 next_cursor 放进同一个请求体发回去就能得到下一页，当某个响应不再带它时就停止。

返回 403 表示密钥缺失或请求额度已用完，401 表示密钥有误。429 表示一秒内超过 20 次请求：等一秒再重发。失败的请求从不收费。

在下面输入一个用户名，以及人们提到这个品牌时用的词。构建器会写出 curl、Python 和 Node.js 版的 /mentions 请求，以及用来查找提到品牌名但没有标记它的帖子的搜索查询。

curl -X POST "https://api.sorsa.io/v3/mentions" \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "northwind_billing", "order": "latest"}'

import requests

r = requests.post(
    "https://api.sorsa.io/v3/mentions",
    headers={"ApiKey": "YOUR_API_KEY"},
    json={
        "query": "northwind_billing",
        "order": "latest",
    },
    timeout=30,
)
page = r.json()
for t in page["tweets"]:
    print(t["user"]["username"], t["full_text"])
print(page.get("next_cursor"))

const res = await fetch("https://api.sorsa.io/v3/mentions", {
  method: "POST",
  headers: { ApiKey: "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    query: "northwind_billing",
    order: "latest",
  }),
});
const page = await res.json();
for (const t of page.tweets) console.log(t.user.username, t.full_text);
console.log(page.next_cursor);

("northwind billing" OR northwnd OR url:northwind.io) -from:northwind_billing

#按点赞、回复和日期过滤提及

POST /mentions 在 Sorsa API 一侧完成过滤，所以请求只要求任务需要的提及，要翻的页数也更少。每个过滤条件都放在与用户名相同的 JSON 请求体里，并且可以自由组合：

• query

  作用

  你想看其提及的账号用户名，不带 @

• order

  作用

  latest，最新的在前（默认），或 popular，互动最多的在前

• min_likes

  作用

  只保留点赞数不少于此值的提及

• min_replies

  作用

  只保留回复数不少于此值的提及

• min_retweets

  作用

  只保留转发数不少于此值的提及

• since_date

  作用

  日期窗口的起点，格式为 YYYY-MM-DD

• until_date

  作用

  日期窗口的终点，格式为 YYYY-MM-DD

• next_cursor

  作用

  上一个响应里的 cursor，用来获取下一页

大多数团队发送的，四种请求体就够了。每一种都是上面 curl 命令可以直接使用的完整请求体：

# Support queue: every mention, newest first, no thresholds
{"query": "northwind_billing", "order": "latest"}

# PR and reputation: mentions that reached people
{"query": "northwind_billing", "order": "popular", "min_likes": 100}

# Campaign report: one month of mentions
{"query": "northwind_billing",
 "since_date": "2026-10-01", "until_date": "2026-10-31"}

# Competitor: what people tell a rival, with some traction
{"query": "ledgerly_founder_hq", "order": "popular", "min_retweets": 10}

客服队列不要设阈值：一条只有两个赞的故障报告，比一条有五百个赞的玩笑更需要尽快回复。阈值适用于报告和提醒，在那里，少数传播开来的提及比每一条回复都重要。想把竞争对手的提及与它的粉丝和发帖习惯放在一起看，请参阅我们的 Twitter 竞品分析指南。

#收集每一页，然后只取新提及

回填和监控是同一个请求，只是停止规则不同。回填读取一个日期窗口，直到 cursor 用完；监控读取最新的提及，并在遇到第一条已保存的提及时停止。

下面的回填会在页面到达时，把一个月的提及写入一个 JSON Lines 文件，每行一条提及。页数预算会让它停下，所以繁忙的账号不会耗光你的请求。

import json
import requests

API = "https://api.sorsa.io/v3/mentions"
HEADERS = {"ApiKey": "YOUR_API_KEY"}


def mentions(handle, max_pages=100, **filters):
    body = {"query": handle, "order": "latest", **filters}
    for _ in range(max_pages):
        r = requests.post(API, json=body, headers=HEADERS, timeout=30)
        r.raise_for_status()
        page = r.json()
        yield from page.get("tweets", [])
        cursor = page.get("next_cursor")
        if not cursor:
            break
        body["next_cursor"] = cursor


with open("mentions.jsonl", "w", encoding="utf-8") as f:
    for t in mentions("northwind_billing",
                      since_date="2026-10-01",
                      until_date="2026-10-31"):
        f.write(json.dumps(t) + "\n")

import { appendFileSync, writeFileSync } from "node:fs";

const API = "https://api.sorsa.io/v3/mentions";
const headers = {
  ApiKey: "YOUR_API_KEY",
  "Content-Type": "application/json",
};

async function* mentions(handle, filters = {}, maxPages = 100) {
  const body = { query: handle, order: "latest", ...filters };
  for (let i = 0; i < maxPages; i++) {
    const res = await fetch(API, {
      method: "POST",
      headers,
      body: JSON.stringify(body),
    });
    if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
    const page = await res.json();
    yield* page.tweets ?? [];
    if (!page.next_cursor) break;
    body.next_cursor = page.next_cursor;
  }
}

const october = { since_date: "2026-10-01", until_date: "2026-10-31" };
writeFileSync("mentions.jsonl", "");
for await (const t of mentions("northwind_billing", october)) {
  appendFileSync("mentions.jsonl", JSON.stringify(t) + "\n");
}

要让动态保持最新，就按计划运行下面的函数。它逐页读取最新的提及，遇到第一个见过的 ID 就停止，所以没有新内容的检查只花一次请求。推文 ID 随时间增大，但以字符串形式返回，所以比较时要把它们转成整数。

from pathlib import Path

STATE = Path("last_mention_id.txt")


def new_mentions(handle):
    last = int(STATE.read_text()) if STATE.exists() else 0
    fresh = []
    for t in mentions(handle, max_pages=10):
        if int(t["id"]) <= last:
            break
        fresh.append(t)
    if fresh:
        STATE.write_text(fresh[0]["id"])
    return fresh

第一次运行时没有已保存的 ID，所以它会读取最多 10 页，并存下最新的一条。之后多久运行一次，取决于有人必须多快作出回复：客服每分钟检查一次，周报一天一次就够。

须知

把最后一个 ID 存在进程之外：文件、数据库的一行，或一个 Redis 键。监控程序若在没有它的情况下重启，要么对旧的提及再次提醒，要么跳过宕机期间发布的所有内容。

想要 Slack 或邮件提醒，以及为许多账号安排计划，我们的 Twitter 实时监控指南搭建了完整的管道。观察一组账号发了什么，与读取别人对它们说了什么，是两项不同的工作。一个 X 列表可以在同一条动态里涵盖最多 5,000 个账号：请看 X 列表与 Community API指南。

#捕获那些从没标记你的提及

POST /mentions 返回带有 @用户名 的帖子。人们谈论一个品牌时也可能不标记它：直接写名字、拼错、附上它网站的链接，或引用它的某条帖子。这几种形式在 Sorsa API 上各有各的接口。

对于名字、拼写错误和链接，把查询发给 POST /search-tweets（在新标签页打开），并排除品牌自己的帖子：

("northwind billing" OR northwnd OR url:northwind.io) -from:northwind_billing

一条既标记了品牌又写出品牌名的帖子，会从两个接口各返回一次，所以两条数据流都以推文 ID 为键，只保留一份。计划任务之前，先读一百条新查询的结果：一个同时也是日常词汇的品牌名，需要的是更多排除条件，而不是更多页数。

单条帖子的引用来自 POST /quotes（在新标签页打开），带有引用的文字及其作者，不论这条引用有没有标记品牌。转发过某条帖子的账号则以资料形式来自 POST /retweeters（在新标签页打开）。我们的 Twitter 搜索 API指南解释了查询语法和搜索循环，Twitter 搜索运算符列表则涵盖了查询可以带的每一种过滤条件。

#官方提及接口并排对比

官方 X API 的 GET /2/users/{id}/mentions 和 Sorsa API 的 POST /mentions 返回的是同样的公开帖子。区别在于你发送什么、返回什么，以及花多少钱。有七项标准决定一项提及任务：每 1,000 条的价格、历史范围、过滤条件、作者数据、设置、速率限制，以及你的 X 账号会怎样。

下表把两个接口并排放在一起，官方的限制来自 X 的速率限制表（在新标签页打开）。读取任意账号的每 1,000 条提及，Sorsa API 便宜约 71 倍；读取你自己账号的，则比官方费率便宜 14 倍。

• 账号输入

  Sorsa API

  用户名

  官方 X API

  数字用户 ID，需要先查询

• 每次请求的提及数

  Sorsa API

  最多 20 条

  官方 X API

  5 到 100 条

• 能回溯多远

  Sorsa API

  你设定的任意日期窗口；通过 /search-tweets 可回溯多年

  官方 X API

  最近的 800 条

• 过滤条件

  Sorsa API

  点赞、回复、转发、日期

  官方 X API

  日期和帖子 ID

• 作者资料

  Sorsa API

  包含在每条提及里

  官方 X API

  通过扩展字段，自 2026 年 11 月 22 日起每个 $0.010

• 速率限制

  Sorsa API

  每个密钥每秒 20 次请求

  官方 X API

  每个应用每 15 分钟 450 次请求

• 每 1,000 条提及的价格

  Sorsa API

  $0.07 起

  官方 X API

  $5.00；读取你自己的账号为 $1.00

• 设置

  Sorsa API

  一个 API 密钥

  官方 X API

  开发者账号、应用、bearer 令牌

• 你的 X 账号

  Sorsa API

  从不使用

  官方 X API

  与开发者账号关联

Sorsa API 在设计上是只读的，所以它从不索要你的 X 登录信息，你的账号也从不会有风险。想用代码回复提及，就搭配官方 X API 来回复：读取留给 Sorsa API，发帖走 X。

#每 1,000 条提及要花多少钱

在 Sorsa API 上，提及每 1,000 条 $0.07 起：一次请求最多返回 20 条，无论里面有什么，都按一次请求计费。官方 X API 对它返回的每条帖子收 $0.005，也就是每 1,000 条提及 $5.00（X 的价目表（在新标签页打开））。

有三个细节会改变官方账单。通过你自己的开发者应用读取你自己账号的提及，算作自有读取，每条帖子 $0.001。从 2026 年 11 月 22 日起，通过扩展字段返回的每位作者另加 $0.010（X 10 月 23 日的通知（在新标签页打开）），所以来自 1,000 个不同人的 1,000 条提及会涨到 $15.00。而且按量付费每月读取 300 万条帖子封顶，超过之后 X 只出售 Enterprise 合同。官方的每项费率都在我们的 X API 定价分析里。

#今天就拉取你的第一批提及

一个账号的提及，只隔着一次请求。把用户名放进 POST /mentions，再加上你关心的点赞、回复、转发或日期，最多 20 条提及就会连同作者一起返回。Sorsa API 每 1,000 条 $0.07 起返回它们，而官方 X API 是 $5.00，且无需开发者账号。你的 100 次免费请求可以覆盖前 2,000 条。

#常见问题