根据用户名获取用户 | API 文档

使用 username 查询用户资料。这个接口适合在只知道用户名时先解析用户 ID，再把返回的 data.id 继续用于时间线查询。

text

GET https://api.requestbeam.com/v1/twitter/users

验证

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

http

Authorization: Bearer YOUR_API_KEY

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

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

Query Parameters

usernamestring必填

Twitter 用户名。支持传 elonmusk 或 @elonmusk，服务端会自动去掉前导 @。

user.fieldsstring

逗号分隔的用户字段列表，例如 created_at,description,public_metrics,verified。

请求示例

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

bash

curl --request GET \
  "$API_BASE_URL/v1/twitter/users?username=elonmusk&user.fields=created_at,description,public_metrics,verified" \
  --header "Authorization: Bearer YOUR_API_KEY"

Response

dataobject必填

统一后的用户对象。

data 字段

idstring必填

用户唯一标识。后续查询时间线时应优先使用这个值。

namestring必填

用户显示名称。

usernamestring必填

用户名，不带 @。

created_atstring

ISO 8601 时间，只有在请求 user.fields=created_at 时返回。

descriptionstring

用户简介。

entitiesobject

用户资料中的实体信息，例如 URL 描述和链接。

locationstring

用户资料中的地理位置。

pinned_tweet_idstring

置顶 tweet 的 ID。

profile_banner_urlstring

头图地址。

profile_image_urlstring

头像地址。

protectedboolean

是否为受保护账号。

public_metricsobject

用户公开统计信息。

public_metrics 字段

followers_countinteger

关注者数量。

following_countinteger

正在关注数量。

tweet_countinteger

推文总数。

listed_countinteger

被加入列表数量。数据源未提供时可能缺失。

urlstring

用户资料里的主页地址。

verifiedboolean

是否为认证账号。

verified_typestring

认证类型，例如 Business。

成功响应示例

json

{
  "data": {
    "id": "44196397",
    "name": "Elon Musk",
    "username": "elonmusk",
    "created_at": "2009-06-02T20:12:29.000Z",
    "description": "Mars and cars",
    "public_metrics": {
      "followers_count": 10,
      "following_count": 20,
      "tweet_count": 40
    },
    "verified": true
  }
}

失败响应

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

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

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
如果你只需要头像、简介、粉丝数，建议显式传 user.fields，避免返回冗余字段