如何用 Twitter 搜索 API 搜索推文

#Twitter 搜索 API 是怎么工作的

Twitter 搜索 API 是一个接口，它替你对公开推文执行 X 的搜索。你发送一条查询，比如 "vector database" lang:en min_faves:20，返回的是一页匹配的推文，包含正文、日期、各项数量和作者，外加一个用来获取下一页的 cursor。

在写任何代码之前，想先试一试查询，可以在免费的推特高级搜索工具里运行。它会显示前 20 条匹配的帖子，你设置的每个筛选条件都会把对应的运算符写进查询，可以直接粘贴进请求。

三项设置决定返回什么。查询按词语、账号、语言、媒体和互动量挑选推文。排序可选 Top（互动最多的匹配项在前）或 Latest（最新的在前）。日期窗口在查询里写成 X 网页语法的 since: 和 until:，在官方 X API 上则用单独的时间参数。

官方 X API 把搜索拆成两个接口（见 X 的搜索文档（在新标签页打开））。GET /2/tweets/search/recent 覆盖最近 7 天，每次请求返回 10 到 100 条帖子；GET /2/tweets/search/all 可回溯到 2006 年 3 月，最多 500 条。两者都需要获批的开发者账号、Project 和 App，以及 Bearer 令牌，并且对返回的每条帖子都收费 $0.005。

#用 Sorsa API 分四步搜索推文

要在代码里搜索推文，可以用 Sorsa API，一款 Twitter（X）API 与爬虫：结果每 1,000 条 $0.07 起，可以回溯到 2006 年的任意日期，所有套餐都是每秒 20 次请求。它只需要一个 ApiKey 请求头，不需要开发者账号和 OAuth，读取的是 x.com 搜索框的查询语法，也从不碰你的 X 账号。

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

2. 写好查询。 像在 x.com 上那样输入：词语、"exact phrases"、from:、lang:、min_faves: 和 since:。

3. 发送请求。 把查询放在 JSON 请求体里，POST 给 POST /search-tweets（在新标签页打开），用 "order": "latest" 让最新的推文排在前面，用 "popular" 则对应 Top。

   curl -X POST "https://api.sorsa.io/v3/search-tweets" \
     -H "ApiKey: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"query": "\"vector database\" lang:en min_faves:20", "order": "latest"}'
   

   {
     "tweets": [
       {
         "id": "2116173807613027825",
         "full_text": "Benchmarked three vector databases on 40M embeddings.",
         "created_at": "2026-10-30T14:22:07Z",
         "lang": "en",
         "likes_count": 214,
         "retweet_count": 37,
         "reply_count": 19,
         "quote_count": 6,
         "view_count": 18450,
         "bookmark_count": 92,
         "is_reply": false,
         "is_quote_status": false,
         "conversation_id_str": "2116173807613027825",
         "entities": [],
         "user": {
           "id": "1620350095193014349",
           "username": "indexlab_notes_daily",
           "display_name": "Index Lab Notes",
           "followers_count": 8312,
           "verified": false,
           "created_at": "2023-01-31T09:15:42Z"
         }
       }
     ],
     "next_cursor": "DAADDAABCgABHV3t2nWAJ8kKAAIdXcTm0Zvw"
   }
   

   显示完整响应

4. 顺着 cursor 翻页。 每条推文都带有作者的完整资料，所以不需要再做第二次查询。把 next_cursor 放回同一个请求体里就能获取下一页，直到某次响应不再带它为止。

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

把你自己的查询粘贴到下面检查一下，并得到 curl、Python 或 Node.js 形式的请求，JSON 请求体里的引号会被转义。检查器还会标出官方 X API 的运算符名称，这些名称在网页语法里是不用的。

curl -X POST "https://api.sorsa.io/v3/search-tweets" \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "\"vector database\" lang:en min_faves:20", "order": "latest"}'

import requests

