面向 AI 智能体的 Twitter API：REST、MCP 还是技能

#AI 智能体如何获取 X 数据

AI 智能体获取 X 数据，和获取其他实时数据的方式一样：模型按名称请求一个工具，模型之外的代码去调用 API，返回的 JSON 进入模型的上下文，供它做下一步。模型自己从不打开 x.com。

让智能体用上这个工具，有三种接入方式：

• REST 工具是智能体代码里的一个函数，注册到 OpenAI Agents SDK、LangChain、CrewAI 或 n8n 这样的框架里。
• MCP 服务器是一个小程序，Claude Code、Cursor 和 Codex 等 AI 应用会自动启动它；它通过 Model Context Protocol 列出自己的工具。
• **技能（skill）**是带一个 SKILL.md 文件的文件夹，用来教编程智能体认识某个 API，让智能体自己编写并运行调用代码。

每一种背后都需要有 X 数据的来源。X 自己的来源是官方 X API，它的智能体资源（在新标签页打开）提供了托管的 MCP 服务器、OpenAPI 规范和 skill.md 文件。那里的每次调用，都走你的 X 开发者应用，使用 OAuth 2.0 或 bearer 令牌，并消耗预付额度。

X 的价目表（在新标签页打开）对每条帖子读取收费 $0.005，对每份用户资料或每个粉丝收费 $0.010，且按量付费在每月读取 300 万条帖子后停止。10 月 23 日的一份通知（在新标签页打开）补充说，从 11 月 22 日起，随帖子一起返回的作者和媒体也按读取计费：带作者的搜索结果，每 1,000 条最高 $15.00。我们的 X API 价格指南列出了每一档费率。

#选择接入方式：REST 工具、MCP 服务器还是技能

按智能体运行的位置来选：自己编码的智能体用 REST 工具，Claude Code 或 Cursor 这样的 AI 应用用 MCP 服务器，会自己写脚本的编程智能体用技能。Sorsa API 是一款 Twitter（X）API 与爬虫，一个密钥、同一个 SORSA_API_KEY 变量就能支持这三种方式，所以你可以先用其中一种，以后再加另一种。

• 你自己的代码：OpenAI Agents SDK、LangChain、CrewAI、n8n、自定义循环

  接入方式

  REST 工具

  需要添加的内容

  一个调用 https://api.sorsa.io/v3 的函数

  占用的上下文

  搜索工具 304 个字符

• AI 应用：Claude Code、Cursor、Codex、VS Code、Claude Desktop

  接入方式

  MCP 服务器

  需要添加的内容

  带上你的密钥运行 npx -y sorsa-mcp

  占用的上下文

  40 个工具 2.33 万个字符

• 会编写并运行代码的编程智能体

  接入方式

  技能

  需要添加的内容

  sorsa-x-api 文件夹

  占用的上下文

  打开技能之前 762 个字符

上下文之所以重要，是因为工具定义的每个字符都会随模型的请求一起发送，要消耗 token，也占用注意力。我们在 11 月 2 日列出了 MCP 服务器的工具：40 个定义共 2.33 万个字符，约 5,800 个 token。Claude Code 用工具搜索把这一部分压得很小，在模型需要某个工具之前，只给它看工具名称。

技能只往上下文里放 762 个字符（名称和描述），只有智能体打开时才加载 8,163 个字符的 SKILL.md。REST 工具占多少取决于你怎么写：下面的 search_x 定义是 304 个字符。

许多团队同时用两种方式：探索数据时在编辑器里用 MCP 服务器，交付上线的智能体里用 REST 工具。

#用 REST 工具给任何智能体接入 X 数据

想给自己构建的智能体接入 X 数据，写一个调用 Sorsa API 的函数，把它注册为工具：模型传入搜索查询，函数以 JSON 返回帖子，每次调用算一次请求。为自己编码的智能体选 Sorsa API：一个 ApiKey 请求头，不需要 OAuth，每次搜索调用返回约 20 条带完整作者资料的帖子，每 1,000 条结果 $0.07 起，所有套餐统一每秒 20 次请求。

