作者:Sorsa 编辑部

更新于 2026 年 7 月 31 日:重写为完整参考手册,覆盖 X API v2 的每一个接口类别(约 100 个接口,2026 年 7 月底对照 X 官方速率限制表重新核实)。新增媒体、书签、Space、趋势、流式和 webhook 的限制,扩充免费版一节,并同步 2026 年 4 月仅限 Enterprise 的变动和 2026 年 5 月账号上限的下调。

核心要点: X API v2 的速率限制按接口设定,分为按应用(Bearer Token)和按用户(OAuth)两个池,在 15 分钟或 24 小时窗口上重置。近期搜索允许每用户每 15 分钟 300 次请求,发帖 100 次。超出任何一项限制都会返回 HTTP 429,响应头 x-rate-limit-reset 会给出窗口重新打开的确切时间。

能拦下你请求的其实有三套系统,报错却长得几乎一样。开发者应用受 X API 的逐接口速率限制约束。用来发帖的 X 账号另外受账号级上限约束,未认证账号现在低至每天 50 条帖子。按量付费余额压在这两层之上,还有每月 200 万次帖子读取的用量上限。三者中撞上任何一个,采集都会当场停住,所以“明明离速率限制还远”才会成为一句这么常见又让人困惑的抱怨。

本指南用当前数字把这三层讲完,先从完整的逐接口限制表开始。我们运营 Sorsa API,一个 Twitter/X API 替代方案,所以这些限制和随之而来的 429,我们每天都在碰,既在自己的数据管道里,也在经手的各类迁移中。这也是我们把 Sorsa 做成没有这些限制的原因:所有接口统一 20 次/秒,没有 15 分钟窗口,也没有按应用与按用户之分要周旋;批量接口上读取成本每 1,000 条推文 $0.02 起,官方按量付费则是每 1,000 次帖子读取 $5.00;注册即送 100 次免费请求,可以直接拿来试。下面的数字是你现在在官方 X API 上要面对的,再往下我们把两个模型并排放。

最后核实:2026 年 7 月 31 日,对照 X 官方的速率限制和账号限制文档。

大家查得最多的几个限制

如果你只是来查一个数字,那它大概率就在下表里。完整内容都在后文。

你要查的当前限制(2026 年)
推文搜索(近期)每用户每 15 分钟 300 次,每应用 450 次
通过 API 发推文每用户每 15 分钟 100 次,每应用每 24 小时 1 万次
删除推文每用户每 15 分钟 50 次
粉丝或关注列表每 15 分钟 300 次(按应用和按用户都一样)
用户时间线每用户每 15 分钟 900 次,每应用 1 万次
批量推文查询每用户每 15 分钟 5,000 次,每次调用最多 100 条推文
读取私信每用户每 15 分钟 15 次
通过 API 关注、点赞、引用发帖自 2026 年 4 月 20 日起仅限 Enterprise
免费版2026 年 2 月起停用
未认证账号发帖(所有渠道合计)每天 50 条原创帖子 + 200 条回复

目录


