X API v2 对每个端点分别限速,窗口为 15 分钟或 24 小时,应用(Bearer token)和用户(OAuth)各有一个额度池。超限返回 HTTP 429(错误码 88),直到 x-rate-limit-reset。计费与限速分开:按次计费每月最多读取 300 万条帖子。下文数字均来自 docs.x.com,截至 2026 年 11 月。
X API 速率限制如何计算
X 为每个 API 端点单独设限,按固定窗口计数,通常是 15 分钟,有时是 24 小时。额度分两个池:用应用级 Bearer token 发出的请求计入应用的额度;用 OAuth 1.0a 或 OAuth 2.0 用户 token 发出的请求计入该用户的额度。企业客户通过客户经理获得定制限额。本文只讲盯一份固定账号列表时用得到的限制;同样的请求要花多少钱,请看 X API 价格指南。
- 窗口:除非文档另有说明为 15 分钟,少数端点为 24 小时
- 应用级:Bearer token(仅应用)请求
- 用户级:OAuth 1.0a 或 OAuth 2.0 用户 token 请求
- 每个端点有自己的额度池,在一个端点上大量轮询不会占用另一个端点
监控时最关键的限额
监控系统会调用这些端点:用时间线和搜索发现新帖子,用查询接口补全帖子和解析用户名,用过滤流接收推送。其他端点见 X 的完整表格。
横向滑动查看完整对比 →
| 端点 | 每 15 分钟限额(应用 / 用户) | 监控用途 |
|---|---|---|
GET /2/users/:id/tweets | 10,000 / 900 | 按用户 ID 轮询单个账号的时间线 |
GET /2/users/by/username/:username/tweets | 1,500 / 900 | 按用户名轮询时间线,无需先解析 ID |
GET /2/tweets/search/recent | 450 / 300 | 用 from: 运算符在一次查询里检查多个账号;最多 100 条结果,查询最长 512 个字符 |
GET /2/tweets | 3,500 / 5,000 | 一次请求补全最多 100 个帖子 ID |
GET /2/tweets/:id | 450 / 900 | 查询单条帖子 |
GET /2/users/by/username/:username | 300 / 900 | 把用户名解析为用户 ID |
GET /2/users/:id/following | 300 / 300 | 读取某账号关注了谁 |
GET /2/tweets/search/stream | 50 次连接尝试(应用) | 过滤流:1 条连接,1,000 条规则,每条最长 1,024 个字符,每秒 250 条帖子 |
POST /2/tweets/search/stream/rules | 100(应用) | 修改流规则 |
POST /2/tweets | 每用户 100;每应用每 24 小时 10,000 | 发帖,供自己发布提醒的机器人使用 |
来源: X API 速率限制
截至 2026-11-11,来自 docs.x.com,该页面未显示最后更新日期。除注明外均为每 15 分钟限额。X 会调整这些数值,设计系统前请先查看该页面。
轮询大量账号在延迟上的代价
如果你轮询时间线,速率限制决定了每个账号最多会滞后多久。用一个窗口的 900 秒除以窗口内可发的请求数,再乘以账号数。按用户时间线应用级每 15 分钟 10,000 次(约每秒 11 次)计算,轮流检查时每个账号的间隔是 0.09 秒乘以账号数。搜索能在每次请求里放更多账号:按常见用户名长度,512 个字符的查询大约能放 25 个 from: 运算符,但应用每 2 秒才能搜索一次,所以 250 个账号分成 10 个查询,每个账号约每 20 秒检查一次。把全部额度都用在轮询上,就没有余量留给查询或重试。
横向滑动查看完整对比 →
| 监控账号数 | 应用 token(每 15 分钟 10,000 次) | 单个用户 token(每 15 分钟 900 次) |
|---|---|---|
| 10 | 每 0.9 秒 | 每 10 秒 |
| 50 | 每 4.5 秒 | 每 50 秒 |
| 100 | 每 9 秒 | 每 100 秒 |
| 250 | 每 22.5 秒 | 每 250 秒(约 4 分钟) |
| 500 | 每 45 秒 | 每 500 秒(约 8 分钟) |
来源: X API 速率限制
根据 docs.x.com 截至 2026-11-11 的限额自行计算:900 秒除以每个窗口的请求数,再乘以账号数。前提是整个额度池都用于时间线轮询,不为查询或重试留余量;结果是两次检查的间隔,不是帖子出现所需的时间。
限制在哪里造成麻烦
当你同时需要大量账号、低延迟和可靠重试时,问题就会出现。账号越多,每个账号两次检查的间隔越长。一次 429 会让共用该额度池的所有账号暂停到 x-rate-limit-reset,一个坏窗口就会拖慢全部账号。重试和轮询消耗同一个额度池,如果重试一起触发,原始故障过去很久之后你仍可能一直超限。
- 轮询频率越高,请求量越大
- 退避会延误影响行情的提醒
- 重试风暴会掩盖真正的故障原因
- 按账号监控的规模越大,成本越高
Filtered Stream:用推送代替轮询
Filtered Stream 换了一种模式:你编写规则、保持一条连接,X 推送匹配的帖子。几条写满 from: 运算符的规则就能覆盖一份账号列表,也没有按账号的检查间隔需要调整。代价体现在限额上。按次计费只允许一条连接,因此它是单点故障,而且重连本身也受限,每 15 分钟 50 次尝试。X 每 20 秒发送一个空行作为保活信号,并要求在 20 秒内什么都没收到时重连。X 称该流的 P99 延迟约 4-5 秒。
横向滑动查看完整对比 →
| 限额 | 按次计费 | 企业版 |
|---|---|---|
| 连接数 | 1 | 多条 |
| 每个项目的规则数 | 1,000 | 25,000+ |
| 规则长度 | 1,024 个字符 | 2,048 个字符 |
| 连接尝试 | 每应用每 15 分钟 50 次 | 定制限额 |
来源: X Filtered Stream · X API 速率限制
来自 docs.x.com,截至 2026-11-11。50 次尝试的限额来自速率限制页面;X 说明企业客户有定制速率限制。
速率限制与计费:300 万读取上限
速率限制控制你调用端点的频率;计费针对你拿回的数据。X 说两者是分开的,所以你可以完全在速率限制之内仍然产生账单,也可以触发限制而不多付钱。按次计费下,每次帖子读取 0.005 美元,同一 UTC 24 小时窗口内去重(X 称这是软保证),每个月度计费周期最多读取 300 万条帖子。如果监控系统读取繁忙账号的每一条帖子,可能先碰到这个上限,而不是任何速率限制。X API 价格指南按账号计算了成本。
横向滑动查看完整对比 →
| 计数器 | 限制什么 | 达到后会怎样 |
|---|---|---|
| 速率限制 | 每个端点每 15 分钟或 24 小时的请求数,按应用或按用户 | HTTP 429,错误码 88,直到 x-rate-limit-reset |
| 帖子读取上限 | 按次计费每个月度计费周期 300 万次帖子读取 | 更高用量需要企业版 |
| 花费上限 | 你为每个计费周期设定的最高花费 | 请求会被阻止,直到下一个计费周期 |
来源: X API 定价 · X API 速率限制
来自 docs.x.com,截至 2026-11-11。
处理 429
超限时,X 返回 HTTP 429,响应体带错误码 88 和 "Rate limit exceeded" 消息。响应里有三个头可以帮你避免超限:x-rate-limit-limit(窗口内允许的请求数)、x-rate-limit-remaining 和 x-rate-limit-reset(窗口重置的 Unix 时间)。X 的建议是读取重置时间、等到那时,必要时使用指数退避。对监控循环来说,下面几个习惯能让你基本不碰到 429。
- 根据
x-rate-limit-remaining节流,在归零前放慢 - 传入
since_id,让每次轮询只返回比上次更新的帖子 - 用
GET /2/tweets每批补全最多 100 个 ID,而不是每条帖子查一次 - 把用户名查询和补全放在各自的端点上,不占用轮询额度池
- 遇到 429 后,休眠到重置时间再加一点抖动,然后一次一个请求地恢复
能绕过这些限制吗?
不能。X 开发者政策规定不得超出或规避速率限制,也不得为同一用途或相互重叠的用途注册多个应用;唯一的例外是分别用于开发、预发布和生产的应用。把同一个监控任务拆到多个应用或 token 上来成倍增加额度,违反这些条款。你能做的是减少所需的请求:用流式接口代替轮询、批量查询、缓存用户 ID 和已见过的帖子、把请求均匀分布在窗口内,或者向 X 咨询企业版定制限额。
横向滑动查看完整对比 →
| 办法 | 作用 | 代价 |
|---|---|---|
| Filtered Stream | 不消耗轮询额度;规则匹配时推送帖子 | 按次计费只有一条连接;X 称 P99 延迟约 4-5 秒 |
| 批量查询 | GET /2/tweets 每次请求补全最多 100 个 ID | 仍按帖子读取计费 |
缓存与 since_id | 跳过重复的用户名解析和旧帖子 | 你自己的存储 |
| 企业版 | 定制速率限制 | 没有公开价格 |
来源: X 开发者政策 · X API 速率限制 · X Filtered Stream
政策与限额于 2026-11-11 在 docs.x.com 查阅。
推送模式
TweetStream 通过一条 WebSocket 推送你选定的 X 账号的帖子,所以不需要管理轮询额度或按账号的检查间隔。套餐按跟踪账号数和 WebSocket 连接数划分:Minimum 为 最多 50个账号、3 条 WebSocket,199 美元/月;Pro 为 最多 250个账号、10 条 WebSocket,499 美元/月。TweetStream 检测 X 帖子用时通常为 166 毫秒,从 X 帖子时间戳计时,到 TweetStream 服务器首次收到为止。实时数据见 tweetstream.io/speedcheck。想不用密钥先试用,免费沙盒以 60 秒延迟推送一份固定的 50 个 X 账号列表。
常见问题
X(Twitter)API 的速率限制是多少?
GET /2/users/:id/tweets)每 15 分钟应用级 10,000 次、用户级 900 次;近期搜索应用级 450 次、用户级 300 次(docs.x.com)。429 Too Many Requests(错误码 88)是什么意思?
x-rate-limit-reset 响应头以 Unix 时间戳给出重置时间;等到那时再请求,必要时用指数退避。怎样突破 X API 的速率限制?
X API 每小时能发多少条推文?
POST /2/tweets 每个用户每 15 分钟 100 条,即每小时最多 400 条;每个应用每 24 小时 10,000 条(docs.x.com,2026 年 11 月)。X 可能另有账号级发帖限制,这些 API 页面没有列出。多付钱能提高 X API 速率限制吗?
用 X API 能实时监控多少个账号?
X API 速率限制会持续多久?
x-rate-limit-reset 响应头给出确切时间。