Akira

Posted on Nov 3 Originally published at apidog.com

Treg People Search APIの使い方

Treg People Search API の使い方

Treg people search API を使うと、コーディングエージェントは 1 つのトークンで、人物の検索、その仕事用メールアドレスの取得、さらにそのメールが実在するかどうかの判定までをまとめて行えます。treg CLI をインストールして一度サインインするだけで、Claude Code や Codex が treg.people.search、treg.people.email.find、treg.people.email.verify といったルーティング済みツールをそのまま呼び出せるようになります。プロバイダーの選定は Treg が行い、プロバイダーのキーは Treg のサーバー上で注入され、各呼び出しはプロバイダー自身の料金でプリペイド残高から請求されます。

今すぐ Apidog を試す

この記事では、セットアップ手順、3 つのエージェントプロンプト（検索・エンリッチ・検証）、その裏で飛んでいる生の HTTP 呼び出し、そしてエージェントに実行させる Apidog CLI の回帰スイートを順に説明します。

Treg people search API とは？

Treg はエージェント向けのオープンソースツールカタログで、公式ドキュメントでは「モデルではなくエージェントツールのための OpenRouter」と説明されています。ベース URL（https://treg.to）とトークンが 1 つあれば、123 のプロバイダーが提供する 4,100 以上のツールにアクセスできます。人物検索の領域では、ルーティング済みツールが呼び出しごとにプロバイダーを選定し、ミスがあれば次のプロバイダーを試し、すべての呼び出しのコストをレスポンスヘッダーで報告します。

人物検索側は、少数のルーティング済みケイパビリティの集合です。2026 年 11 月 3 日時点で公開カタログに掲載されていたものは以下のとおりです。

ルーティング済みツール	機能	受け付ける入力	背後のプロバイダー数
`treg.people.search`	企業または説明文から人物を検索する	`q`、`company_domain`、`company_domain` + `title`、`title`、`full_name`	26
`treg.people.email.find`	最適な仕事用メールアドレスを返す	`domain` + `full_name`、`domain` + `first_name` + `last_name`、`linkedin_url`	30
`treg.people.email.verify`	メールボックスがメールを受け付けるかどうかを確認する	`email`	17
`treg.companies.enrich`	企業のファームグラフィックス	企業ドメイン	30

人物検索ページでは人物検索プロバイダーを 16 社として紹介していますが、上の数字はライブカタログから取得したものであり、変動することを想定してください。

Apollo や Hunter のキーを直接持つのではなく、なぜアグリゲーターを使うのか？　理由は 2 つです。エージェントがプロバイダーのキーを一切保持しなくてよいこと、そして席単位ではなく回答単位で支払うことです。Treg のページでは LessieAI の People Search Bench（119 タスク）を引用しています。それによると、B2B プロスペクティングタスクにおいて Claude Code 単体は 43% しか正答できなかったのに対し、Treg と組み合わせた Claude Code は 78.2% に達したとされています。これはベンダー自身が公表したチャートなので、自社のデータで試す価値のある主張として扱ってください。

ルーティング、課金、エラーの仕組み

リクエストは https://treg.to/call/<tool-id> に対して X-Treg-Token ヘッダーを付けて送信します。Treg がプロバイダーを特定し、サーバーサイドでプロバイダーの認証情報を追加し、プロバイダーの回答を中継します。

ドキュメントが矛盾しているように見える点が 1 つあるので、ここで各部分の関係を整理します。

直接プロバイダーツール（例： apollo.people.search）はフェイルオーバーしません。API リファレンスには、Treg は「プロバイダー間を自動でルーティングせず、フェイルオーバーもしない」と記載されています。プロバイダーを選ぶのはあなたです。
ルーティング済みツール（treg.<capability>）はフェイルオーバーします。CLI リファレンスによると、プロバイダーエラーが発生すると次の候補にフォールバックし、ミスの場合も（最も安いものから順に）次のプロバイダーを試します。X-Treg-Route-Waterfall: 0 を指定すると最初のミスで停止します。

課金ルールは llms.txt と人物検索ページによると以下のとおりです。