1. 获取密钥。 注册后，从控制台复制密钥，放进 SORSA_API_KEY 环境变量。密钥留在你的代码里，模型永远看不到它。

2. 先试一次调用。 POST /search-tweets（在新标签页打开）接收带 X 搜索运算符的查询，每页返回约 20 条帖子，设置 "order": "latest" 则最新的在前。

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

   {
     "tweets": [
       {
         "id": "1985342107664281745",
         "full_text": "Our support agent now reads X through MCP.",
         "created_at": "2026-10-30T14:12:09Z",
         "lang": "en",
         "likes_count": 48,
         "retweet_count": 6,
         "reply_count": 9,
         "quote_count": 2,
         "view_count": 5310,
         "is_reply": false,
         "user": {
           "id": "1544001928374651904",
           "username": "kai_builds_agents",
           "display_name": "Kai Builds Agents",
           "followers_count": 2841,
           "verified": false
         }
       }
     ],
     "next_cursor": "DAADDAABCgABG4vQ2kXAJxIKAAIbi9Dask"
   }
   

   显示完整响应

3. 把它包装成工具。 这个函数用 next_cursor 翻页，直到预算用完，并且从每条帖子的 41 个字段里只保留 7 个，所以 20 条帖子的工具结果仍然很短。

   import os
   
   import requests
   
   API = "https://api.sorsa.io/v3"
   HEADERS = {"ApiKey": os.getenv("SORSA_API_KEY", "YOUR_API_KEY")}
   KEEP = ("id", "full_text", "created_at", "likes_count", "view_count")
   
   
   def search_x(query: str, max_pages: int = 1) -> list[dict]:
       """Search public X posts with operators like from: and lang:.
   
       Args:
           query: X search query.
           max_pages: Pages to read, about 20 posts each.
       """
       posts, cursor = [], None
       for _ in range(max_pages):
           body = {"query": query, "order": "latest"}
           if cursor:
               body["next_cursor"] = cursor
           r = requests.post(f"{API}/search-tweets", json=body,
                             headers=HEADERS, timeout=30)
           r.raise_for_status()
           data = r.json()
           for t in data.get("tweets", []):
               post = {k: t.get(k) for k in KEEP}
               post["author"] = t["user"]["username"]
               post["followers"] = t["user"]["followers_count"]
               posts.append(post)
           cursor = data.get("next_cursor")
           if not cursor:
               break
       return posts
   

4. 注册这个工具。 同一个函数可以用在 OpenAI Agents SDK、LangChain 或任何 LLM API 里，它的 docstring 会成为工具的描述。Claude 的 Messages API 把这个 schema 叫作 input_schema；OpenAI 的函数工具把同一个对象叫作 parameters。

   from agents import Agent, Runner, function_tool
   
   agent = Agent(
       name="X researcher",
       instructions="Answer from public X posts and cite post IDs.",
       tools=[function_tool(search_x)],
   )
   result = Runner.run_sync(agent, "What are developers saying about MCP?")
   print(result.final_output)
   

   from langchain.agents import create_agent
   from langchain.tools import tool
   
   agent = create_agent(
       model="openai:gpt-5.5",
       tools=[tool(search_x, parse_docstring=True)],
       system_prompt="Answer from public X posts and cite post IDs.",
   )
   question = {"role": "user", "content": "What are developers saying about MCP?"}
   result = agent.invoke({"messages": [question]})
   

   {
     "name": "search_x",
     "description": "Search public X posts with operators like from: and lang:.",
     "input_schema": {
       "type": "object",
       "properties": {
         "query": {"type": "string", "description": "X search query."},
         "max_pages": {
           "type": "integer",
           "description": "Pages to read, about 20 posts each."
         }
       },
       "required": ["query"]
     }
   }
   

响应里的每条帖子带 22 个字段，其中的 user 对象（作者的完整资料）又带 19 个。智能体很少需要全部。只返回 7 个字段，能让每个工具结果都保持简短，这很重要：比如 Claude Code，在单个工具结果超过 1 万个 token 时就会发出警告。

同一个智能体的更多工具