X API 速率限制如何运作 {#how-x-api-rate-limits-work}

X API v2 的速率限制按接口设定,没有单一的全局数字。多数接口在 15 分钟滚动窗口上重置;少数接口用 24 小时窗口,比如发帖和媒体上传;另有几个流式和存档接口再加一层每秒上限。窗口从你对该接口的第一次请求开始计算,不是从整点开始,所以“每 15 分钟 300 次”指的是任意滚动 15 分钟内 300 次请求。

按应用与按用户限制

每个接口最多追踪两个互相独立的池:

按应用限制在你用 Bearer Token(仅应用认证)时生效。应用发出的每个请求都从同一个共享池里扣,不管是哪个用户触发的。一万个用户同时打你的后端,花的都是同一份按应用配额。

按用户限制在你用 OAuth 1.0a 或 OAuth 2.0 用户令牌认证时生效。每个已认证用户各有一份独立配额。有 100 个用户,就有 100 份各自独立的“近期搜索每 15 分钟 300 次请求”。

有些接口两个池都开放,有些只开一个。下面各表中的 n/a 表示该调用不支持这种认证方式。

从响应头读你的限制

每个 X API 响应都带三个头,直接告诉你当前处境:

x-rate-limit-limit: 900
x-rate-limit-remaining: 847
x-rate-limit-reset: 1705420800

x-rate-limit-limit 是当前窗口的上限,x-rate-limit-remaining 是你还剩多少,x-rate-limit-reset 是窗口重置时间的 Unix 时间戳。解析这个时间戳再减去当前时间,就能精确知道还要等几秒。完全不用猜。

速率限制、用量上限、账号限制的区别

这个区别绊倒的开发者比任何单个数字都多,所以把三层并排列出来:

层级管什么举例在哪里咬人
API 速率限制你的应用调用每个接口有多快每 15 分钟 300 次搜索请求爆发式采集、轮询循环
用量上限(计费)你每月消耗多少数据按量付费每月 200 万次帖子读取任何持续运行的读取管道
账号限制X 账号本身在平台级能做什么未认证账号每天 50 条原创帖子发帖自动化

X 在 2026 年初转向按量付费之后,你抓取的每条资源都要花钱,标准账号还压着每月 200 万次帖子读取的硬性上限。你完全可能舒舒服服待在 15 分钟速率限制之内,却因为烧穿了月度上限而被拦住。成本这一侧的完整情况,包括按动作定价、24 小时去重窗口,以及 2026 年 4 月 20 日改了什么,见我们的 X API 价格详解

还要再区分一点:如果你是普通 X 用户,在刷推或发帖时看到“rate limit exceeded”,那是平台侧的上限,不是开发者 API。这部分我们单独写成了一篇:X 上“rate limit exceeded”是什么意思、怎么解决。下文全部是写给调用 API 的开发者的。


X API 速率限制表:每个接口 {#x-api-rate-limit-tables-every-endpoint}

X 官方文档目前列出约 100 个接口,分布在十几个类别里。下面的表把它们全部覆盖,按“你要做什么”分组,而不是按 X 内部的产品分类。所有数字都读自 X 官方速率限制表,并在 2026 年 7 月 31 日重新核查。除另有标注外,限制均为每 15 分钟。

搜索与推文查询的速率限制

接口方法按应用按用户说明
/2/tweets/search/recentGET450300最多 100 条结果,查询 512 字符,回溯 7 天
/2/tweets/search/all(全量存档)GET300 + 1/秒1/秒最多 500 条结果,查询 1,024 字符,可回溯到 2006 年,仅限付费套餐
/2/tweets/counts/recentGET300n/a只返回计数,不含推文内容
/2/tweets/counts/allGET300n/a只返回计数
/2/tweets(批量查询)GET3,5005,000每次调用最多 100 个推文 ID
/2/tweets/:id(单条推文)GET450900

搜索值得细看,因为它拆成两个接口,上限差别很大。近期搜索给每用户每 15 分钟 300 次请求,但只回溯 7 天,这覆盖了大多数通过 API 跑的推文搜索。全量存档搜索能一路查到 2006 年,却把你限死在每秒 1 次请求,没法爆发式采集。需要历史深度的话,每秒 1 次这个硬性上限就是你要围绕它做规划的数字;怎么在这个限制下干活,见我们的拉取历史 Twitter 数据指南。

时间线与提及的速率限制

接口方法按应用按用户说明
/2/users/:id/tweetsGET1 万900按 ID 取用户时间线
/2/users/by/username/:username/tweetsGET1,500900按用户名取用户时间线
/2/users/:id/mentionsGET450300
/2/users/by/username/:username/mentionsGET450180
/2/users/:id/timelines/reverse_chronologicalGETn/a180主页时间线,仅支持用户令牌

发帖、删除与媒体的速率限制

接口方法按应用按用户说明
/2/tweets(发帖)POST1 万 / 24 小时100见下方账号上限一节
/2/tweets/:id(删帖)DELETEn/a50
/2/tweets/:tweet_id/hidden(隐藏回复)PUTn/a50
/2/media/uploadPOST5 万 / 24 小时500
/2/media/upload(状态查询)GET10 万 / 24 小时1,000
/2/media/upload/initialize/append/finalizePOST各 18 万 / 24 小时各 1,875分片上传
/2/media/metadataPOST5 万 / 24 小时500
/2/media/subtitlesPOST / DELETE1 万 / 24 小时100

对多数发帖自动化来说,真正要记住的是两个数字:每用户每 15 分钟 100 条帖子,每用户每 15 分钟 50 次删除。两者都是 API 侧的上限,但通常先卡住你的是下文的账号级上限。

互动数据查询的速率限制(点赞、转发、引用)

接口方法按应用按用户说明
/2/tweets/:id/retweeted_byGET7575
/2/tweets/:id/retweetsGET7575
/2/tweets/:id/quote_tweetsGET7575
/2/tweets/:id/liking_usersGET7575
/2/users/:id/liked_tweetsGET7575
/2/users/reposts_of_meGETn/a75最多 100 条结果

所有互动数据查询都统一压在每 15 分钟 75 次,是整个 API 里最紧的读取上限之一。想盘点一条爆款帖子的转发用户或点赞用户,这点额度很快就见底。

互动写入的速率限制(2026 年 4 月起仅限 Enterprise)

接口方法按应用按用户说明
/2/users/:id/likes(点赞)POST / DELETEn/a50 + 1,000 / 24 小时仅限 Enterprise
/2/users/:id/retweets(转发)POST / DELETEn/a50引用发帖仅限 Enterprise
/2/users/:id/following(关注)POST / DELETEn/a50仅限 Enterprise

自 2026 年 4 月 20 日起,X 把关注、点赞和引用发帖从所有自助套餐中移除。上面这些限制仍留在 X 的表里,但现在只在 Enterprise 合同下适用。发帖和私信在按量付费上仍然可用。

用户查询与粉丝接口的速率限制

接口方法按应用按用户说明
/2/users(批量,按 ID)GET300900每次调用最多 100 个用户
/2/users/:id/2/users/by/2/users/by/username/:usernameGET300900所有查询变体的池结构一致
/2/users/meGETn/a75
/2/users/searchGET300900
/2/users/:id/followersGET300300每页最多 1,000 条
/2/users/:id/followingGET300300每页最多 1,000 条

粉丝接口和关注接口共用同一份每 15 分钟 300 次的限制,两个池都一样。按每页 1,000 条结果算,翻完一个百万粉丝的账号要 16 到 17 个窗口,约四小时实际耗时。如果大规模拉取粉丝和关注列表是你的核心负载,这个节奏就是设计时要围绕的约束。

私信的速率限制

接口方法按应用按用户说明
/2/dm_events 及按会话读取GETn/a15所有私信读取变体
/2/dm_conversations/...(发送消息)POST1,440 / 24 小时15 + 1,440 / 24 小时
/2/dm_events/:id(删除)DELETE4,000 / 24 小时300 + 1,500 / 24 小时
/2/users/:id/dm/block/dm/unblockPOST25 + 1,000 / 24 小时10 + 400 / 24 小时

每用户每 15 分钟只有 15 次读取,私信密集的工作流几乎立刻就撞上限;发送侧的 24 小时上限则是刻意把这里的自动化拖慢。

列表的速率限制

接口方法按应用按用户说明
/2/lists/:idGET7575
/2/lists/:id/tweetsGET900900
/2/lists/:id/membersGET900900
/2/users/:id/owned_listsGET1515
/2/users/:id/list_membershipsGET7575
创建 / 更新 / 删除列表POST / PUT / DELETEn/a300
添加 / 移除列表成员POST / DELETEn/a300
关注 / 取关列表POST / DELETEn/a50
/2/users/:id/pinned_listsGET1515置顶 / 取消置顶:每用户 50

列表推文和列表成员都给到每 15 分钟 900 次,属于 API 里最宽松的读取限制,这也是列表至今仍是热门监测替代路径的原因。

Space、趋势、社区、分析与新闻的速率限制

接口方法按应用按用户说明
Space 查询(/2/spaces/:id 及各变体)GET300300/2/spaces/by/creator_ids 另加每秒 1 次上限
/2/spaces/searchGET300300
/2/users/personalized_trendsGET200 + 200 / 24 小时10 + 100 / 24 小时
/2/trends/by/woeid/:idGET75n/a按地区取趋势
/2/communities/:id/2/communities/searchGET300300社区产品已于 2026 年 5 月关停,X 的表里仍列着
/2/tweets/analyticsGET300300
/2/news/:id/2/news/searchGET200200(仅搜索)

书签、拉黑与静音的速率限制

接口方法按应用按用户说明
/2/users/:id/bookmarksGETn/a180
书签文件夹GET5050
添加 / 移除书签POST / DELETEn/a50
/2/users/:id/blockingGETn/a15
/2/users/:id/mutingGETn/a15静音 / 取消静音:每用户 50

流式与 webhook 的速率限制

接口方法按应用说明
/2/tweets/search/stream(过滤流)GET50 次连接尝试1 条活动连接,1,000 条规则,每秒推送 250 条帖子
/2/tweets/search/stream/rulesGET / POST读 450 / 写 100
/2/tweets/sample10/streamGET10010% 抽样
/2/activity/streamGET4502 条连接,每秒 250 条帖子
活动订阅POST / GET / PUT / DELETE500
Webhook 增删改查POST / GET / PUT / DELETE450重放:100

流式接口只支持仅应用认证。关键在于理解它管的是什么:限制卡的是连接尝试和规则变更,不是推送量。所以一条健康的流式连接,效果胜过任何轮询循环。

合规与用量的速率限制

接口方法按应用说明
/2/compliance/jobs(创建、查询、列出)POST / GET150
/2/usage/tweetsGET50你自己的消耗统计

X API 发帖速率限制:API 上限与账号上限 {#x-api-posting-rate-limits-api-caps-vs-account-caps}

2026 年,X 在两个各自独立的层面上执行发帖限制,而真正拦住你的几乎从来不是 API 那一层。

API 写入接口(/2/tweets)允许每用户每 15 分钟 100 条帖子,每应用每 24 小时 1 万条。除此之外,你发帖所用的 X 账号还受账号级上限约束,这个上限横跨网页端、移动端和 API 一并生效。2026 年 5 月,未认证账号的这个上限降到每天 50 条原创帖子和 200 条回复,此前长期是 2,400 条。

坑就在这里。开发者读到 API 限制(每 15 分钟 100 条看着很宽裕,折合每用户每天近 9,600 条)就照它架构,结果机器人发到 50 条就停了。API 限制从来不是真正的约束:

  • 未认证账号 + API 自动化: 每天 50 条原创帖子的账号上限,远早于 API 窗口起作用。回复另有每天 200 条的单独上限;转帖和引用普遍反馈也计入这 50 条,不过 X 没有正面说明。
  • 已认证或 Premium 账号 + API 自动化: 账号级上限更高(X 不公布确切数字),此时 API 写入限制才成为真正的天花板。
  • 应用级规模: 即便手上有很多已认证用户,每应用每 24 小时 1 万条帖子对高频发布来说仍是一堵硬墙。

X 的账号限制文档写得很明确:这些上限会把来自所有设备的动作合并计数,网页端、移动端和 API 一起算。所以你的脚本和你的手机共享同一个每日发帖预算。最常被自动化触及的账号级上限如下:

动作未认证账号,每天
原创帖子50
回复200
关注400
发送私信500

账号侧的完整情况,包括已认证档位的上限、半小时子区间,以及 2026 年 5 月改了什么,见我们专门的 X 发帖限制与每日帖子上限指南。

发帖也是只读替代方案唯一帮不上忙的环节。Sorsa 这类服务商是为大规模读取 X 数据做的,不是为写入。所以如果你的场景是自动发布,官方 API 的写入接口绕不开,上面这些就是你要长期面对的限制。


2026 年 X API 免费版的限制 {#x-api-free-tier-limits-in-2026}

2026 年,新开发者拿不到通用的免费 X API 版本。独立的免费版在 2026 年 2 月按量付费上线时停用,新账号在发起任何调用之前必须先买额度。仅剩的免费访问,是面向指定公共事业类应用、需要审批的一个窄口子。

如果你还想拿遗留免费版做对比,它的速率限制从设计上就一直很严:

  • 只能写。 帖子读取权限为零:没有时间线,没有搜索,也没有推文查询。
  • 发帖接口每 24 小时 17 次请求,按应用和按用户合并计算,实际折合每月约 500 条帖子,而 X 当时对外宣传的是“每月 1,500 条帖子”。
  • 24 小时窗口,不是付费访问上那种更友好的 15 分钟窗口。

换句话说,免费版从来就没有能用来读取 X 数据的速率限制,现在对新注册更是彻底没有了。今天想测试读取,实用的免费路径要走第三方:注册即送 100 次免费请求,一次性发放,无需绑卡,永不过期。这些额度覆盖全部 40 个接口,享受与付费套餐相同的 20 次/秒;走批量接口的话,在你花一分钱之前最多可覆盖 1 万条推文或 2 万份用户资料。官方访问和密钥现在怎么办,见我们的全流程讲解:2026 年如何获取 X API 密钥


你每天实际能拉多少推文? {#how-many-tweets-can-you-actually-pull-per-day}

单看速率限制数字说明不了太多。真正要紧的是吞吐:一天下来你现实能采到多少推文、用户资料或粉丝记录。下面按最常见的几个场景算一笔账,均假设按用户认证。

推文搜索(近期)

  • 速率限制:每 15 分钟 300 次请求 = 1,200/小时 = 2.88 万/天
  • 每次请求最多结果:100
  • 理论上限:每天 288 万条推文

听着很宽裕,但按量付费的计费上限是每月 200 万次帖子读取。持续搜索不到一天,你就能把整月额度烧光。这里速率限制不是瓶颈,月度上限才是。

用户时间线

  • 速率限制:每 15 分钟 900 次请求 = 3,600/小时
  • 每次请求结果:约 20(不固定)
  • 理论上限:每个账号每小时约 7.2 万条推文

抓单个时间线时,速率限制很少构成约束。真正的限制是这个账号一共发过多少推文。

粉丝

  • 速率限制:每 15 分钟 300 次请求 = 1,200/小时
  • 每页最多结果:1,000
  • 理论上限:每小时 120 万条粉丝记录

X 每页最多返回 1,000 个粉丝,这让它成为吞吐较高的读取接口之一。作为对比,Sorsa 按请求计费,粉丝接口每次请求最多返回 200 份用户资料,没有 15 分钟窗口,只有统一的 20 次/秒,折算下来约每秒 4,000 份资料,约每小时 1440 万份。关系图一大,差距很快就叠出来了。

真正的瓶颈,总结

场景速率限制上限(每天)计费上限(每月)哪个先撞上
近期搜索(100/请求)约 288 万条推文200 万次帖子读取计费上限
用户时间线(20/请求)约 170 万条推文200 万次帖子读取取决于规模
粉丝采集(1,000/页)约 2880 万条记录无特定上限,但 $0.01/条成本
发推文1 万(应用)或 9,600(用户)账号上限(未认证 50/天)账号上限,其次速率限制

只要读取工作到了有意义的规模,你先撞上的一定是月度计费上限,不是速率限制。速率限制主要在三种情况下才真正成为瓶颈:写入场景、互动数据查询那个每窗口 75 次的紧上限,以及仅应用认证下的高并发管道。


标准与 Enterprise 速率限制 {#standard-vs-enterprise-rate-limits}

上面讲的都是标准(按量付费)速率限制。Enterprise 是另一个世界。Enterprise 客户直接与 X 销售团队谈定制限制,细节不公开,但大致轮廓是已知的:

  • 定制的逐接口限制,通常远高于标准
  • 更高的月度用量上限,或者直接取消(200 万次帖子读取的上限可以消失)
  • 2026 年 4 月从自助套餐移除的那些互动写入(关注、点赞、引用发帖)
  • 并发更高的全量存档搜索,外加带定制限制的 Activity API 和 webhook 访问

Enterprise 的起步价历史上约 4.2 万美元/月,不过这个数字可能随按量付费的转变有所调整。审批带有选择性,接入可能要花上几周。

谁真正需要 Enterprise?

Enterprise 适合把 X 数据转售给自己客户的大型 SaaS 平台、跑实时模型的金融公司,以及每月处理数百万条帖子的研究团队。如果你既需要每月超过 200 万次帖子读取,又需要写入权限,Enterprise 是官方 API 上唯一的路。

如果你要的是读取操作上的高吞吐,又不想付 Enterprise 的价,这正是第三方服务商填补的缺口,也是我们做 Sorsa 的位置。我们的统一 20 次/秒适用于所有套餐,包括 $49/月的 Starter,没有逐接口的限制表,也没有 15 分钟窗口要管;高用量场景可以通过联系销售按需提高。取舍也说清楚:Sorsa 只读,不发帖、不发私信,也不做点赞或关注这类写入。如果你只要单次读取绝对最便宜、并且愿意自己拼可靠性,市面上有更简陋的选择;如果你要的是价格固定、可靠且完整的读取访问,那正是我们做的事。更全面的横向对比见我们的 X API 替代方案梳理。

具体到读取负载,两个模型这样对齐:

官方 X API(按量付费)Sorsa API
速率限制模型按接口,15 分钟和 24 小时窗口所有接口统一 20 次/秒
应用池与用户池两个独立池要管理单个密钥,不分池
认证OAuth 2.0 + Bearer Token,需应用审批单个 API 密钥,即时可用
每 1,000 条推文成本$5.00$0.02 起(批量接口)
每 1,000 份资料成本$10.00$0.01 起(批量接口)
每月上限200 万次帖子读取按套餐(1 万到 50 万次请求)
写操作发帖和私信可自助;点赞、关注、引用发帖仅限 Enterprise无(只读)

在 Sorsa 的批量接口上,这折算为每 1,000 条推文 $0.02 起;即便走最朴素的搜索翻页,Pro 套餐上也保持在每 1,000 条约 $0.10,而官方按量付费是每 1,000 次帖子读取 $5.00。对读密集型采集来说,这意味着每次读取最多可比官方 API 便宜 50 倍,逐接口窗口也彻底消失。留在官方 API 的理由是写入:任何发帖、发私信或点赞的动作仍然必须在官方 API 上跑,因为 Sorsa 从产品设计上就是只读。我们见得最多的务实模式是:写入留在官方 API,重读取迁到按请求计费的替代方案。怎么干净地完成这次切换,见我们的迁移指南


撞上速率限制(429)时会发生什么 {#what-happens-when-you-hit-a-rate-limit-429}

超出速率限制时,X 返回 HTTP 429,响应体如下:

json
{
  "errors": [{
    "code": 88,
    "message": "Rate limit exceeded"
  }]
}

响应里仍然包含速率限制头,那才是关键部分。x-rate-limit-reset 告诉你窗口具体什么时候重新打开,所以你永远不必盲目地睡一个固定间隔。

恰当的恢复策略

最朴素的做法是固定睡 15 分钟再重试。能用,但很浪费。更好的做法是读取重置时间戳,只等窗口实际需要的那么久:

python
import time
import requests

def request_with_rate_limit_handling(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code != 429:
            return response

        reset_timestamp = int(response.headers.get("x-rate-limit-reset", 0))
        wait_seconds = max(reset_timestamp - int(time.time()), 1)
        print(f"Rate limited. Waiting {wait_seconds}s until window resets.")
        time.sleep(wait_seconds + 1)  # +1 秒缓冲

    raise Exception("Rate limit retries exhausted")

有几点要留意。

不要立刻重试。 没有延迟的重试循环会在应用级认证下把其他接口的剩余请求一起烧掉,还可能触发更激进的限流。

批量采集管道里不要忽视 429。 在紧密的采集循环里,一个 429 可能意味着代码察觉之前已经有几百个请求失败了。每次请求之前检查 x-rate-limit-remaining,掉到 10 到 20 以下就暂停。

记录剩余请求数。 排查速率限制问题时,一份 x-rate-limit-remaining 的时间序列日志是最有用的东西,能精确显示哪种调用模式在榨干你的预算。

确认你撞上的到底是三层里的哪一层。 如果 429 伴随速率限制头接近零,那是接口窗口。如果窗口重置之后仍然被拦,通常是月度用量上限或账号级上限,这两种情况再怎么退避都没用。


如何待在速率限制之下 {#how-to-stay-under-rate-limits}

常见建议(“缓存响应”“用指数退避”)没错,但不完整。下面这些动作才真正改变这笔账,取自我们经手的管道迁移。

1. 用批量接口,别做单条查询

/2/tweets 接口一次请求最多接收 100 个推文 ID:一次请求、一次速率限制消耗、返回 100 条推文。改成做 100 次单条 /2/tweets/:id 调用,就要从一个更紧的限制里消耗 100 次(450/15 分钟,批量则是 3,500/15 分钟)。/2/users 同理,一次最多接收 100 个用户名或 ID。

第三方 API 把批量推得更远。我们的批量推文接口每次请求接收 100 个推文 URL 或 ID,批量资料查询接收 100 份用户资料,各自都只从你的额度里扣一次请求。更多压缩请求量的做法,见我们关于优化 API 用量的说明。

2. 用流式,别轮询

每 30 秒轮询一次 /2/tweets/search/recent,等于对这一个接口每天发 2,880 次请求。X 的过滤流通过一条持久连接实时把匹配的推文推给你:一个连接,每秒最多 250 条匹配帖子。坑在于每 15 分钟只允许 50 次连接尝试,且同时只能有 1 条活动连接;但对监测关键词或账号来说,它完胜轮询。更深入的内容见我们的实时 Twitter 监测指南。

3. 积极缓存用户资料

用户资料变化很慢。显示名、简介和粉丝数是按天变,不是按分钟变。如果你的应用在拉推文时也要取用户数据,给资料设 12 到 24 小时的 TTL,缓存命中就跳过调用。互动指标变得更快,做分析的话 1 到 6 小时的 TTL 通常比较合适;实时仪表盘则只能靠新鲜调用,没有更好的替代。

4. 监控响应头,主动降速

别等 429 才放慢。在每个响应上追踪 x-rate-limit-remaining,加一个软阈值:掉到限制的约 10% 以下时就主动放慢,别等撞墙。

python
remaining = int(response.headers.get("x-rate-limit-remaining", 100))
if remaining < 30:   # 软阈值
    time.sleep(2)    # 硬停之前先温和降速

5. 分散到多种认证方式

按应用和按用户限制是两个独立的池。如果你同时用 Bearer Token 和 OAuth 用户令牌认证,对两者都支持的接口,你实际上拿到了两份配额。比如推文查询允许每应用每 15 分钟 3,500 次并且每用户每 15 分钟 5,000 次,两个都用净得每 15 分钟 8,500 次。这一招只在你的架构支持双认证路径时有用;服务端很直接,纯客户端应用通常做不到。

真正开始烧额度之前,还有一个工具值得知道:X 在 2025 年 12 月放出了自托管的 API Playground,可以在本地模拟 v2 接口,包括速率限制模拟。你可以用它把退避逻辑和响应头处理跑通,一次真实请求都不花。


实战:不断撞 429 的金融科技分析团队

某小型金融科技分析团队,约八名工程师,在他们的 X 数据管道反复卡住之后找到我们。他们每 30 秒轮询一次近期搜索来捕捉影响市场的帖子,再按作者扇出查询用户资料。让他们想不通的是,“每 15 分钟 300 次”的限制为什么会在采集中途反复触发 429。原因很常见:仅应用认证意味着每次资料查询和每次搜索都从同一个按应用池里扣,光是轮询节奏就吃掉了其中大部分。

我们没有把他们仍然需要的写入从官方 API 迁走,只把读密集的采集换成按请求计费的模型,并把轮询改成事件驱动。在官方 API 的按资源定价下,这个读取量正好卡在“按量付费还算便宜”和“4.2 万美元的 Enterprise 合同”之间那个尴尬地带。在这个量级上,我们的套餐每次读取最多可比官方 API 便宜 50 倍,他们账单的读取侧降到每月两三百美元;逐接口窗口一旦不存在,429 也就消失了。写入路径留在官方 API 上,本来也该留在那里。


常见问题 {#frequently-asked-questions}

X API 的速率限制是按用户还是按应用?

两者都有,取决于接口和你的认证方式。Bearer Token(仅应用)认证走按应用限制,应用发出的每个请求共享同一个池。OAuth 用户令牌认证走按用户限制,每个已认证用户各有一份独立配额。很多接口同时公布按应用和按用户两个数字,有些只公布一个。X 官方的速率限制表标明了每个接口适用哪一种。

X API 发帖的速率限制是多少?

API 写入接口(/2/tweets)允许每用户每 15 分钟 100 条帖子,每应用每 24 小时 1 万条,删除则限每用户每 15 分钟 50 条。实际上先卡住你的是账号级上限:未认证的 X 账号每天只能发 50 条原创帖子和 200 条回复,API、网页端和移动端合并计数。

X API 搜索的速率限制是多少?

近期搜索(/2/tweets/search/recent)允许每应用每 15 分钟 450 次请求、每用户每 15 分钟 300 次,每次最多返回 100 条结果,查询限 512 字符。全量存档搜索(/2/tweets/search/all)允许每秒 1 次请求、15 分钟上限 300 次,每次调用最多返回 500 条结果,可回溯到 2006 年,且仅限付费套餐。

X API 的速率限制窗口有多长?

多数 X API v2 接口用 15 分钟滚动窗口。少数用 24 小时窗口,包括发帖接口(每应用每 24 小时 1 万条)、媒体上传和几个私信上限,另有少数流式和存档接口再加一层每秒上限。每个窗口从你对该接口的第一次请求开始计算,不是从整点开始。

2026 年 X API 有速率限制够用的免费版吗?

没有。X 在 2026 年 2 月停用了独立的免费版,新开发者一上来就是按量付费,没有免费额度。遗留免费版只能写,发帖接口每 24 小时限 17 次请求,帖子读取权限为零,从来就不支持大规模读取 X 数据。现在唯一的免费访问,是面向指定公共事业类应用、需要审批的项目。想不花钱测试读取访问,Sorsa API 注册即送 100 次免费请求:一次性发放,无需绑卡,永不过期,覆盖全部 40 个接口。

X 的账号限制和 API 速率限制是一回事吗?

不是,这是两套独立的系统。API 速率限制管的是开发者应用调用每个接口有多快,比如每用户每 15 分钟 100 条帖子。账号限制管的是一个 X 账号在平台级能做什么,比如未认证账号每天 50 条原创帖子。关键在于,账号限制同样把 API 动作计入,所以自动发帖和手动发帖共享同一个每日预算。

不上 Enterprise 能提高 X API 的速率限制吗?

在官方 API 上不能。标准速率限制是固定的,只有签 Enterprise 协议才会提高。可行的绕过方案是批量(每次请求多拿数据)、流式(避开轮询),以及把请求分散到应用认证和用户认证。官方 API 之外,专注读取的第三方服务商通常用统一的每秒限制取代逐接口窗口,也可以按需调高。

开发者怎样在没有 Enterprise 合同的情况下拿到高读取吞吐?

多数团队把读密集型工作迁到用统一速率限制、而非逐接口窗口的 Twitter/X API 替代方案。以 Sorsa API 为例,全部 40 个读取接口所有套餐统一 20 次/秒,批量接口上每 1,000 条推文 $0.02 起,套餐 $49/月起。在读取规模上,这比官方 API 的按资源定价最多可便宜 50 倍,同时去掉了 15 分钟窗口和按应用与按用户之分,采集管道里大多数 429 都由此而来。


如何开始

如果上面这些逐接口窗口和 429 正是你想摆脱的问题,感受差异最快的办法是自己跑几次调用。我们的在线试用工具 Playground 在浏览器里直接调用真实接口,无需密钥也无需注册,可以在投入之前先看清响应结构。准备好开工时,Sorsa API 快速上手用单个 API 密钥几分钟内完成认证。创建账号,领取 100 次免费请求(无需绑卡,永不过期,覆盖全部 40 个接口),走批量接口最多可覆盖 1 万条推文或 2 万份用户资料。之后付费套餐批量接口上每 1,000 条推文 $0.02 起,$49/月起,并享受上文那个统一的 20 次/秒。没有应用审核,没有 OAuth 握手,也没有要背下来的速率限制表。


审校:Keksich(Sorsa 创始人,X API 研究者)

本指南是怎么写成的:文中每一个接口数字都直接读自 X 官方的速率限制表,账号级上限读自 X 的限制文档。两者都在 2026 年 7 月 31 日重新核查,因为这些数字改动时往往不打招呼。X 在 2026 年 5 月刚把未认证账号的每日帖子上限从 2,400 降到 50,又在 2026 年 4 月把互动写入转为仅限 Enterprise。吞吐换算、429 恢复代码,以及“哪个限制先撞上”这个框架,来自我们自己构建并运营 Twitter/X API 替代方案的经验,也来自团队经手的读取管道迁移。上面那个金融科技案例已做匿名处理,细节做了合并,去除了任何可识别信息。定价和用量上限的结论总结自我们单独的 X API 定价内容。我们是谁、怎么联系我们,见关于 Sorsa。本文没有任何编造的统计数据、来源或客户成果。