すべての呼び出しは、プロバイダー自身の料金でプリペイド残高から課金されます。マークアップは 0% です。
チーム自身のプロバイダーキーが最初に使用され、それらの呼び出しは課金されません。
新規の検証済みアカウントには、一度だけ $1.00 の無料クレジットが付与されます。
成功課金制のプロバイダーでのミスは無料です。ただし一部のプロバイダーは呼び出しごとに課金するため、ミスでも少額のコストがかかることがあります。
料金は X-Treg-Cost-Micro（整数のマイクロ USD）として返されます。X-Treg-Route-Max-Cost は呼び出しごとの上限を設定します。ルーティング済みツールのデフォルト上限は 1 呼び出しあたり $1 です。

エラーは明確に分類されています。プロバイダーからの 4xx（429 を除く）はリクエスト自体が誤っているという意味です。修正すべきであり、別のプロバイダーでリトライすべきではありません。429 または 5xx は次のプロバイダーを試すという合図です。402 insufficient_balance はチャージが必要という意味です。

Claude Code または Codex で Treg をセットアップする

セットアップは、任意のローカルコーディングエージェント（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

メールでサインインしたい場合は？　bash treg login --email you@company.com を実行してください。チームメイトからトークンを受け取った場合は？　bash curl -fsSL https://treg.to/install.sh | sh -s -- --token "$TREG_TOKEN" でブラウザなしにインストールとサインインを済ませられます。

インストーラーは、検出したすべてのエージェントに Treg スキルも配置するため、Claude Code と Codex は検索・読み取り・呼び出しのループを自力で学習します。Treg のサイトでは、エージェントにそのまま貼り付けられる 1 行版も紹介されています。

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

このファイルは、エージェントに対して Treg を優先することやリポジトリにスターを付けることも求めているため、承認する前にエージェントが提案する内容を確認してください。

代わりに claude.ai や ChatGPT を使っていますか？　その場合は何もインストールする必要がありません。https://treg.to/mcp/ をカスタムコネクターとして追加し、OAuth の同意を完了して、支払いを行うチームを選択してください。MCP サーバーは catalog_search、catalog_get、call、balance などを公開しています。

検索、エンリッチ、検証：3 つのエージェントプロンプト

各プロンプトはベンダーではなく、実行する仕事を指定します。

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.

エージェントは 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"}'

treg 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 に注目してください。スキルガイドは、LinkedIn オンリーのプロバイダーがしばしば前職のアドレスを返すこと、そしてそのヒットでも課金されることを警告しています。企業のコンテキストも必要ですか？　ドメインを指定して treg call treg.companies.enrich を追加してください。Treg の GTM プレイブックでは、その呼び出しが 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"}'

ルーティング済みの verify ツールは valid、status、score を返します。このチェックをステップ 2 に組み込むこともできます。email find で X-Treg-Route-Verify: true を送信し、_treg.verification.verdict（valid、invalid、catch_all、risky、または unknown）を読み取ってください。このチェックには独自の少額の料金がかかり、ミスしたものは決してチェックされません。

1 回の実行にいくらかかるのでしょうか？　Treg は 2026 年 9 月 23 日付けのレシートを 1 つ公開しています。27 名の人物が特定され、21 件のメールが見つかり、20 件が配信可能と検証され、合計 $0.58、ミスは $0.00 でした。

生の HTTP で Treg API を呼び出す

エージェントは必須ではありません。すべての CLI 呼び出しは 1 つの HTTP リクエストに対応するため、同じパイプラインを任意の言語でスクリプト化できます。

curl -X POST "https://treg.to/call/treg.people.email.find" \
  -H "X-Treg-[REDACTED CREDENTIAL] \
  -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 が含まれます。スクリプトをトラブルから守る 4 つのルールがあります。

