Treg People Search API 使用指南：让 Agent 查人、找邮箱、验邮箱

Treg people search API 让你的编码 agent 用一个 token 完成三件事：查找联系人、拿到工作邮箱、并判断邮箱是否真实有效。安装 treg CLI 并登录一次后，Claude Code 或 Codex 就能调用 treg.people.search、treg.people.email.find 和 treg.people.email.verify 这类路由工具。Treg 负责挑选供应商、在其服务端注入供应商密钥，并从预充值余额中按供应商自身费率逐次计费。

本指南覆盖安装配置、三个 agent 提示词（查找、补全、验证）、它们背后的原始 HTTP 调用，以及一套可交给 agent 运行的 Apifox CLI 回归测试。

AI Coding 交流群

一起交流 AI 编程、Cursor、Claude Code 和开发工作流，分享实践经验与工具技巧。

Treg people search API 是什么？

Treg 是一个面向 agent 的开源工具目录，官方文档称其为“OpenRouter，只不过路由的是 agent 工具而不是模型”。一个 base URL（https://treg.to）加一个 token，就能访问 123 家供应商的 4,100+ 工具。在人员查找场景，路由工具会为每次调用挑选供应商，未命中时自动尝试下一家，并在响应头中报告每次调用的花费。

people search 这条线只是其中一小撮路由能力。公共目录在 2026 年 11 月 3 日列出的内容如下：

people search 页面标注的供应商数量是 16 家；上表数字来自实时目录，随时可能变动。

为什么用一个聚合器，而不是直接买 Apollo 或 Hunter 的 key？两个原因：你的 agent 永远不需要持有供应商 key，而且按结果付费而不是按席位付费。Treg 页面引用了 LessieAI 的 People Search Bench（119 个任务）：在其 B2B 线索任务上，Claude Code 单独作答的正确率是 43%，Claude Code 加 Treg 是 78.2%。这是厂商自己的图表，把它当作一个值得在你自己数据上验证的说法即可。

路由、计费与错误处理的工作机制

你向 https://treg.to/call/<tool-id> 发送请求，并带上 X-Treg-Token header。Treg 找到供应商、在服务端附加供应商凭据，再把供应商的应答转发回来。

文档里有一处看起来互相矛盾，这里把各块拼起来说清楚：

• 直连供应商工具（例如 apollo.people.search）不会故障转移。API 参考文档写明 Treg“不会在供应商之间自动路由，也不会故障转移”，选哪家供应商由你决定。
• 路由工具（treg.<capability>）则会转移。根据 CLI 参考文档：供应商报错时回退到下一个候选，未命中时也会换下一家供应商重试，按价格从低到高排序；X-Treg-Route-Waterfall: 0 在第一次未命中时立即停止。

计费规则（来自 llms.txt 和 people search 页面）：

1. 每次调用都从预充值余额按供应商自身费率计费，0 加价。
2. 团队自有供应商 key 优先使用，且不计费。
3. 新通过验证的账户可获得一次 $1.00 免费额度。
4. 按成功计费的供应商未命中不收费；部分供应商按调用计费，未命中也可能产生少量费用。
5. 扣费金额通过 X-Treg-Cost-Micro（整数 micro-USD）返回；X-Treg-Route-Max-Cost 为单次调用设置上限，路由工具默认上限为每次 $1。

错误的处理边界很清晰：供应商返回 4xx（429 除外）说明你的请求本身有问题，改请求，别换家重试；429 或 5xx 说明可以换下一家供应商；402 insufficient_balance 则意味着该充值了。

在 Claude Code 或 Codex 中配置 Treg

任何本地编码 agent（Claude Code、Codex、Cursor、opencode）的配置流程都一样：

curl -fsSL https://treg.to/install.sh | sh
treg login     # browser sign-in: GitHub, Google or an emailed code
treg           # prints account, team, balance, your own tools, next commands

想用邮箱登录？运行 treg login --email you@company.com。拿到队友给的 token？curl -fsSL https://treg.to/install.sh | sh -s -- --token "$TREG_TOKEN" 可以免浏览器一步完成安装和登录。

