Threads 创作者研究 API 教程

用一次请求读取已知 Threads 账号资料或搜索候选;核对响应结构、保留未知指标,先确认身份再决定后续查询。

深色电影质感画面:一批 Threads 账号解析成排名的资料卡,汇入 Agent 内核

已经知道 Threads 账号,和只知道品牌名称,不该走同一条接入路径。前者直接查资料,后者先搜索候选,再确认哪个才是目标。这篇 Threads 创作者研究 API 教程先解决这两个首次请求,不把模糊匹配自动当成已确认的身份。

2026-11-08 本次修订核对了免费端点 inspect 和当前公开参考响应,没有执行付费 Threads 业务请求。原文 2026-09-27 UTC 的资料实测保留在后半篇,run ID 与 JSON 数值不改。Threads API 总览介绍更广的能力范围;这里的当前代码只读一次资料,或返回一次候选搜索。

先说结论

  • 已知账号用 threads/web/user-info,参数是 username,业务载荷里检查 user 对象。
  • 找候选用 threads/web/search-profiles,参数是 query,候选位于 xdt_api__v1__users__search_connection.edges[].node。
  • 两者都只读取 outputs[0].data。关键结构缺失应报错,不能当成空资料或零粉丝。
  • 不自动选首条匹配、不遍历账号、不排名、不抓帖子,也不自动重试或翻页。

Threads 创作者研究 API:先区分输入

已有信息所选请求需要判断什么
已确认的账号 handle用户资料返回的这个账号资料
品牌名、显示名或查询词资料搜索候选账号集合,还不是最终选择

资料 schema 只有一个必填字符串 username,搜索只有一个必填字符串 query。两者都没有声明 page、cursor、end_cursor 或 limit。不要把帖子接口的分页参数移植过来,也不要写成可以自动搜到下一页。

例如主页链接 https://www.threads.net/@nasa 对应的输入是 nasa,不是完整 URL,也不是数字账号 ID。helper 接受裸 handle 或一个前导 @,去掉两端空白,并用字母、数字、点、下划线做简单格式检查。这只是本例的本地输入限制,不宣称穷尽了上游所有用户名规则,更不能据此确认账号存在。

搜索本来就比精确资料查询宽。当前公开参考明确提醒:目标名称旁边可能混有相似 handle。显示名相同或带认证标记,都不能单独证明就是你要找的组织。先将 username 与目标身份核对,再决定是否追加资料请求。代码保留全部候选 node,不取第一条当最终答案。

已有项目或 agent 怎么接

已经有 Key,就复用项目本地的 SANDBASE_API_KEY 或现有密钥存储。agent 已连接 SandBase,就使用现成连接并检查所选端点,不必再创建 Key。新项目可以把 setup skill 和 Markdown quickstart 交给 agent,再说明任务、handle 或查询词;密钥不贴进对话,也不写入示例源码。

可以这样描述:“使用现有 SandBase 连接,先检查 threads/web/search-profiles,再按我给的名称查询一次,把候选留给我核对。不自动选账号,不逐个查资料,不按粉丝排名,不读取帖子。”如果已经知道账号,把任务改为一次 user-info。先明确停止点,就不会让小查询悄悄扩成一整套调研。

Python 环境先运行 python3 -m pip install requests,把代码存为 first_request.py,本地配置 Key 后运行 python3 first_request.py。主程序默认读取一次示例账号 nasa。改成搜索时,将最后两行替换为 result = first_request("search", "OpenAI") 和 print("Candidate count:", len(result[SEARCH_CONNECTION]["edges"]))。这是两种备选任务,不是把两个请求接起来执行。

单次请求,按端点检查结构

使用端点 README 的 Model API POST 路由:https://api.sandbase.ai/v1/api/threads/web/<operation>,JSON 只放 username 或 query。目录 GET 路径和上游 schema 内嵌的通用 /v1/run 条目,都不能替代这里明确记录的逐端点请求。

Python
import os
import re
import requests

SEARCH_CONNECTION = "xdt_api__v1__users__search_connection"