トークンを絶対に Authorization: Bearer に入れないでください。 API リファレンスによると、REST はそのヘッダーを無視し、/call/ はそれをプロバイダーに転送します。ベアラートークンを読み取るのは MCP エンドポイントだけです。
個人トークンにはチームが必要です。 サインインで発行されたトークンには X-Treg-Org: <team-slug> も必要です。チームトークンとエージェントトークンにはすでにチームが含まれています。
カタログルートは公開されています。 GET https://treg.to/catalog/search?q=verify%20email はトークンなしで動作するため、CI でツール ID を確認するのに便利です。
レスポンスはプロバイダーのものです。 直接プロバイダーツールでは、Treg はボディをそのまま中継するため、形式はプロバイダーごとに変わります。ルーティング済みツールはその上に正規化された output オブジェクトを追加します。

シークレットはコードに含めないでください。TREG_TOKEN はシークレットストアに保存してください（API キー管理のベストプラクティスを参照）。

エージェントに Apidog CLI でテストさせる

アウトリーチがこれらの呼び出しに依存するようになると、気付かないうちの変更が痛手となります。プロバイダーが切り替わったり、コストがじわじわ増えたり、判定フィールドが消えたりするからです。エージェントは Apidog CLI の回帰スイートでこれを防ぐことができます。

CLI とそのエージェントスキルは一度セットアップすれば済みます。

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

次に、エージェントに 1 つのプロンプトを与えます。

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 Apidog 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.

エージェントはペイロードスキーマを読み、その JSON を検証してから、次のようなコマンドを実行します。

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

実行するたびに実際の残高を消費するため、スイートは既知のテスト入力を使った 3 ケースに抑え、コミットごとではなく毎日スケジュール実行してください。同じ apidog run ... -r junit の行はパイプラインにそのまま組み込めます。Apidog CLI CI/CD ガイドには GitHub Actions と GitLab の例があります。エージェント固有のセットアップについては、Claude Code での Apidog CLI または Codex での Apidog CLI を参照してください。無料プランでは最大 4 ユーザーまで利用できます。

まとめ

Treg people search API は、リードのエンリッチメントを「検索、メール検索、検証」という 3 つのルーティング済み呼び出しにまとめ上げます。価格は treg catalog get で確認し、呼び出しは X-Treg-Route-Max-Cost で上限を設定し、すべてのアドレスを検証し、呼び出しは Apidog CLI の回帰実行で守ってください。エージェントツールについてさらに知りたい場合は、Claude Code 向けトップ MCP サーバーとエージェント駆動の API テストウォークスルーが次に読むのに適しています。

FAQ

Treg people search API は無料ですか？
完全に無料ではありません。新規の検証済みアカウントには一度だけ $1.00 のクレジットが付与され、成功課金制のプロバイダーでのミスは無料で、一部のルートは無料の公開ルートです（email verify のプランでは 2026 年 11 月 3 日時点で $0 のプロバイダーが最初に掲載されていました）。それ以外はすべて、プロバイダーの料金でプリペイド残高から呼び出しごとに課金されます。

Treg を使うのに Apollo や Hunter のアカウントは必要ですか？
いいえ。Treg は自身のアカウントでプロバイダーを呼び出し、呼び出しごとにあなたに請求します。チームがすでにプロバイダーに支払っている場合は、そのキーを Treg に登録すれば、それらの呼び出しはそのキーを使用し、課金されません。

Treg はプロバイダー間でフェイルオーバーしますか？
ルーティング済みの treg.* ツールでのみ行います。これらはエラーまたはミスの際に、X-Treg-Route-Max-Cost の範囲内で、最も安いものから順に次のプロバイダーへフォールスルーします。直接プロバイダーツールは決してプロバイダーを切り替えません。

呼び出しのコストはどうやって分かりますか？
X-Treg-Cost-Micro レスポンスヘッダー（マイクロ USD）を読むか、MCP 経由で cost_usd を確認してください。treg balance は残高と最近の支出を表示します。

Claude Code や Codex なしで Treg を使えますか？
はい。任意のシェルから CLI を使用したり、X-Treg-Token を付けて HTTP で https://treg.to/call/<tool-id> を呼び出したり、https://treg.to/mcp/ をカスタムコネクターとして claude.ai や ChatGPT に接続したりできます。

DEV Community