开放能力导航
首页/X 开发者平台/调用手册
X 开发者平台调用手册

检索最近 7 天的公开帖子

从小规模关键词查询起步，读取结果与下一页游标，适合开发信息检索功能。

官方资料核对 2026-10-15示例代码，未进行真实接口实测
← 返回平台功能

接入准备

  • 注册 X 开发者并创建 App，确认目标读取端点对自己的 App 可用。
  • 在控制台取得应用级 Bearer Token，核对 credits 余额并设置支出上限；本页不需要用户发帖权限。

准备环境变量

示例值需要替换为自己的凭证或资源 ID。代码在本机或服务端运行；密钥不应放进公开网页。

X_BEARER_TOKEN
Developer Console 的 App 中生成的应用级 Bearer Token；只用于服务端。
终端
export X_BEARER_TOKEN='replace_with_app_bearer_token'

以上 export 适用于 macOS / Linux 的终端，在同一终端内运行后续代码。Python 示例保存为 request.py 后执行 python3 request.py。

调用步骤

  1. 01

    打开 Developer Console，选择自己的 App，在凭证设置中生成或查看应用级 Bearer Token。

  2. 02

    将 Token 设置为 X_BEARER_TOKEN 环境变量；不要把 API Secret 当成 Bearer Token。

  3. 03

    修改示例里的用户名、帖子 ID 或查询词，然后在自己的服务端运行代码，检查 HTTP 状态与 JSON 内的 errors。

调用 01

搜索近期帖子

示例只查询关键词 API，最多取 10 条。换成中文、多条件或空格查询时先进行 URL 编码。

GEThttps://api.x.com/2/tweets/search/recent?query=API&max_results=10

请求头

Authorization
Bearer ${X_BEARER_TOKEN}
Accept
application/json

参数说明

参数表可左右滑动，查看完整说明。

字段 / 位置类型 / 必填说明
queryQuerystring必填搜索表达式；示例为 API。语法和可用操作符仍受端点访问规则约束。
max_resultsQueryinteger可选每页 10–100，默认 10；示例用 10 限制返回量。
next_tokenQuerystring可选取上一次响应 meta.next_token，URL 编码后加入下一次请求；没有则停止。
start_timeQueryISO 8601 string可选可选起点，需在近 7 天内；不能与 since_id 同时提供。

调用代码

替换示例 ID 与请求体内容后运行。cURL 会报 HTTP 错误，业务状态还需按下方返回示例核对。

cURL
# 执行后核对返回 JSON 的业务状态；HTTP 200 仍可能包含业务错误。
curl --silent --show-error --fail-with-body \
  --request GET \
  --url "https://api.x.com/2/tweets/search/recent?query=API&max_results=10" \
  --header "Authorization: Bearer ${X_BEARER_TOKEN}" \
  --header "Accept: application/json"
Python 3
import json
import os
import re
import urllib.request
import urllib.error

def expand(value):
    return re.sub(r"\$\{([A-Z][A-Z0-9_]*)\}",
                  lambda match: os.environ[match.group(1)], value)

url = expand("https://api.x.com/2/tweets/search/recent?query=API&max_results=10")
headers = {
    "Authorization": expand("Bearer ${X_BEARER_TOKEN}"),
    "Accept": expand("application/json"),
}
data = None
request = urllib.request.Request(url, data=data, headers=headers, method="GET")
try:
    with urllib.request.urlopen(request, timeout=30) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    print(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}")
    raise SystemExit(1)
print(json.dumps(result, ensure_ascii=False, indent=2))
Node.js
// Node.js 22+，保存为 request.mjs 后运行 node request.mjs
function expand(value) {
  return value.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (_, name) => {
    if (!process.env[name]) throw new Error(`缺少环境变量 ${name}`);
    return process.env[name];
  });
}

const url = expand("https://api.x.com/2/tweets/search/recent?query=API&max_results=10");
const headers = Object.fromEntries(
  Object.entries({
  "Authorization": "Bearer ${X_BEARER_TOKEN}",
  "Accept": "application/json"
}).map(([key, value]) => [key, expand(value)])
);
const response = await fetch(url, {
  method: "GET",
  headers,
  signal: AbortSignal.timeout(30000),
});
const text = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
const result = JSON.parse(text);
console.log(JSON.stringify(result, null, 2));

返回示例

按官方结构整理的节选示意，非实测结果。data 是帖子数组；meta.result_count 为本页数量；有 meta.next_token 才继续翻页。 以下为结构示意，非本站实测结果。

JSON
{
  "data": [
    {
      "id": "1234567890123456789",
      "text": "公开讨论示意"
    }
  ],
  "meta": {
    "result_count": 1,
    "next_token": "example_next_page_token"
  }
}

常见错误与排查

HTTP 400查询或参数格式不符合要求
检查 query 编码、max_results 范围和互斥时间参数。
HTTP 401凭证缺失或无效
核对 Authorization: Bearer 格式与 App Token 是否已被重新生成。
HTTP 403已认证，但无权访问目标端点或数据
核对 App 接入资格与公开可见性；应用级 Token 无法绕过受保护账号。
HTTP 429频控或用量上限
读取 x-rate-limit-reset，检查 credits 与支出上限后再重试。

调用注意

  • 近期搜索不是完整历史搜索。每页结果单独计入用量；本示例不会自动循环翻页。
  • next_token 与 pagination_token 二选一；start_time 与 since_id 二选一，end_time 与 until_id 二选一。
近期帖子搜索参数与分页X HTTP 错误与部分成功响应

注意事项

  • 读取按返回资源消耗 credits，调试也可能计费；准确单价、折扣及预算以当前控制台为准。
  • 这是公开数据只读场景，不包含发帖、私信或用户 OAuth 授权；数据保存和展示仍须遵守 X 政策。

核验来源

本站按官方资料整理本场景的必要调用步骤与代码，覆盖范围以本页列出的接口为准。官方资料用于追溯规范及查看变更。

  1. 01
  2. 02
  3. 03
    近期帖子搜索参数与分页核验日期 2026-10-15
  4. 04
    X HTTP 错误与部分成功响应核验日期 2026-10-15

X 开发者平台的其他调用手册

按用户名取得用户资料和 ID通过帖子 ID 读取内容

← 返回X 开发者平台的全部功能