def first_request(task, value):
    if not isinstance(value, str) or not value.strip():
        raise ValueError("Provide a known username or a search query")
    value = value.strip()
    if task == "profile":
        username = value[1:] if value.startswith("@") else value
        if not re.fullmatch(r"[A-Za-z0-9._]+", username):
            raise ValueError("Use a username, not a profile URL")
        path, params = "user-info", {"username": username}
    elif task == "search":
        path, params = "search-profiles", {"query": value}
    else:
        raise ValueError("Choose profile or search")
    key = os.environ.get("SANDBASE_API_KEY", "").strip()
    if not key:
        raise RuntimeError("Set SANDBASE_API_KEY locally")
    try:
        response = requests.post(
            f"https://api.sandbase.ai/v1/api/threads/web/{path}",
            headers={"Authorization": f"Bearer {key}"}, json=params,
            timeout=(10, 90), allow_redirects=False,
        )
        if not 200 <= response.status_code < 300:
            raise RuntimeError(f"SandBase HTTP {response.status_code}")
        body = response.json()
    except ValueError:
        raise RuntimeError("SandBase returned invalid JSON") from None
    except requests.RequestException:
        raise RuntimeError("SandBase network request failed; not retried") 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")
    payload = outputs[0].get("data")
    if not isinstance(payload, dict):
        raise RuntimeError("Missing documented outputs[0].data")
    if task == "profile":
        user = payload.get("user")
        if not isinstance(user, dict) or not user:
            raise RuntimeError("Missing or empty Threads user object")
    else:
        connection = payload.get(SEARCH_CONNECTION)
        if not isinstance(connection, dict) or not isinstance(connection.get("edges"), list):
            raise RuntimeError("Missing Threads search connection/edges array")
        for edge in connection["edges"]:
            if (not isinstance(edge, dict) or not isinstance(edge.get("node"), dict)
                    or not edge["node"]):
                raise RuntimeError("Missing or empty Threads search node object")
    return payload


if __name__ == "__main__":
    result = first_request("profile", "nasa")
    print("Profile name:", result["user"].get("full_name"))

共用 SandBase 信封,不代表业务载荷相同。资料必须是非空 user 对象;搜索必须有指定 connection 对象、edges 数组,以及每条 edge 内的非空 node 对象。空 edges 数组可以成立,数组不存在则不能。拒绝空资料或空 node 是本例的完整性检查,避免把无法使用的记录打印成成功查询。

两个公开参考响应都不需要 code: 0 或 success: true 规则,所以代码没有套用其他平台的成功判断。HTTP 失败、状态未完成、非法 JSON、旧顶层 output、缺少资料或搜索结构,都会停止,不把上游错误吞成“没有候选”。可选业务字段原样保留,不自动补值。

请求设置连接和读取超时,不跟随跳转。遇到超时、网络错误或 401/402/403/429/5xx,都不会自动再发一次。错误信息不回显密钥或原始上游正文。按情况先查鉴权、账户计费上下文或限流,再决定是否另行尝试。离线 mock 只能证明这些客户端行为,不能证明上游此刻可用。

看资料与候选,不制造排名

当前公开资料参考展示的是 NASA,样本里有显示名、简介、粉丝数、认证标记和空 bio_links。这些是已公开样本中观察到的字段,不是本次修订刚测出的数字,也不保证每条资料都包含。字段可能缺失或为 null。没有 follower_count 表示未知,显式数字 0 则是返回值;把两者合并会丢失信息。

is_verified 缺失也不能自动变成 false。“没有提供”和“明确为 false”是不同状态。以后要做表格,先保留未知值与读取日期,再决定比较规则。粉丝数是资料指标,不能直接当作帖子触达、投放效果或受众质量。

公开搜索样本的 node 里有 username、full_name、id、pk、is_verified 等身份字段,但没有据此保证每个候选都有粉丝数。因此不能把搜索结果直接丢进旧版粉丝排序逻辑。候选先保持候选,决定继续查谁是后续独立任务。