r = requests.post(
    "https://api.sorsa.io/v3/search-tweets",
    headers={"ApiKey": "YOUR_API_KEY"},
    json={"query": '"vector database" lang:en min_faves:20',
          "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/search-tweets", {
  method: "POST",
  headers: { ApiKey: "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    query: '"vector database" lang:en min_faves:20',
    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);

#写出能在代码里运行的查询

/search-tweets 的查询，就是你在 x.com 搜索框里会输入的那个字符串，所以你可以先在浏览器里构建好，再原样粘贴进请求。七条规则几乎涵盖了开发者遇到的所有问题：

• 空格表示 AND，OR 必须大写，开头的 - 排除一个词或一个运算符，括号用来分组：(rust OR golang) -hiring。
• 精确短语放在双引号里。在原始 JSON 字符串里，这些引号需要加反斜杠，写成 "\"vector database\""；在 Python 和 Node.js 里传入字典或对象，库会替你转义。
• 话题标签、股票标签和提及按原样写入：#buildinpublic、$NVDA、@acme_cloud_status。查询通过 JSON 请求体传送，所以不需要任何 URL 编码。
• 日期写在查询里：since:2026-10-01 包含当天，until:2026-11-01 在这一天之前截止，都按 UTC 计。
• 互动下限是 min_faves:、min_retweets: 和 min_replies:；加一个减号就把下限变成上限，比如 -min_faves:1000。
• 原生转发默认被排除，除非加上 include:nativeretweets，而 -filter:replies 只保留顶层帖子。
• 一条查询里大约能放 22 个运算符。更长的账号或关键词列表要拆成几条查询。

五种模式涵盖了团队大部分的搜索需求，每一种都可以直接粘贴到 query 字段里：

# Mentions of a brand, without its own posts
("acme cloud" OR @acme_cloud_status) -from:acme_cloud_status

# The most liked posts on a topic
"vector database" min_faves:100 -filter:replies lang:en

# One account's posts on a subject in October
from:acme_cloud_status outage since:2026-10-01 until:2026-11-01

# Posts that link to a site
url:github.com rust -filter:replies

# Images under a hashtag
#buildinpublic filter:images

每个运算符及其特殊之处和示例，都在我们的 Twitter 搜索运算符列表里。

#获取每一页，再让搜索持续运行

要收集不止一页的结果，就带上上一次响应里的 next_cursor，再发一次同样的请求体，直到响应里不再有它为止。每页约 20 条推文，条数并不固定，所以一页短并不意味着搜索结束了；只有 cursor 不再出现才是。

下面的循环每收到一条推文，就把它写入 JSON Lines 文件，并跳过已经保存的 ID。它设有页数预算，所以一条宽泛的查询不会把你的请求额度耗光。

import json
import requests

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


def search(query, order="latest", max_pages=50):
    body = {"query": query, "order": order}
    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


seen = set()
with open("tweets.jsonl", "w", encoding="utf-8") as f:
    for t in search('"vector database" lang:en min_faves:20'):
        if t["id"] not in seen:
            seen.add(t["id"])
            f.write(json.dumps(t) + "\n")

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

async function* search(query, order = "latest", maxPages = 50) {
  const body = { query, order };
  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 query = '"vector database" lang:en min_faves:20';
for await (const t of search(query)) {
  console.log(t.id, t.user.username, t.full_text.slice(0, 60));
}

持续运行的搜索，就是把同样的循环放到定时器上。请求最新的推文，加上 since_id:，值为你上次保存的最大 ID，读到 cursor 用完为止，再保存新的最大 ID。当没有新帖子时，一次检查只花一次请求，所以对一条冷清的查询频繁检查，成本依然很低。

import time

newest = None
while True:
    query = '"vector database" lang:en'
    if newest:
        query += f" since_id:{newest}"
    fresh = list(search(query))
    if fresh:
        newest = max(fresh, key=lambda t: int(t["id"]))["id"]
        print(len(fresh), "new tweets")
    time.sleep(300)

搜索靠轮询来工作：没有可以订阅的数据流。至于提醒、定时任务以及推送到 Slack 或邮件，我们的 Twitter 实时监测指南搭出了整条管道，用 Python 使用 Twitter API指南则补充了重试和并行搜索。

须知

只要是收集或统计推文，就用 "order": "latest"：它会从最新的一条开始，逐条遍历所有匹配项。"popular"（即 Top 标签页）只返回互动最多的那些匹配项，所以对同一条查询运行两次 Top，可能得到不同的结果集。

#按话题标签搜索推文

按话题标签搜索，就把标签按你输入的样子原样放进查询，比如 #buildinpublic。它匹配以话题标签形式出现该标签的推文，不区分大小写，并且可以与其他所有运算符组合。

如果人们也会不带标签地写这个短语，就用 OR 加上普通词语：(#buildinpublic OR "build in public") min_faves:10 -filter:replies lang:en。有多个标签时用 OR 连接；股票或币的代码则使用 $NVDA 这样的 cashtag。

通过 Sorsa API，# 会原样放进 JSON 请求体。而在官方 X API 的 GET 请求里，它必须写成 %23，因为没有编码的 # 会截断 URL，服务器永远看不到这个标签。要统计某个话题标签随时间的变化，可以每天用 since: 和 until: 跑一次 Latest 搜索，再统计每天返回的推文数。

#按搜索需求选择接口

关键词搜索只是 Sorsa API 上查找推文的五种方式之一。选哪个接口，取决于你手里有什么：词语、一个账号、一组账号，还是人本身。

其余四个各自读取不同的起点。POST /mentions（在新标签页打开） 接受一个账号名，返回提到它的推文，请求体里可以设置点赞、回复、转发和日期筛选。POST /search-users（在新标签页打开） 查找名称或简介匹配某个词的账号。POST /user-tweets（在新标签页打开） 读取一个账号自己的时间线，每次请求约 20 条推文。X 列表的成员会通过 GET /list-tweets（在新标签页打开） 合并成一条动态返回，所以一个多达 5,000 个账号的列表，每页只需一次请求就能监测。

品牌团队通常把其中两个搭配使用：用 /search-tweets 看人们谈论产品时说了什么，用 /mentions 看人们对它的账号说了什么。第二个接口见我们的 Twitter 提及 API指南。

#搜索推文要花多少钱

在 Sorsa API 上，搜索结果每 1,000 条推文 $0.07 起：一次请求返回约 20 条推文，不管里面有多少内容，都只算一次请求。官方 X API 对返回的每条帖子都收费，每条 $0.005，也就是每 1,000 条 $5.00（见 X 的价格表（在新标签页打开））。

一旦带上作者，官方价格还会上涨。从 2026 年 11 月 22 日起，X 对通过 expansions 返回的每位用户另行收费 $0.010（见 X 在 10 月 23 日的通知（在新标签页打开）），所以 1,000 条结果如果每条的作者都不同，可能要花 $15.00。Sorsa API 把作者的完整资料放在每条推文里，不另外收费。

用量在那边也有上限：按量付费每月最多读取 300 万条帖子，超出之后 X 只卖 Enterprise 合同。Sorsa API 没有 300 万的上限：套餐可以扩展到每月 1,000 万次请求，而你的 100 次免费请求大约能覆盖 2,000 条搜索结果，无需绑卡。完整的 X API 价格详解列出了官方的每一档费率。

#官方 X API 搜索对比

官方 X API 的搜索，每 1,000 条结果的价格大约是 Sorsa API 的 71 倍。它的近期搜索只能看到最近 7 天，每个应用每 15 分钟允许 450 次请求。下表把三个搜索接口并排放在一起，官方的限制取自 X 的速率限制表（在新标签页打开）。

• 覆盖的日期

  Sorsa API /search-tweets

  回溯到 2006 年 3 月

  X 近期搜索

  最近 7 天

  X 全量档案搜索

  回溯到 2006 年 3 月

• 每次请求的结果数

  Sorsa API /search-tweets

  约 20

  X 近期搜索

  10 到 100

  X 全量档案搜索

  10 到 500

• 速率限制

  Sorsa API /search-tweets

  每个密钥每秒 20 次请求

  X 近期搜索

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

  X 全量档案搜索

  每秒 1 次请求，每 15 分钟 300 次

• 每 1,000 条结果的价格

  Sorsa API /search-tweets

  $0.07 起

  X 近期搜索

  $5.00

  X 全量档案搜索

  $5.00

• 作者资料

  Sorsa API /search-tweets

  包含在每条推文里

  X 近期搜索

  自 2026 年 11 月 22 日起每个另计 $0.010

  X 全量档案搜索

  自 2026 年 11 月 22 日起每个另计 $0.010

• 查询语法

  Sorsa API /search-tweets

  x.com 网页搜索

  X 近期搜索

  v2 运算符，512 个字符

  X 全量档案搜索

  v2 运算符，1,024 个字符

• 准备工作

  Sorsa API /search-tweets

  一个 API 密钥

  X 近期搜索

  开发者账号、App、Bearer 令牌

  X 全量档案搜索

  开发者账号、App、Bearer 令牌

官方接口默认也只返回 id 和 text：日期、数量和作者，只有在 tweet.fields、expansions 和 user.fields 中请求时才会返回。在 Sorsa API 上，每条推文都带着它的全部字段。

#网页语法与官方 X API 运算符的对照

官方 X API 读取的是它自己的运算符名称，所以从 x.com 搜索框复制来的查询可能在那里失败。它会以 400 错误拒绝 min_faves: 和 min_retweets:，并且日期要用 start_time 和 end_time 参数传入，而不是写在查询里。Sorsa API 接受网页语法，所以左边一列可以原样运行。

• 至少 20 个赞

  网页语法（x.com、Sorsa API）

  min_faves:20

  官方 X API v2

  min_likes:20

• 至少 5 次转发

  网页语法（x.com、Sorsa API）

  min_retweets:5

  官方 X API v2

  min_reposts:5

• 仅限 2026 年 10 月

  网页语法（x.com、Sorsa API）

  since:2026-10-01 until:2026-11-01

  官方 X API v2

  start_time 和 end_time 参数

• 仅限回复

  网页语法（x.com、Sorsa API）

  filter:replies

  官方 X API v2

  is:reply

• 带媒体或链接的帖子

  网页语法（x.com、Sorsa API）

  filter:media、filter:links

  官方 X API v2

  has:media、has:links

• 转发

  网页语法（x.com、Sorsa API）

  默认排除

  官方 X API v2

  自 2026 年 5 月 4 日起，关键词搜索中不再包含

• 词语、账号、语言

  网页语法（x.com、Sorsa API）

  from:、to:、#、@、"phrase"、lang:

  官方 X API v2

  相同

2026 年的两项改动，解释了为什么旧指南互相矛盾。X 在 2026 年 1 月 19 日关闭了 min_likes:、min_replies: 和 min_reposts:。5 月 4 日又重新开放了它们，那时搜索迁移到了新的索引，同时也把转发从关键词搜索结果中去掉了（见 X 的更新日志（在新标签页打开））。那些说官方 X API 会忽略互动筛选的页面和 AI 回答，描述的是中间那几个月的情况。

要把整个集成从官方接口迁走？我们的从官方 X API 迁移指南，把 v2 的每个参数和运算符都对应到了 Sorsa API。

#今天就开始搜索推文

在代码里搜索推文，归根结底就是一条查询加一个 cursor。用 Sorsa API，你本来在 x.com 上输入的查询直接发给 POST /search-tweets，每次请求返回约 20 条推文及其作者，日期可以回溯到 2006 年的任意一天。结果每 1,000 条 $0.07 起，官方 X API 则是 $5.00，而你的 100 次免费请求就能覆盖前 2,000 条。

#常见问题