安装器还会向检测到的每个 agent 注入 Treg skill，让 Claude Code 和 Codex 自学“搜索、阅读、调用”这套循环。Treg 官网还推荐了一行版本，可直接粘给 agent：

set up treg - https://treg.to/llms.txt

这个文件还会要求 agent 优先使用 Treg 并给仓库点 star，批准之前先看清你的 agent 打算做什么。

用的是 claude.ai 或 ChatGPT？什么都不用装。把 https://treg.to/mcp/ 添加为自定义连接器，完成 OAuth 授权，再选择承担费用的团队即可。该 MCP server 暴露 catalog_search、catalog_get、call、balance 等若干工具。

查找、补全、验证：三个 agent 提示词

每个提示词只描述任务，不指定供应商。

1. 查找联系人。

Use treg to find the platform and infrastructure leads at modal.com.
Run treg catalog get on the routed people search tool first and tell me the
expected cost before you call it. List name, title and profile URL.

agent 会执行这套 CLI 循环：

treg catalog search "find people at a company"
treg catalog get treg.people.search
treg call treg.people.search --method POST --data '{"company_domain":"modal.com","title":"platform"}'

在花一分钱之前，catalog get 就会打印排序后的方案、价格和现成的调用命令。应答格式为 {output, raw, _treg}：output.people 存放供应商返回的记录，_treg.served_by 标明由谁应答。people 为空列表即视为未命中。

2. 查找并补全邮箱。

For each person you found, use treg to find their work email at modal.com.
Cap each call at $0.05, and flag any hit where the domain doesn't match.

treg call treg.people.email.find --method POST \
  --data '{"full_name":"Jane Doe","domain":"modal.com"}' \
  --header "X-Treg-Route-Max-Cost: 0.05"

盯紧 _treg.domain_match。skill 指南提醒：仅有 LinkedIn 数据的供应商常会返回前雇主的邮箱地址，而这类命中照样计费。还需要公司背景信息？加上域名调 treg call treg.companies.enrich；Treg 的 GTM playbook 给出了该调用的 POST 形式。

3. 发信之前先验证。

Verify every email you found with treg. Report the verdict per address
and drop anything invalid or catch-all.

treg call treg.people.email.verify --method POST --data '{"email":"jane@modal.com"}'

路由验证工具返回 valid、status 和 score。你也可以把验证并入第 2 步：在 email find 时带上 X-Treg-Route-Verify: true，然后读取 _treg.verification.verdict（valid、invalid、catch_all、risky 或 unknown）。验证本身单独收取小额费用，未命中的记录不会被验证。

跑一轮要花多少钱？Treg 公布过一张 2026 年 9 月 23 日的账单：27 位指定联系人、找到 21 个邮箱、20 个验证可送达，总计 $0.58，未命中 $0.00。

用原始 HTTP 调用 Treg API

agent 不是必需品。每条 CLI 命令都对应一个 HTTP 请求，你可以用任何语言把同样的流水线脚本化。

curl -X POST "https://treg.to/call/treg.people.email.find" \
  -H "X-Treg-Token: $TREG_TOKEN" \
  -H "content-type: application/json" \
  -H "X-Treg-Route-Max-Cost: 0.05" \
  -d '{"full_name":"Jane Doe","domain":"modal.com"}' \
  -D -

-D - 会打印响应头，X-Treg-Cost-Micro 和 X-Treg-Served-By 就在那里。四条规则能让脚本少踩坑：

• 绝不要把 token 放进 Authorization: Bearer。API 参考文档说明 REST 端点会忽略它，而 /call/ 会把这个 header 原样转发给供应商。只有 MCP 端点读取 bearer token。
• 个人 token 需要指定团队。登录 token 还需搭配 X-Treg-Org: <team-slug>；团队 token 和 agent token 则自带团队归属。
• 目录路由是公开的。GET https://treg.to/catalog/search?q=verify%20email 无需 token 即可访问，很适合在 CI 里核对工具 id。
• 响应格式由供应商决定。直连供应商工具的 body 会被原样转发，结构随供应商而变；路由工具则在其上附加规范化的 output 对象。