同样的模式可以覆盖智能体在 X 上做的其他事情：围绕一个接口写一个函数，每次调用都是一次请求。

• GET /info-batch（在新标签页打开）每次调用按用户名或用户 ID 查询 100 份用户资料。
• POST /tweet-info-bulk（在新标签页打开）每次调用根据 ID 或链接读取 100 条帖子，每条都带作者。
• GET /followers（在新标签页打开）每页返回 200 个粉丝，用 next_cursor 翻页。
• POST /check-follow（在新标签页打开）一次调用就能回答一个账号是否关注了另一个账号。

另外 40 个接口，从回复、引用到 Lists、Communities 和趋势，见 Sorsa API 接口页面。

#把 MCP 服务器添加到 Claude Code、Cursor 或 Codex

对支持 MCP 的 AI 应用，添加 Sorsa API 的 MCP 服务器：一条命令就能从 npm 启动 sorsa-mcp，应用随即获得 40 个用你的密钥调用的只读工具，从搜索、用户资料到关注检查。

claude mcp add sorsa --scope user \
  -e SORSA_API_KEY=YOUR_API_KEY -- npx -y sorsa-mcp

{
  "mcpServers": {
    "sorsa": {
      "command": "npx",
      "args": ["-y", "sorsa-mcp"],
      "env": { "SORSA_API_KEY": "YOUR_API_KEY" }
    }
  }
}

在 Claude Code 里，服务器名称 sorsa 要放在 -e 之前，因为 -e 会把它后面的词当作变量来读。Cursor 则从上面的 JSON 文件读取同一个服务器。之后向智能体提一个需要 X 的问题，比如今天大家在怎么讨论你的发布，它就会自己调用 search_tweets。

Codex、VS Code、Claude Desktop 和其他应用的配置行，以及服务器连不上时的解决办法，见我们的 Twitter MCP 服务器指南。Twitter MCP 服务器页面列出了全部 40 个工具及其各自的返回内容。

#为编程智能体安装智能体技能

Claude Code、Codex 或 Cursor 这样的编程智能体，通过技能来学会 Sorsa API：sorsa-x-api 文件夹会告诉它某项任务该用哪个接口、如何用 next_cursor 翻页、什么时候该批量处理 100 个 ID，调用代码则由智能体自己编写。

技能遵循开放的 Agent Skills（在新标签页打开） 格式，所以同一个文件夹可以在这些智能体之间通用。用 skills 命令行安装，它会询问要添加到哪些智能体；也可以手动把它复制到 Claude Code 的技能文件夹：

npx skills add Sorsa-io/sorsa-x-api-skill

git clone https://github.com/Sorsa-io/sorsa-x-api-skill \
  ~/.claude/skills/sorsa-x-api

然后在智能体运行的 shell 里设置 SORSA_API_KEY。当智能体应该留下代码时，技能更合适，比如每周一导出一周提及内容的脚本，而不是每个问题都去调用一次工具。

对没有技能功能的助手，AI 文档（在新标签页打开）页面把完整的 API 参考放在一个文本文件里，可以直接附上。用 AI 构建页面提供了适用于 Claude Code、Cursor 和 Codex 的现成提示词。

#为什么读取 X 的智能体应该只读

读取帖子的智能体读到的是陌生人写的文字，所以只能读取的 API 是最简单的保护措施：没有任何工具能发帖、点赞、关注或发私信，被人埋进去的帖子就无法驱使智能体去做这些事。

安全团队把这叫作间接提示注入。OWASP（在新标签页打开） 把提示注入列为 LLM 应用风险之首，并指出来自网站或文件等外部来源的内容就是入口之一。搜索结果正是这类内容。在官方 X API 上，持有带写入权限令牌的智能体可能被诱导去操作账号，所以常见的建议是加一道网关，在每个写请求到达 X 之前把它拦下。

如果智能体绝对不能在 X 上执行操作，就用 Sorsa API：它的 45 个接口全部读取公开数据，所以 API 密钥本身就是边界，不需要网关。MCP 服务器也没有发帖工具：我们在 11 月 2 日调用 post_tweet 时，它回答的是 "Tool post_tweet not found"。整个过程中不涉及你的任何 X 登录信息或 Cookie，所以你的 X 账号零风险。

