获取用户时间线 | API 文档

按统一用户 ID 查询用户时间线。这个接口返回官方 X API v2 风格的 data / includes / meta 结构。

text

GET https://api.requestbeam.com/v1/twitter/users/{id}/tweets

验证

所有 Twitter API 接口都需要使用 Bearer Token 进行认证。

http

Authorization: Bearer YOUR_API_KEY

如果请求直接返回认证错误，请优先检查：

API Key 是否正确
Key 是否适用于当前 API Base URL
请求头是否拼写正确
代理层是否改写了请求头

Path Parameters

idstring必填

Twitter 用户 ID，例如 44196397。

Query Parameters

max_resultsinteger默认: 10

单次返回的 tweet 数量，范围 1-100。

pagination_tokenstring

继续翻页时使用的游标，取自上一次响应中的 meta.next_token。

excludestring

逗号分隔的排除策略。当前支持 replies、retweets，例如 exclude=retweets,replies。

expansionsstring

逗号分隔的展开字段。当前建议使用 author_id；当包含 author_id 时，会返回 includes.users。

tweet.fieldsstring

逗号分隔的 tweet 字段列表，例如 created_at,public_metrics,attachments,source。

user.fieldsstring

当 expansions=author_id 时，用于控制 includes.users 中用户对象的字段投影。

请求示例

下方示例假设 API_BASE_URL 已设置为你的 API Base URL。

bash

curl --request GET \
  "$API_BASE_URL/v1/twitter/users/44196397/tweets?max_results=5&exclude=retweets,replies&expansions=author_id&tweet.fields=created_at,public_metrics,attachments,author_id,conversation_id&user.fields=public_metrics" \
  --header "Authorization: Bearer YOUR_API_KEY"

Response

dataobject[]必填

时间线 tweet 列表。

单条 tweet 字段

idstring必填

Tweet ID。

textstring必填

Tweet 文本内容。

attachmentsobject

媒体引用信息，当前以 media_keys 输出。

author_idstring

作者 ID。当你请求 expansions=author_id 时，可与 includes.users 对应。

conversation_idstring

对话 ID。

created_atstring

Tweet 创建时间，ISO 8601。

edit_history_tweet_idsstring[]

编辑历史 tweet ID 列表。

entitiesobject

Tweet 解析后的实体信息，例如 hashtag、url、mentions。

in_reply_to_user_idstring

回复对象的用户 ID。

langstring

Tweet 语言。

possibly_sensitiveboolean

是否为敏感内容。

public_metricsobject

Tweet 公开统计信息。

public_metrics 字段

retweet_countinteger

转推数量。

reply_countinteger

回复数量。

like_countinteger

点赞数量。

quote_countinteger

引用数量。

bookmark_countinteger

收藏数量。

impression_countinteger

展示次数。

referenced_tweetsobject[]

引用的 tweet 列表，type 可能是 retweeted、quoted 或 replied_to。

sourcestring

Tweet 来源，例如客户端或 Web。

includesobject

扩展对象。只有当 expansions 包含 author_id 时才会出现。

includes 字段

usersobject[]

与 author_id 对应的作者列表。

metaobject必填

分页与结果统计信息。

meta 字段

newest_idstring

当前页最新 tweet 的 ID。

oldest_idstring

当前页最旧 tweet 的 ID。

next_tokenstring

下一页游标。继续翻页时传给 pagination_token。

result_countinteger必填

当前页 tweet 数量。

成功响应示例

json

{
  "data": [
    {
      "id": "tweet-1",
      "text": "Hello Mars",
      "attachments": {
        "media_keys": [
          "media-1"
        ]
      },
      "author_id": "44196397",
      "conversation_id": "tweet-1",
      "created_at": "2025-04-22T10:00:00.000Z",
      "public_metrics": {
        "bookmark_count": 4,
        "impression_count": 15,
        "like_count": 7,
        "quote_count": 1,
        "reply_count": 2,
        "retweet_count": 3
      }
    }
  ],
  "includes": {
    "users": [
      {
        "id": "44196397",
        "name": "Elon Musk",
        "username": "elonmusk",
        "public_metrics": {
          "followers_count": 10,
          "following_count": 20,
          "tweet_count": 40
        }
      }
    ]
  },
  "meta": {
    "newest_id": "tweet-1",
    "oldest_id": "tweet-1",
    "next_token": "cursor-123",
    "result_count": 1
  }
}

失败响应

完整错误码、协议差异和排查步骤见错误码与错误处理。

平台原生接口失败时通常返回如下结构：

json

{
  "success": false,
  "error": {
    "code": 40000,
    "message": "Insufficient credit. Required: 100000, Available: 99999"
  },
  "requestId": "req_xxx"
}

字段说明：

success：固定为 false
error.code：平台统一数字错误码
error.message：错误说明
requestId：请求追踪 ID，排查问题时建议保留

使用建议

如果你只有 username，先调用用户查询接口拿 data.id
需要作者资料时再加 expansions=author_id
只拉展示需要的字段时，显式设置 tweet.fields 和 user.fields
继续翻页时，使用上一次响应里的 meta.next_token