Twitter API expansions 与推文作者

#Twitter API 的 expansions 是什么，会返回什么

expansion 是官方 X API v2 的一个请求参数，用来把相关对象（比如作者、图片或被引用的帖子）加进响应里。不加的话，查询帖子只会返回三个字段：id、text 和 edit_history_tweet_ids。作者不在其中，连作者的 ID 都没有。

加上 expansions=author_id 后，每条帖子会多出一个 author_id，响应里则多出一个 includes.users 列表，每位作者一项。这一项默认只有 id、name 和 username。其他内容，比如简介、粉丝数或头像，都必须在 user.fields 里点名。

下表列出开发者最常用的帖子 expansion，以及从 2026 年 11 月 22 日起适用的 X API 价格下各自的费用。每个用户对象的价格，是随它返回的那条帖子的两倍。

• author_id

  加入 includes 的内容

  帖子的作者

  官方 X API，11 月 22 日起每个对象

  $0.010

• referenced_tweets.id

  加入 includes 的内容

  被引用、被回复或被转发的帖子

  官方 X API，11 月 22 日起每个对象

  $0.005

• referenced_tweets.id.author_id

  加入 includes 的内容

  那条帖子的作者

  官方 X API，11 月 22 日起每个对象

  $0.010

• in_reply_to_user_id

  加入 includes 的内容

  被回复的账号

  官方 X API，11 月 22 日起每个对象

  $0.010

• entities.mentions.username

  加入 includes 的内容

  每个被提及的账号

  官方 X API，11 月 22 日起每个对象

  $0.010

• attachments.media_keys

  加入 includes 的内容

  每张图片、视频或 GIF

  官方 X API，11 月 22 日起每个对象

  $0.005

• attachments.poll_ids

  加入 includes 的内容

  投票

  官方 X API，11 月 22 日起每个对象

  $0.005

• geo.place_id

  加入 includes 的内容

  标记的地点

  官方 X API，11 月 22 日起每个对象

  $0.005

这些费率来自 X 在 2026 年 10 月 23 日发布的 expansions 计费通知（在新标签页打开），通知写明，通过 expansions 返回的对象将"按该资源的标准 PPU 费率计费，与直接查询相同"。在此之前，它们在帖子本身的费用之外不收钱。

#用 Sorsa API 一次调用拿到推文和作者

Sorsa API 是一款 Twitter（X）API 与爬虫，它返回的每条推文里都有一个 user 对象：作者的完整公开资料，共 19 个字段，不额外收费。不需要加 expansion，不需要再去拼接第二个列表，也没有按作者计费。用你的 API 密钥发一次请求，就能拿到推文，而且每条推文都已经带着作者。

1. 获取密钥。 注册后，从控制台复制 API 密钥。不需要 X 开发者账号，也不涉及 OAuth。

2. 发送最多 100 个推文链接或 ID。 POST /tweet-info-bulk（在新标签页打开）接收一组推文 URL 或纯 ID，在一个响应里全部返回，无需翻页。

   curl -X POST "https://api.sorsa.io/v3/tweet-info-bulk" \
     -H "ApiKey: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"tweet_links": ["1849212213712385091",
          "https://x.com/kai_builds_tools/status/1849212213712385092"]}'
   

   {
     "tweets": [
       {
         "id": "1849212213712385091",
         "full_text": "Shipped the new export queue today.",
         "created_at": "2026-10-24T09:12:44Z",
         "likes_count": 214,
         "retweet_count": 31,
         "view_count": 18402,
         "user": {
           "id": "1592041833471827968",
           "username": "kai_builds_tools",
           "display_name": "Kai Builds",
           "description": "Data tooling for small teams.",
           "followers_count": 1840,
           "followings_count": 312,
           "tweets_count": 2291,
           "verified": false,
           "created_at": "2022-11-14T08:03:10Z",
           "location": "Lisbon",
           "profile_image_url": "https://pbs.twimg.com/profile_images/1/kai.jpg"
         }
       }
     ]
   }
   

   显示完整响应

3. 直接从每条推文里读取作者。 资料就在 tweet["user"] 下，所以遍历这些推文的循环就是全部代码。

   import requests
   
   URL = "https://api.sorsa.io/v3/tweet-info-bulk"
   HEADERS = {"ApiKey": "YOUR_API_KEY"}
   
   
   def tweets_with_authors(ids):
       for start in range(0, len(ids), 100):
           batch = ids[start:start + 100]
           r = requests.post(URL, headers=HEADERS,
                             json={"tweet_links": batch})
           r.raise_for_status()
           for tweet in r.json()["tweets"]:
               author = tweet["user"]
               yield (tweet["id"], author["username"],
                      author["followers_count"], tweet["full_text"])
   

   const URL = "https://api.sorsa.io/v3/tweet-info-bulk";
   const headers = {
     ApiKey: "YOUR_API_KEY",
     "Content-Type": "application/json",
   };
   
   async function tweetsWithAuthors(ids) {
     const rows = [];
     for (let i = 0; i < ids.length; i += 100) {
       const body = JSON.stringify({ tweet_links: ids.slice(i, i + 100) });
       const res = await fetch(URL, { method: "POST", headers, body });
       if (!res.ok) throw new Error(`HTTP ${res.status}`);
       for (const t of (await res.json()).tweets) {
         rows.push([t.id, t.user.username, t.user.followers_count]);
       }
     }
     return rows;
   }
   