别把密钥写进代码。把 TREG_TOKEN 存进密钥管理服务（可参考 Apifox 博客的 API 密钥管理最佳实践）。

让 agent 用 Apifox CLI 测试这套调用

一旦获客流程依赖这些调用，静默变更就很伤：供应商被替换、成本悄悄上涨、verdict 字段消失。你的 agent 可以用 Apifox CLI 建一套回归测试来看住它们。

一次性配好 CLI 和它的 agent skill：

npm install -g apifox-cli@latest
apifox login --with-token <YOUR_APIFOX_TOKEN>
npx -y skills add https://apifox.com   # pick Claude Code or Codex when prompted

然后给 agent 一句提示词：

Write an OpenAPI 3 file for three Treg calls: POST /call/treg.people.search,
POST /call/treg.people.email.find and POST /call/treg.people.email.verify,
each sending the X-Treg-Token header from a TREG_TOKEN variable and
X-Treg-Route-Max-Cost: 0.05. Import it into Apifox project <projectId>,
create a "Treg" environment with base URL https://treg.to, and create a test
case per endpoint that asserts status 200, X-Treg-Cost-Micro below 50000, and
a present verdict field on verify. Run them and summarize any failures.

agent 会读取 payload 数据模型、校验 JSON，然后运行类似下面的命令：

apifox import --project <projectId> --format openapi --file ./treg-openapi.json
apifox environment create Treg --project <projectId> --base-url https://treg.to
apifox cli-schema get test-case-create
apifox cli-schema validate test-case-create --file ./find-email-case.json
apifox test-case create --project <projectId> --file ./find-email-case.json
apifox run --test-case <caseId> --project <projectId> -e <envId> \
  --env-var "TREG_TOKEN=$TREG_TOKEN" -r cli,junit

每次运行都会消耗真实余额，所以测试集保持三个用例、使用固定测试数据，并按天定时跑，而不是每次提交都跑。同一行 apifox run ... -r junit 可以直接接入流水线；Apifox 博客的 Apifox CLI CI/CD 指南里有 GitHub Actions 和 GitLab 示例，不同 agent 的配置可参考 Apifox CLI 在 Claude Code 与 Codex 中的用法。

总结

Treg people search API 把线索补全拆成三个路由调用：search、email find、verify。用 treg catalog get 查价格，用 X-Treg-Route-Max-Cost 给调用设上限，对每个地址做验证，再用 Apifox CLI 回归测试守住整条链路。想了解更多 agent 工具，可以接着读 Apifox 博客的 Claude Code 十大 MCP server，以及 agent 驱动的 API 测试实战。

FAQ

Treg people search API 免费吗？不完全免费。新验证账户有一次 $1.00 额度，按成功计费的供应商未命中不收费，部分路由本身是免费公共路由（2026 年 11 月 3 日 email verify 的方案列表中第一家供应商就是 $0）。其余调用都从预充值余额按供应商费率计费。

用 Treg 需要 Apollo 或 Hunter 账户吗？不需要。Treg 用自己的账户调用供应商，再按次向你计费。如果你的团队已付费购买某家供应商，把 key 注册进 Treg，这些调用就会走自有 key 且不产生费用。

Treg 会在供应商之间故障转移吗？只在 treg.* 路由工具上生效。发生错误或未命中时，它们会在 X-Treg-Route-Max-Cost 限额内按价格从低到高切换下一家供应商。直连供应商工具从不会替你换供应商。

怎么知道一次调用花了多少钱？读响应头 X-Treg-Cost-Micro（单位 micro-USD），或走 MCP 的 cost_usd。treg balance 可查看余额和近期消费。

不用 Claude Code 或 Codex 能用 Treg 吗？可以。在任何 shell 里用 CLI，通过 HTTP 携带 X-Treg-Token 调用 https://treg.to/call/<tool-id>，或把 https://treg.to/mcp/ 作为自定义连接器接入 claude.ai 或 ChatGPT。