X/Twitter 公开数据 API | SandBase
按用户名或精确 ID 查询一份 X/Twitter 资料,核对 notfound 与身份,区分两条接口的参数、价格和历史示例。

查账号资料,先明确手里的是用户名还是账号 ID。有用户名时可选 Web User Profile;已有精确数字 ID 字符串时,也可选单独计价的 User Detail。两者共用 SandBase 鉴权入口,参数拼写、类型和参考响应却不能混用。
本文于 2026-11-08 修订,只核对这两个首请求的免费 inspect 和公开参考资料,没有重新执行业务调用。其他搜索、帖子、粉丝和趋势端点保留为历史导航。关键词研究和监测流程是另外的任务,不会随资料查询自动执行。
先说结论
- Web User Profile 用字符串 screen_name 或整数 rest_id,选一个;同时传入时 ID 优先。
- User Detail 要求驼峰 restId,值是数字字符串,不能套用前者字段。
- 外层 completed 不等于拿到了账号:真实保存的空输入样本返回 notfound,身份和计数都是 null。
- 保留缺失值和原始标记;单次快照不能推增长,认证标记不能独立证明身份或合作关系。
保留的封面是概念插画。虚构的 SandBase 资料卡、认证徽标、128.7K 粉丝数和趋势数字均不是实际账号或业务指标;“实时、可靠”等画面文字也不是本轮验证结果。
按已有标识选择接口
| 手里的信息 | 当前端点 | 请求字段 |
|---|---|---|
| 已选定的用户名,如 NASA | Web User Profile | screen_name 字符串 |
| 要用于 web 路线的精确整数 ID | Web User Profile | rest_id 整数,不再传用户名 |
| 以文本保存的精确数字 ID | User Detail | restId 字符串,I 大写 |
Web schema 将两项分别标为可选,不代表空对象能选定账号。描述明确说明 ID 优先:若用户名旁边还留着另一个账号的 ID,请求可能查的是后者。下面的 helper 因此要求二选一,在发请求前拒绝歧义。
User Detail 的 restId 必填。用户名、主页 URL、浮点数都不能代替它。Python 整数可保留任意精度;JavaScript 客户端则应在序列化前拒绝不安全整数。已经被 Number 舍入的 ID,转成字符串也不能找回原值。无论请求如何编码,返回的账号 ID 都应按字符串保存。
历史 X/Twitter 目录截图。图中的端点数量、起价和 GET 目录路径不代表本轮执行结果;其中 user-post-tweet 的旧“读取帖子”标签也不是可照抄的只读调用建议。当前示例使用下文的 POST 路径。
已有 key、已连接 agent 与新项目
已经配置 SANDBASE_API_KEY,就复用现有环境变量或密钥管理器。Agent 已连接 SandBase 时,只需告诉它选定的账号、接口和输出要求,不必重新注册,也不要把 key 粘进聊天。新项目可以交给 agent 阅读 setup Skill、Markdown quickstart和具体 API 页;人工步骤见接入指南。
可以这样描述任务:“用 Web User Profile 查询这个已知用户名的一份公开资料,核对业务身份,保留未知字段,一次响应后停止。如果返回 notfound,说明结果,不要自动换接口或抓粉丝。”是否改选 User Detail,应单独决定,因为它的价格不同。
先在 Python 环境安装 requests。示例对用户名采用 1–15 位 ASCII 字母、数字或下划线的本地限制,对 ID 采用正整数规则;这是本教程收窄输入的做法,不是说 registry 自带完全相同的正则限制。代码不从 URL 抓取用户名,也不根据显示名称猜 ID。
import os
import re
import requests
API = "https://api.sandbase.ai/v1/api/twitter"
ID_PATTERN = r"[1-9][0-9]*"
def first_request(task, *, screen_name=None, rest_id=None, restId=None):
expected_id = None
if task == "web":
if restId is not None or (screen_name is None) == (rest_id is None):
raise ValueError("Choose exactly one web screen_name or integer rest_id")
if screen_name is not None:
if not isinstance(screen_name, str) or not re.fullmatch(r"[A-Za-z0-9_]{1,15}", screen_name):
raise ValueError("Provide a bare selected handle, not a URL or @handle")
payload = {"screen_name": screen_name}
else:
if type(rest_id) is not int or rest_id <= 0:
raise ValueError("Web rest_id must be a positive integer")
expected_id = str(rest_id)
payload = {"rest_id": rest_id}
route = "web/user-profile"
elif task == "detail":
if screen_name is not None or rest_id is not None:
raise ValueError("User Detail accepts only camel-case restId")
if not isinstance(restId, str) or not re.fullmatch(ID_PATTERN, restId):
raise ValueError("User Detail restId must be an exact positive decimal string")
expected_id = restId
payload, route = {"restId": restId}, "user-detail"
else:
raise ValueError("Choose web or detail")
key = os.environ.get("SANDBASE_API_KEY", "").strip()
if not key:
raise ValueError("Set SANDBASE_API_KEY in your environment")
try:
response = requests.post(
f"{API}/{route}",
headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
json=payload, timeout=(10, 90), allow_redirects=False,
)
if not 200 <= response.status_code < 300:
raise RuntimeError(f"SandBase HTTP {response.status_code}; request stopped")
body = response.json()
except requests.RequestException:
raise RuntimeError("Network request failed; inspect locally before another call") from None
except ValueError:
raise RuntimeError("SandBase returned invalid JSON") from None
if not isinstance(body, dict) or body.get("status") != "completed":
raise RuntimeError("SandBase request did not complete")
outputs = body.get("outputs")
if not isinstance(outputs, list) or not outputs or not isinstance(outputs[0], dict):
raise RuntimeError("Missing documented outputs[0]")
data = outputs[0].get("data")
if not isinstance(data, dict):
raise RuntimeError("Missing documented outputs[0].data object")
if data.get("status") == "notfound":
raise RuntimeError("Profile not found; no fallback request made")
identities = [data[k] for k in ("rest_id", "id") if data.get(k) is not None]
if (not identities or any(not isinstance(v, str) or not re.fullmatch(ID_PATTERN, v) for v in identities)
or len(set(identities)) != 1):
raise RuntimeError("Missing, malformed or conflicting returned profile identity")
if expected_id is not None and identities[0] != expected_id:
raise RuntimeError("Returned profile ID does not match the selected ID")
if not isinstance(data.get("name"), str) or not data["name"].strip():
raise RuntimeError("Missing profile display name in the reference shape")
return data
if __name__ == "__main__":
result = first_request("web", screen_name="NASA")
print("Received fields:", sorted(result))使用 web 整数 ID 时,将主程序赋值行替换为 result = first_request("web", rest_id=11348282);选择 User Detail 时替换为 result = first_request("detail", restId="44196397")。不要把两行追加成自动连续调用。代码不自动重试、跟随重定向、切换端点、下载头像或读取置顶帖。
这里直接检查 outputs[0].data 下的扁平字段,没有再套 user 或 data.data。返回必须有可用的字符串 id 或 rest_id;两者同时出现不能冲突,按 ID 查询时还必须与所选 ID 相符。示例同时要求参考资料中展示的非空显示名称,结构改变时停止,而不是保存一个“成功的空账号”。
用户名查询仍有边界:裁剪参考没有保证回显独立的 screen_name。应同时保存请求用户名和返回的精确 ID,不能靠显示名称相似认定同一账号。两条参考对可选 profile 字段的描述也不同,不应据此建立统一的跨账号关联规则。
空输入的保存样本确实没有找到账号
公开保存的 Web User Profile 样本 ID 为 dab93362-96dc-4d35-a50a-9036130ee4ba,created_at 是 2026-08-20T07:25:01.103Z。输入快照为一个空对象,业务返回 status notfound,身份和计数字段为空。下面是保持原值的裁剪:
{
"status": "notfound",
"id": null,
"rest_id": null,
"name": null,
"sub_count": null,
"statuses_count": null
}这是一份负例,不能当成 NASA 查询成功。把教学请求改成 screen_name NASA,并不会改变旧空输入实际返回过什么。离线测试将这份保存的业务结果送进解析器,预期报错;没有为测试再次发起请求。
README 中另有一段 NASA 形状的裁剪参考,包含扁平 id、name,以及数组 affiliates、对象 business_account,但没有执行时间。它用于核对字段路径,不能说是刚刚成功查到的资料,更不能把负例的 null 用这段参考填满后冒充同一次运行。
历史 Web User Profile 参数页,展示 screen_name 和整数 rest_id。图右侧只有 model 的旧请求、空 data 响应及示意 ID 都不是当前可执行示例或 NASA 实测结果。
User Detail 的参考结构与计数含义
当前公开资料没有 User Detail 完整保存样本。README 将一段裁剪响应标作真实示例,展示字符串 id、显示名称等扁平字段,但没有给出执行时间。因此只能称参考片段,不能声称本轮读取成功;请求仍须使用驼峰 restId 字符串。
该参考的 affiliates 是带组织标签的对象,而 web 参考是数组;business_account 在这里是 null,在 web 参考中则是对象。不要把它们强制映射成臆造的同一套嵌套结构。暂时保留原值和来源端点,确有产品需求时再定义映射规则。片段通过解析测试,也不等于完整响应或线上可用性已得到验证。
字段说明区分 sub_count 粉丝量和 friends 关注数量。statuses_count 与 media_count 也是不同总数,不是活动成效或曝光量。记录原字段、原值和观察时间;一个快照无法衡量增长。缺失计数保持未知,不能默认成零,也不要将 null 标记转成 false 来简化面板。
created_at 表示账号创建时间,不是观察时间。location 是自由文本,不是经过验证的地理位置;desc 可能只是短链接,代码不会自动打开。认证标记、组织标签都只是返回信号,不能据此断定付费状态、真实身份或合作关系。protected 等公开状态也不会授予私密帖子或私信的访问权限。
保留旧示意 JSON,不追认为实测
原文使用过 ID 13a394de-55e6-4c72-b0b1-604007a3757d 的示意信封,NASA 数值用于展示结构,并非已核实的运行记录。以下 JSON 原样保留,不代表当前账号计数,也不是空输入负例成功的证据:
{
"id": "13a394de-55e6-4c72-b0b1-604007a3757d",
"status": "completed",
"model": "twitter/web/user-profile",
"outputs": [
{
"data": {
"name": "NASA",
"rest_id": "11348282",
"blue_verified": true,
"location": "Pale Blue Dot",
"friends": 115,
"statuses_count": 74334,
"created_at": "Wed Dec 19 20:20:32 +0000 2007"
}
}
]
}旧 Python 和 curl 已逐字放入历史代码归档,同时保存哈希。它们没有本次新增的业务结果和身份检查。当前接入使用上面的单次 helper,历史示例用于追溯原文,不再作为执行主流程。
其他能力只作为独立任务导航
下面保留原 hub 的能力导航,本轮没有重新验证搜索、帖子、粉丝或趋势接口。统一鉴权和信封不能替代每个接口各自的输入、业务结构与预算检查。
| 能力 | 历史导航 | 读者任务 |
|---|---|---|
| 搜索 | twitter/web/search-timeline | 按问题寻找候选帖子 |
| 帖子详情 | twitter/web/tweet-detail | 读取已选定帖子 |
| 回复 | twitter/web/post-comments | 查看某个讨论 |
| 关系数据 | twitter/web/user-followers | 单独规划粉丝读取 |
| 趋势 | twitter/web/trending | 查看选定趋势来源 |
历史 search-timeline 参数参考,并非端点列表截图。搜索和分页属于另一个任务,本轮没有执行;图中的示意信封不作为真实业务返回。
查资料不应自动扩展成搜索、帖子、回复三步链路,也不应开始遍历粉丝。置顶帖 ID 和头像 URL 只是引用,不是已经拿到的内容。先判断研究问题还缺什么证据,再决定下一次请求。需要监测时,转到独立监测指南,另外核对契约,不在这里隐式追加。
这两个选定接口读取公开资料,不负责发帖、私信、账号操作或私域分析。SandBase 提供接入层,并不拥有 X;也不能用本轮两个资料请求的结论替整个目录背书。
价格与失败处理
2026-11-08 免费 inspect 显示 Web User Profile 每次 0.001 美元,User Detail 每次 0.014286 美元。两者都有组织共享每日 100 次合资格数据 API 调用的资格标记,00:00 UTC 重置。资格不是剩余次数、账户余额或实际扣费记录,不保证本次免费或成功。若分别选择两次调用,额度影响前的标价合计为 0.015286 美元;代码没有自动降级调用。
HTTP 失败、外层未完成、JSON 结构异常和业务 notfound 应分开报告,不能都解释为账号消失,也不能默默保存空资料。示例错误信息不回显密钥和上游响应正文。后续重试或更换路线是新的决策,需要原因与预算,而不是隐藏的恢复动作。
常见问题
两种 ID 参数怎么区分? Web 用整数 rest_id,User Detail 用驼峰 restId 数字字符串。请求序列化与返回值存储是两回事,返回 ID 保留为字符串。
completed 也可能没有资料吗? 会。真实保存的空输入样本返回 notfound 和空身份,必须检查业务结果。
认证徽标能证明身份吗? 它是返回信号,不是独立的身份或合作关系审核,也不能推出付费历史和受众质量。
notfound 后要自动换端点吗? 不要。先报告结果,再单独选择是否执行另一条不同参数、不同价格的路线。
这次会读搜索和粉丝吗? 不会。能力表只是导航,这两个首请求都在一份公开资料响应后停止。
从一个已知账号开始
根据已有标识选择 Web User Profile 或 User Detail。检查身份、保留未知值,一次响应后停止;需要扩展时再到 X/Twitter 目录选择单独核对的任务。
觉得有用?分享给更多人