返回 403 表示密钥缺失或请求次数已用完；返回 429 表示一秒内超过 20 次请求，稍等片刻再重试。失败的请求从不计费。

搜索、时间线、回复和引用返回的推文，也都带有同样的 user 对象。POST /search-tweets（在新标签页打开）每页返回约 20 条推文及其作者，可以用 X 的搜索运算符检索回溯到 2006 年的公开帖子，并返回 next_cursor 用于翻到下一页，直到游标返回为空。

#在官方 X API 上把帖子和作者对应起来

要在官方 X API 上把帖子和作者对应起来，先把 includes.users 按用户 ID 建成字典，再用每条帖子的 author_id 去查。X 的 expansions 指南（在新标签页打开）提到，includes 里的对象不带位置信息，所以 ID 是两个列表之间唯一的联系。

curl -G "https://api.x.com/2/tweets" \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  --data-urlencode "ids=1849212213712385091,1849212213712385092" \
  --data-urlencode "expansions=author_id" \
  --data-urlencode "user.fields=description,public_metrics,profile_image_url"

{
  "data": [
    {
      "id": "1849212213712385091",
      "text": "Shipped the new export queue today.",
      "author_id": "1592041833471827968",
      "edit_history_tweet_ids": ["1849212213712385091"]
    },
    {
      "id": "1849212213712385092",
      "text": "Next up: retries with backoff.",
      "author_id": "1592041833471827968",
      "edit_history_tweet_ids": ["1849212213712385092"]
    }
  ],
  "includes": {
    "users": [
      {
        "id": "1592041833471827968",
        "name": "Kai Builds",
        "username": "kai_builds_tools",
        "description": "Data tooling for small teams.",
        "public_metrics": {"followers_count": 1840, "following_count": 312}
      }
    ]
  }
}

两条帖子，一位作者：includes.users 在每个响应里每位作者只列一次，而不是每条帖子列一次。所以这个列表往往比 data 短，按位置去索引，或者把 includes["users"]["username"] 当成单个对象来读，都会出错。下面的循环会翻页读取最近的搜索结果，并在各页之间共用同一个作者字典。

import requests

URL = "https://api.x.com/2/tweets/search/recent"
HEADERS = {"Authorization": "Bearer YOUR_BEARER_TOKEN"}
params = {
    "query": "from:kai_builds_tools",
    "max_results": 100,
    "expansions": "author_id",
    "user.fields": "description,public_metrics,profile_image_url",
}

authors, rows = {}, []
while True:
    page = requests.get(URL, headers=HEADERS, params=params).json()
    for user in page.get("includes", {}).get("users", []):
        authors[user["id"]] = user
    for post in page.get("data", []):
        author = authors.get(post["author_id"], {})
        rows.append((post["id"], author.get("username"), post["text"]))
    token = page.get("meta", {}).get("next_token")
    if not token:
        break
    params["next_token"] = token

读取作者时请用 .get()：被封禁或被屏蔽的账号可能不在 includes 里，而它的帖子仍在 data 中，这时响应会在 errors 数组里列出这个缺口。

转发或引用的作者

转发或引用本身是一条指向另一条帖子的帖子，它的 author_id 是转发者或引用者，不是原作者。要同时拿到原作者，需要请求三个 expansion：author_id、referenced_tweets.id 和 referenced_tweets.id.author_id。原帖会出现在 includes.tweets 里，它的作者与转发者一起出现在 includes.users 里，你通过 referenced_tweets[0].id 找到原帖，再用原帖的 author_id 找到作者。从 11 月 22 日起，这样一次转发要计两条帖子和两个用户的费用：$0.030。

在 Sorsa API 上，被转发的推文以 retweeted_status 返回，被引用的以 quoted_status 返回，两者都是完整的推文，里面各有自己的 user。

#2026 年 11 月 22 日起 expansions 怎么收费

从 2026 年 11 月 22 日起，expansion 加进来的每个对象都按直接读取计费：每个用户 $0.010，每条帖子、图片、视频、投票或地点 $0.005。因此一条带作者的帖子最高收费 $0.015，是原来 $0.005 的三倍。每条再加一张图片，最高 $0.020；再加上被引用的帖子及其作者，就到 $0.035。

