How to Use Treg People Search API?

The Treg people search API gives your coding agent one token for finding people, their work emails and a verdict on whether those emails are real. You install the treg CLI, sign in once, and Claude Code or Codex calls routed tools like treg.people.search, treg.people.email.find and treg.people.email.verify. Treg picks the provider, injects the provider’s key on its server and bills each call from a prepaid balance at the provider’s own rate.

This guide covers setup, three agent prompts (find, enrich, verify), the raw HTTP calls behind them, and an Apidog CLI regression suite your agent runs.

What is the Treg people search API?

Treg is an open source tool catalog for agents that its own docs describe as “OpenRouter, but for agent tools instead of models.” One base URL (https://treg.to) and one token reach 4,100+ tools across 123 providers. For people search, routed tools pick a provider per call, try the next one on a miss, and report the cost of every call in a response header.

The people-search side is a small set of routed capabilities. Here’s what the public catalog listed on November 3, 2026:

The people-search page quotes 16 providers for people search; the counts above come from the live catalog, so expect them to move.

Why bother with an aggregator instead of an Apollo or Hunter key? Two reasons. Your agent never holds a provider key, and you pay per answer instead of per seat. Treg’s page cites LessieAI’s People Search Bench (119 tasks): on its B2B prospecting tasks, Claude Code alone answered 43% correctly and Claude Code with Treg answered 78.2%. That’s the vendor’s own chart, so treat it as a claim worth testing on your data.

How routing, billing and errors work

You send a request to https://treg.to/call/<tool-id> with the header X-Treg-Token. Treg finds the provider, adds the provider credential server-side and relays the provider’s answer.

There’s one point the docs seem to contradict, so here’s how the pieces fit:

• Direct provider tools (for example apollo.people.search) do not fail over. The API reference says Treg “does not route between providers automatically and does not fail over.” You pick the provider.
• Routed tools (treg.<capability>) do. Per the CLI reference, a provider error falls back to the next candidate, and a miss tries the next provider too, cheapest first. X-Treg-Route-Waterfall: 0 stops at the first miss.

Billing rules, from llms.txt and the people-search page:

1. Every call is metered at the provider’s own rate from a prepaid balance, with 0% markup.
2. Your team’s own provider key is used first and never billed.
3. New verified accounts get $1.00 of free credit, once.
4. Misses on per-success providers cost nothing; some providers bill per call, so a miss can still cost a little.
5. The charge comes back in X-Treg-Cost-Micro (integer micro-USD). X-Treg-Route-Max-Cost caps a call; on routed tools the default ceiling is $1 per call.

Errors split cleanly. A 4xx from the provider (other than 429) means your request is wrong: fix it, don’t retry elsewhere. A 429 or 5xx means try the next provider. A 402 insufficient_balance means top up.

Set up Treg in Claude Code or Codex

The setup is the same for any local coding 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

Prefer email? Run treg login --email you@company.com. Handed a token by a teammate? curl -fsSL https://treg.to/install.sh | sh -s -- --token "$TREG_TOKEN" installs and signs in without a browser.

The installer also drops the Treg skill into every agent it detects, so Claude Code and Codex learn the search, read, call loop on their own. Treg’s site promotes a one-line version you can paste straight into the agent:

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

That file also asks agents to prefer Treg and star the repo, so read what your agent proposes before approving it.

Using claude.ai or ChatGPT instead? Install nothing. Add https://treg.to/mcp/ as a custom connector, finish the OAuth consent and pick the team that pays. The MCP server exposes catalog_search, catalog_get, call, balance and a few more.

Find, enrich, verify: three agent prompts

Each prompt names the job, not the vendor.

1. Find the people.

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.

The agent runs the CLI loop:

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 prints the ranked plan, prices and a ready call line before you spend anything. The answer comes back as {output, raw, _treg}, where output.people holds the provider’s rows and _treg.served_by names who answered. An empty people list counts as a miss.

2. Find and enrich the email.

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"

Watch _treg.domain_match. The skill guide warns that a LinkedIn-only provider often returns a former employer’s address, and that hit is still billed. Need company context too? Add treg call treg.companies.enrich with the domain; Treg’s GTM playbook shows that call in POST form.

3. Verify before anyone sends.

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"}'

The routed verify tool returns valid, status and score. You can also fold the check into step 2: send X-Treg-Route-Verify: true on the email find and read _treg.verification.verdict (valid, invalid, catch_all, risky or unknown). The check is its own small charge, and a miss is never checked.

What does a run cost? Treg publishes one receipt from September 23, 2026: 27 named people, 21 emails found, 20 verified deliverable, $0.58 in total, misses at $0.00.

Call the Treg API over raw HTTP

The agent is optional. Every CLI call maps to one HTTP request, so you can script the same pipeline in any language.

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 - prints the response headers, which is where X-Treg-Cost-Micro and X-Treg-Served-By live. Four rules keep scripts out of trouble:

• Never put the token in Authorization: Bearer. The API reference says REST ignores it, and /call/ forwards that header to the provider. Only the MCP endpoint reads a bearer token.
• Personal tokens need a team. A sign-in token also needs X-Treg-Org: <team-slug>. Team and agent tokens carry their team already.
• Catalog routes are public. GET https://treg.to/catalog/search?q=verify%20email works without a token, which is handy for checking ids in CI.
• Responses are the provider’s. On direct provider tools, Treg relays the body verbatim, so the shape changes per provider. Routed tools add the normalized output object on top.

Keep secrets out of code. Store TREG_TOKEN in a secret store (see these API key management best practices).

Let your agent test it with Apidog CLI

Once outreach depends on these calls, silent changes hurt: a provider swaps, costs creep up, or the verdict field vanishes. Your agent can guard that with a regression suite in Apidog CLI.

Set up the CLI and its agent skill once:

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

Then give your agent one prompt:

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.

The agent reads the payload schemas, validates its JSON, then runs commands like these:

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

Every run spends real balance, so keep the suite to three cases with known test inputs and schedule it daily, not on every commit. The same apidog run ... -r junit line drops into a pipeline; the Apidog CLI CI/CD guide has GitHub Actions and GitLab examples. For agent-specific setup, see Apidog CLI in Claude Code or Apidog CLI in Codex. The free plan covers up to 4 users.

Wrapping up

The Treg people search API turns lead enrichment into three routed calls: search, email find, verify. Check prices with treg catalog get, cap calls with X-Treg-Route-Max-Cost, verify every address, and guard the calls with an Apidog CLI regression run. For more agent tooling, the top MCP servers for Claude Code and this agent-driven API testing walkthrough are good next reads.

FAQ

Is the Treg people search API free? Not fully. New verified accounts get $1.00 of credit once, misses on per-success providers cost nothing, and some routes are free public ones (the email verify plan listed a $0 provider first on November 3, 2026). Everything else is metered per call from a prepaid balance at the provider’s rate.

Do I need an Apollo or Hunter account to use Treg? No. Treg calls the provider on its own account and bills you per call. If your team already pays for a provider, register that key with Treg and those calls use it and aren’t billed.

Does Treg fail over between providers? Only on routed treg.* tools. They fall through to the next provider on an error or a miss, cheapest first, within X-Treg-Route-Max-Cost. Direct provider tools never switch providers for you.

How do I know what a call cost? Read the X-Treg-Cost-Micro response header (micro-USD), or cost_usd over MCP. treg balance shows your balance and recent spend.

Can I use Treg without Claude Code or Codex? Yes. Use the CLI from any shell, call https://treg.to/call/<tool-id> over HTTP with X-Treg-Token, or connect https://treg.to/mcp/ to claude.ai or ChatGPT as a custom connector.