如果智能体必须发帖，就把发帖放在官方 X API 上的一个单独工具里，每条帖子 $0.015，并让人工审批后再发出。

须知

把工具返回的内容当作数据，而不是指令。在系统提示词里告诉模型，帖子文本只是被引用的材料；并且让所有密钥都留在你的代码或环境变量里，绝不放进提示词，这样任何帖子或工具结果都套不出它。

#智能体读取 X 数据的成本，每 1,000 条结果

在 Sorsa API 上，智能体读取 X 数据的成本，按任务不同是每 1,000 条结果 $0.007 到 $0.07，而在官方 X API 上是 $5.00 到 $15.00。这个 $15.00 是 X 从 11 月 22 日起对随作者一起返回的帖子收取的价格。Sorsa API 的价格从最低的按请求费率算起，在所有套餐里，一次调用不论返回什么都是一次请求。

• 按主题搜索帖子

  接口

  POST /search-tweets

  每次调用

  约 20 条帖子，含作者

  Sorsa API，每 1,000 条

  $0.07 起

  官方 X API，每 1,000 条

  $5.00，带作者 $15.00

• 按 ID 读取帖子

  接口

  POST /tweet-info-bulk

  每次调用

  最多 100 条帖子，含作者

  Sorsa API，每 1,000 条

  $0.014 起

  官方 X API，每 1,000 条

  $5.00，带作者 $15.00

• 查询用户资料

  接口

  GET /info-batch

  每次调用

  最多 100 份用户资料

  Sorsa API，每 1,000 条

  $0.014 起

  官方 X API，每 1,000 条

  $10.00

• 读取粉丝列表

  接口

  GET /followers

  每次调用

  最多 200 个粉丝

  Sorsa API，每 1,000 条

  $0.007 起

  官方 X API，每 1,000 条

  $10.00

用一次研究任务就能把规模说清楚：智能体搜索一个主题，拿到 20 条带作者的帖子，再查询 100 份用户资料。在官方 X API 上，这次任务现在要 $1.10，11 月 22 日起要 $1.30。在 Sorsa API 上，只需 $0.0028 起，而且失败的请求从不计费。

GET /key-usage-info（在新标签页打开）显示还剩多少请求次数，且本身不算作请求，所以智能体可以在长任务开始前先查一下预算。

#让智能体的 X 调用既省钱又可靠

智能体一旦陷入循环就会浪费调用，所以要给每个 X 工具设置翻页预算，批量查询，并且只返回模型会读的字段。

• 批量查询。 一次 POST /tweet-info-bulk 调用最多发送 100 个帖子 ID，或一次 GET /info-batch 调用最多发送 100 个用户名，而不是发 100 次单独的调用。
• 给翻页设预算。 用 max_pages 参数防止智能体一页一页地读完 5 万条帖子的搜索结果。next_cursor 一返回为空就停下。
• 在任务内缓存。 同一个查询在一个任务里问两次，返回的是同样的帖子，所以保留第一次的答案。
• 处理 429 和 403。 每个密钥在所有套餐上都是每秒 20 次请求：遇到 429，等一秒再重试。403 表示密钥缺失，或账号的请求次数已用完。
• 按计划轮询。 每次请求返回的都是最新数据，所以监测类智能体只要按计划重新运行搜索，并在查询里加上 since:，就能保持最新。指南Twitter 实时监测演示了这个循环。

响应的 schema 保持稳定，所以你的工具代码可以一直用下去。

#今天就给你的智能体接入 X 数据

你的智能体几分钟内就能读取 X：自己构建的智能体用 REST 工具，Claude Code 和 Cursor 用 MCP 服务器，编程智能体用技能。Sorsa API 用一个只读密钥支持这三种方式，帖子每 1,000 条 $0.014 起，而官方 X API 是 $5.00，所有套餐统一每秒 20 次请求，自 2022 年起投入生产，累计处理请求超 60 亿次。前 100 次请求免费，足够智能体读取最多 1 万条帖子。

#常见问题