X 在 UTC 的 24 小时内去重：按其按量付费价格页面（在新标签页打开），同一天内再次获取的同一资源不会重复计费。某位用户当天写了你读取的 50 条帖子，也只算一次。所以来自 200 位不同作者的 1,000 条帖子，帖子部分 $5.00，作者部分 $2.00，共 $7.00；来自 1,000 位作者的 1,000 条帖子则是 $15.00。去重在 UTC 午夜重置，X 称其为软性保证。

在 Sorsa API 上，价格不随推文携带的内容变化。按 ID 读取推文，每 1,000 条 $0.014 起，作者、被引用的帖子和媒体链接都包含在内；搜索结果每 1,000 条 $0.07 起。对比官方 X API 带作者的帖子每 1,000 条 $15.00，大约便宜 1,000 倍。

• 仅帖子

  Sorsa API

  $0.014 起

  官方 X API，11 月 22 日起

  $5.00

• 帖子加作者

  Sorsa API

  $0.014 起

  官方 X API，11 月 22 日起

  最高 $15.00

• 每条再加一张图片或一段视频

  Sorsa API

  $0.014 起

  官方 X API，11 月 22 日起

  最高 $20.00

• 再加被引用的帖子及其作者

  Sorsa API

  $0.014 起

  官方 X API，11 月 22 日起

  最高 $35.00

计算器会按你用到的 expansions，估算一个月读取帖子的费用。它把每位作者都算作新作者，也就是区间的上限；选择重复作者，可以看到去重的效果。

须知

X 的按量付费套餐每月读取 300 万条帖子后停止；超过之后，官方 X API 只能走 Enterprise 合同，每月约 4.2 万美元起。在 Sorsa API 上，套餐越大，每 1,000 条推文的价格越低，而且所有套餐的每条推文都包含作者。

#为什么作者不再放在推文里面

作者原本就是推文的一部分。在 v1.1 的格式里，每个推文对象都带一个 user 对象，里面是作者资料，所以一条推文是自包含的，twarc 文档（在新标签页打开）也这么说。2020 年发布的 API v2 把每个对象砍到只剩几个默认字段，把相关对象移到 includes 里，只能通过 expansions 获取。

到目前为止，这种拆分增加的是代码量，不涉及费用：通过 expansions 返回的对象不计入用量，所以 expansion 只是省掉了第二次请求。2026 年 10 月的通知改变的正是费用这一块。从 11 月 22 日起，你从 includes.users 里拼接出来的作者，会按单独查询计费。

在这一点上，Sorsa API 的推文和 v1.1 的很像：user 就在里面。为 v1.1 写的代码如果读取 tweet["user"]["screen_name"]，只需要换一个键名 username；指南从 Twitter/X API 迁移按接口逐个对应了 v2 代码库的其余部分。

#每条 Sorsa API 推文附带哪些作者字段

每条 Sorsa API 推文的 user 下都带 19 个作者字段，不需要另外请求。下表把大多数代码用得到的字段，对应到你在官方 X API 的 user.fields 里要列出的名称。

• username

  官方 X API 的 user.fields 名称

  username

• display_name

  官方 X API 的 user.fields 名称

  name

• description

  官方 X API 的 user.fields 名称

  description

• followers_count

  官方 X API 的 user.fields 名称

  public_metrics.followers_count

• followings_count

  官方 X API 的 user.fields 名称

  public_metrics.following_count

• tweets_count

  官方 X API 的 user.fields 名称

  public_metrics.tweet_count

• profile_image_url

  官方 X API 的 user.fields 名称

  profile_image_url

• created_at

  官方 X API 的 user.fields 名称

  created_at

• location

  官方 X API 的 user.fields 名称

  location

• verified

  官方 X API 的 user.fields 名称

  verified

• protected

  官方 X API 的 user.fields 名称

  protected

• pinned_tweet_ids

  官方 X API 的 user.fields 名称

  pinned_tweet_id

• bio_urls

  官方 X API 的 user.fields 名称

  entities.description.urls

另外六个是 id、favourites_count、media_count、profile_background_image_url、can_dm 和 possibly_sensitive。ID 以字符串返回，日期采用 ISO 8601 格式。推文、用户资料和其他对象包含的全部内容，见指南 Twitter API 能获取哪些数据。

如果你的起点是一份推文 ID 列表，指南还原推文 ID讲了如何处理数百万条的列表，每次请求 100 个 ID。

#读取你的第一批带作者的推文

在官方 X API 上，帖子的作者是一个 expansion：要多拼接一个列表，而且从 2026 年 11 月 22 日起，在 $0.005 的帖子费用之上，每位作者另收 $0.010。想一次拿到推文和作者，就用 Sorsa API：POST /tweet-info-bulk 每次请求返回 100 条推文，每条里面都有作者的完整资料，每 1,000 条 $0.014 起，所有套餐统一每秒 20 次请求。

Sorsa API 从不要求你的 X 登录信息，所以你自己的账号永远不会有风险，而且它在设计上就是只读的：要发帖，请搭配官方 X API 使用。你的 100 次免费请求，可以读取前 1 万条带作者的推文。

#常见问题