资料参考中的空 bio 链接,也没有证明非空链接元素一定是什么结构。要提取链接,先看一条真实返回,再写映射。JSON 里的链接或头像 URL 不会被这个示例自动访问,它不下载头像、不跟 bio,也不宣称能读取私有账号内容。

价格与免费额度资格

2026-11-08 免费 inspect 显示,资料查询 base price 为 $0.002,资料搜索为 $0.003。两者都具备组织每天 100 次数据 API 共享免费额度资格,00:00 UTC 重置。本次没查询剩余额度,也没执行业务请求。符合资格,不等于下一次一定免费。

抵扣可能的额度之前,单次请求按所选端点价格预算。若搜索一次,再人工选中一个账号查资料,属于两个独立请求,按当前基础价合计 $0.005。这只是规划算术,不是示例自动执行的链路,也不是本次实际扣费。更大的账号列表需要另定预算,并保留每次错误,不能静默跳过。

历史资料实验:2026-09-27

原教程会遍历账号并对扁平记录排序。双语 Python 原文归档逐字保留原来的八段代码,并记录来源提交与 SHA256。旧代码跳过缺资料的账号、将缺粉丝数补为 0、将缺认证标记补为 false,再遍历 handle 列表。它只供追溯,不再作为当前执行建议。原封面的排名卡片也是概念示意,不是一份经过验证的创作者榜单。

历史 SandBase Threads API 目录列表 历史目录截图,2026-09-27。展示端点列表,不是一次成功的资料或搜索执行;当前输入和价格另行核对。

原文对 zuck 的资料读取 run 是 77059cb9-8616-4be1-abfe-96e82a12b54f。下面 JSON 原样保留,粉丝数与简介只表示那个历史时间点,不是当前数值:

JSON
{
  "id": "77059cb9-8616-4be1-abfe-96e82a12b54f",
  "status": "completed",
  "model": "threads/web/user-info",
  "outputs": [
    {
      "data": {
        "user": {
          "full_name": "Mark Zuckerberg",
          "biography": "Mostly superintelligence and MMA takes",
          "follower_count": 5744972,
          "is_verified": true,
          "bio_links": [],
          "id": "63055343223",
          "pk": "63055343223"
        }
      }
    }
  ]
}

历史 Threads User Info API 参考 历史 user-info 参数参考截图,2026-09-27。实际历史资料样本是上方 JSON,截图不是本次业务执行证据。

旧列表写了 zuck、mosseri、natgeo,但本文保留的是一份明确资料响应,不能据此证明列表里每个账号都返回了相同字段。旧排序使用 (verified, followers) 降序,认证才是第一排序键,并非简单的“按传播度排序”。缺值补零和补 false 又进一步影响比较。新版直接移除这个排序,而不是给它换个名字继续当作已审核结论。

历史 Threads User Info by ID API 参考 历史 user-info-by-id 参数参考,2026-09-27。它与按 username 查询不是同一端点,当前行为不在本次复验范围。

常见问题

需要 Threads 或 Meta 登录吗? 这两个当前请求 schema 使用 SandBase 鉴权,不要求 Threads 登录 cookie 或 OAuth token,也不授予私有或账号授权内容的访问权限。

为什么资料缺失要报错? 缺少、为 null 或空的 user,都不等于一个已经确认、粉丝数为零的账号。helper 会报告问题,让它与可选字段缺失的有效资料分开。

能直接取搜索第一条吗? helper 不会这样做。搜索可能含相似账号,追加任何请求前先核对用户名与目标身份。

怎么获取更多候选? 本次检查的搜索 schema 只声明 query,不能自造 page、cursor 或 limit。本文不承诺完整搜索覆盖,也没验证续页机制。

可以继续读取帖子和回复吗? 这是其他端点与任务,本次未验证它们的当前可用性、价格、标识或分页。扩展前应单独检查。

先从确实已知的输入发出一条请求,保留未知字段,再判断哪些后续研究值得继续。

觉得有用?分享给更多人