Hướng dẫn sử dụng Treg People Search API

API tìm kiếm người của Treg cung cấp cho tác nhân lập trình của bạn một token để tìm người, email công việc của họ và một phán quyết về việc những email đó có thật hay không. Bạn cài CLI treg, đăng nhập một lần, và Claude Code hoặc Codex gọi các công cụ được định tuyến như treg.people.search, treg.people.email.find và treg.people.email.verify. Treg chọn nhà cung cấp, chèn khóa của nhà cung cấp trên máy chủ của mình và tính phí mỗi lần gọi từ số dư trả trước theo đúng mức giá của nhà cung cấp.

Hướng dẫn này bao gồm việc thiết lập, ba câu lệnh gợi ý cho tác nhân (tìm, làm giàu, xác minh), các lệnh gọi HTTP thô phía sau chúng, và một bộ kiểm thử hồi quy Apidog CLI mà tác nhân của bạn chạy.

API tìm kiếm người của Treg là gì?

Treg là một danh mục công cụ mã nguồn mở dành cho các tác nhân mà tài liệu của chính nó mô tả là “OpenRouter, nhưng dành cho công cụ tác nhân thay vì mô hình.” Một URL cơ sở (https://treg.to) và một token có thể truy cập hơn 4.100 công cụ trên 123 nhà cung cấp. Đối với tìm kiếm người, các công cụ được định tuyến sẽ chọn một nhà cung cấp cho mỗi lần gọi, thử nhà cung cấp tiếp theo khi trượt, và báo cáo chi phí của mỗi lần gọi trong một header phản hồi.

Phần tìm kiếm người là một tập nhỏ các khả năng được định tuyến. Đây là những gì danh mục công khai liệt kê vào ngày 3 tháng 11 năm 2026:

Công cụ được định tuyến	Nó làm gì	Đầu vào nó chấp nhận	Các nhà cung cấp đứng sau
`treg.people.search`	Tìm người tại một công ty hoặc theo mô tả	`q`, `company_domain`, `company_domain` + `title`, `title`, `full_name`	26
`treg.people.email.find`	Trả về email công việc khớp nhất	`domain` + `full_name`, `domain` + `first_name` + `last_name`, `linkedin_url`	30
`treg.people.email.verify`	Kiểm tra xem một hộp thư có nhận thư không	`email`	17
`treg.companies.enrich`	Thông tin nhân khẩu học doanh nghiệp cho một công ty	tên miền công ty	30

Trang tìm kiếm người dẫn nguồn 16 nhà cung cấp cho tìm kiếm người; các con số ở trên đến từ danh mục trực tiếp, nên hãy mong đợi chúng sẽ thay đổi.

Tại sao phải bận tâm với một bên tổng hợp thay vì dùng khóa Apollo hay Hunter? Hai lý do. Tác nhân của bạn không bao giờ giữ khóa nhà cung cấp, và bạn trả tiền theo câu trả lời thay vì theo chỗ ngồi. Trang của Treg dẫn nguồn People Search Bench của LessieAI (119 tác vụ): trên các tác vụ tìm kiếm khách hàng B2B của nó, chỉ Claude Code trả lời đúng 43% và Claude Code với Treg trả lời đúng 78,2%. Đó là biểu đồ của chính nhà cung cấp, nên hãy coi nó như một tuyên bố đáng để kiểm chứng trên dữ liệu của bạn.

Định tuyến, tính phí và lỗi hoạt động như thế nào

Bạn gửi một yêu cầu đến https://treg.to/call/<tool-id> với header X-Treg-Token. Treg tìm nhà cung cấp, thêm thông tin xác thực của nhà cung cấp ở phía máy chủ và chuyển tiếp câu trả lời của nhà cung cấp.

Diagram of a Treg call: the coding agent sends a request with the X-Treg-Token header to treg.to/call, which tries providers in a waterfall and returns the provider response plus the X-Treg-Cost-Micro header

Có một điểm mà tài liệu có vẻ mâu thuẫn, nên đây là cách các mảnh ghép khớp với nhau:

Công cụ nhà cung cấp trực tiếp (ví dụ apollo.people.search) không chuyển đổi dự phòng. Tài liệu tham chiếu API nói Treg “không định tuyến giữa các nhà cung cấp một cách tự động và không chuyển đổi dự phòng.” Bạn chọn nhà cung cấp.
Công cụ được định tuyến (treg.<capability>) thì có. Theo tài liệu tham chiếu CLI, lỗi từ nhà cung cấp sẽ chuyển sang ứng viên tiếp theo, và một lần trượt cũng thử nhà cung cấp tiếp theo, rẻ nhất trước. X-Treg-Route-Waterfall: 0 dừng lại ở lần trượt đầu tiên.

Các quy tắc tính phí, từ llms.txt và trang tìm kiếm người:

Mọi lần gọi đều được tính theo mức giá của chính nhà cung cấp từ số dư trả trước, với mức đánh dấu 0%.
Khóa nhà cung cấp của chính nhóm bạn được dùng trước và không bao giờ bị tính phí.
Các tài khoản đã xác minh mới nhận 1,00 đô la tín dụng miễn phí, một lần.
Các lần trượt trên những nhà cung cấp tính theo thành công không tốn phí; một số nhà cung cấp tính phí theo lần gọi, nên một lần trượt vẫn có thể tốn một chút.
Khoản phí được trả về trong X-Treg-Cost-Micro (số nguyên micro-USD). X-Treg-Route-Max-Cost giới hạn một lần gọi; trên các công cụ được định tuyến, mức trần mặc định là 1 đô la mỗi lần gọi.

Lỗi được phân chia rõ ràng. Mã 4xx từ nhà cung cấp (ngoài 429) nghĩa là yêu cầu của bạn sai: hãy sửa nó, đừng thử lại ở nơi khác. Mã 429 hoặc 5xx nghĩa là hãy thử nhà cung cấp tiếp theo. Mã 402 insufficient_balance nghĩa là hãy nạp thêm tiền.

Thiết lập Treg trong Claude Code hoặc Codex

Việc thiết lập giống nhau với mọi tác nhân lập trình cục bộ (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

Thích dùng email hơn? Chạy treg login --email you@company.com. Được đồng nghiệp đưa cho một token? curl -fsSL https://treg.to/install.sh | sh -s -- --token "$TREG_TOKEN" sẽ cài và đăng nhập mà không cần trình duyệt.

Trình cài đặt cũng đưa kỹ năng Treg vào mọi tác nhân mà nó phát hiện, nên Claude Code và Codex tự học được vòng lặp tìm kiếm, đọc, gọi. Trang của Treg quảng bá một phiên bản một dòng mà bạn có thể dán thẳng vào tác nhân:

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

Tệp đó cũng yêu cầu các tác nhân ưu tiên dùng Treg và gắn sao cho repo, nên hãy đọc những gì tác nhân của bạn đề xuất trước khi phê duyệt.

Thay vào đó dùng claude.ai hoặc ChatGPT? Không cần cài gì cả. Thêm https://treg.to/mcp/ làm trình kết nối tùy chỉnh, hoàn tất đồng ý OAuth và chọn nhóm trả tiền. Máy chủ MCP cung cấp catalog_search, catalog_get, call, balance và một vài thứ khác.

Tìm, làm giàu, xác minh: ba câu lệnh gợi ý cho tác nhân

Mỗi câu lệnh gợi ý nêu tên công việc, không nêu tên nhà cung cấp.

Pipeline diagram: people.search finds who runs platform at a company, people.email.find returns a best-match work email, people.email.verify returns valid, invalid or catch_all, with an Apidog CLI regression run below checking status 200, cost under cap and verdict present

1. Tìm người.

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.

Tác nhân chạy vòng lặp 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 in ra kế hoạch đã xếp hạng, giá cả và một dòng gọi sẵn sàng trước khi bạn tiêu bất cứ thứ gì. Câu trả lời trở về dưới dạng {output, raw, _treg}, trong đó output.people chứa các hàng của nhà cung cấp và _treg.served_by nêu tên ai đã trả lời. Danh sách people rỗng được tính là một lần trượt.

2. Tìm và làm giàu 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"

Hãy để ý _treg.domain_match. Hướng dẫn kỹ năng cảnh báo rằng một nhà cung cấp chỉ dùng LinkedIn thường trả về địa chỉ của một nhà tuyển dụng cũ, và lần trúng đó vẫn bị tính phí. Cũng cần ngữ cảnh công ty? Thêm treg call treg.companies.enrich với tên miền; cẩm nang GTM của Treg hiển thị lệnh gọi đó ở dạng POST.

3. Xác minh trước khi bất kỳ ai gửi.

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

Công cụ xác minh được định tuyến trả về valid, status và score. Bạn cũng có thể gộp bước kiểm tra vào bước 2: gửi X-Treg-Route-Verify: true trong lệnh tìm email và đọc _treg.verification.verdict (valid, invalid, catch_all, risky hoặc unknown). Việc kiểm tra có một khoản phí nhỏ riêng, và một lần trượt không bao giờ được kiểm tra.

Một lần chạy tốn bao nhiêu? Treg công bố một hóa đơn từ ngày 23 tháng 9 năm 2026: 27 người được nêu tên, 21 email được tìm thấy, 20 được xác minh là có thể gửi đến, tổng cộng 0,58 đô la, các lần trượt ở mức 0,00 đô la.

Gọi API Treg qua HTTP thô

Tác nhân là tùy chọn. Mọi lệnh gọi CLI ánh xạ tới một yêu cầu HTTP, nên bạn có thể viết script cho cùng một quy trình bằng bất kỳ ngôn ngữ nào.

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 - in ra các header phản hồi, đó là nơi X-Treg-Cost-Micro và X-Treg-Served-By nằm. Bốn quy tắc giữ cho các script không gặp rắc rối:

Đừng bao giờ đặt token vào Authorization: Bearer. Tài liệu tham chiếu API nói REST bỏ qua nó, và /call/ chuyển tiếp header đó đến nhà cung cấp. Chỉ endpoint MCP đọc token bearer.
Token cá nhân cần một nhóm. Token đăng nhập cũng cần X-Treg-Org: <team-slug>. Token nhóm và token tác nhân đã mang sẵn nhóm của chúng.
Các tuyến danh mục là công khai. GET https://treg.to/catalog/search?q=verify%20email hoạt động mà không cần token, rất tiện để kiểm tra id trong CI.
Phản hồi là của nhà cung cấp. Trên các công cụ nhà cung cấp trực tiếp, Treg chuyển tiếp nguyên văn phần thân, nên hình dạng thay đổi theo từng nhà cung cấp. Các công cụ được định tuyến thêm đối tượng output đã chuẩn hóa lên trên.

Giữ bí mật ngoài mã nguồn. Lưu TREG_TOKEN trong một kho bí mật (xem các thực hành tốt nhất về quản lý khóa API này).

Để tác nhân của bạn kiểm thử nó bằng Apidog CLI

Một khi việc tiếp cận phụ thuộc vào những lệnh gọi này, những thay đổi âm thầm sẽ gây hại: một nhà cung cấp bị thay đổi, chi phí tăng dần, hoặc trường phán quyết biến mất. Tác nhân của bạn có thể bảo vệ điều đó bằng một bộ kiểm thử hồi quy trong Apidog CLI.

Thiết lập CLI và kỹ năng tác nhân của nó một lần:

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

Sau đó đưa cho tác nhân của bạn một câu lệnh gợi ý:

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.

Tác nhân đọc các lược đồ payload, xác thực JSON của nó, rồi chạy các lệnh như sau:

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

Mỗi lần chạy tiêu tốn số dư thật, nên hãy giữ bộ kiểm thử ở ba trường hợp với đầu vào kiểm thử đã biết và lên lịch chạy hằng ngày, không phải mỗi lần commit. Cùng dòng apidog run ... -r junit đó có thể thả vào một pipeline; hướng dẫn Apidog CLI CI/CD có các ví dụ GitHub Actions và GitLab. Để biết thiết lập dành riêng cho tác nhân, xem Apidog CLI trong Claude Code hoặc Apidog CLI trong Codex. Gói miễn phí bao gồm tối đa 4 người dùng.

Tổng kết

API tìm kiếm người của Treg biến việc làm giàu khách hàng tiềm năng thành ba lệnh gọi được định tuyến: tìm kiếm, tìm email, xác minh. Kiểm tra giá bằng treg catalog get, giới hạn các lệnh gọi bằng X-Treg-Route-Max-Cost, xác minh mọi địa chỉ, và bảo vệ các lệnh gọi bằng một lần chạy hồi quy Apidog CLI. Để biết thêm về công cụ tác nhân, top 10 máy chủ MCP cho Claude Code và hướng dẫn kiểm thử API do tác nhân điều khiển này là những bài đọc tiếp theo hay.

Câu hỏi thường gặp

API tìm kiếm người của Treg có miễn phí không? Không hoàn toàn. Các tài khoản đã xác minh mới nhận 1,00 đô la tín dụng một lần, các lần trượt trên những nhà cung cấp tính theo thành công không tốn phí, và một số tuyến là công khai miễn phí (kế hoạch xác minh email liệt kê một nhà cung cấp 0 đô la đầu tiên vào ngày 3 tháng 11 năm 2026). Mọi thứ khác đều được tính theo lần gọi từ số dư trả trước theo mức giá của nhà cung cấp.

Tôi có cần tài khoản Apollo hay Hunter để dùng Treg không? Không. Treg gọi nhà cung cấp bằng tài khoản của chính nó và tính phí bạn theo lần gọi. Nếu nhóm bạn đã trả tiền cho một nhà cung cấp, hãy đăng ký khóa đó với Treg và những lệnh gọi đó sẽ dùng nó và không bị tính phí.

Treg có chuyển đổi dự phòng giữa các nhà cung cấp không? Chỉ trên các công cụ treg.* được định tuyến. Chúng chuyển sang nhà cung cấp tiếp theo khi có lỗi hoặc trượt, rẻ nhất trước, trong giới hạn X-Treg-Route-Max-Cost. Các công cụ nhà cung cấp trực tiếp không bao giờ tự đổi nhà cung cấp cho bạn.

Làm sao biết một lần gọi tốn bao nhiêu? Đọc header phản hồi X-Treg-Cost-Micro (micro-USD), hoặc cost_usd qua MCP. treg balance hiển thị số dư và chi tiêu gần đây của bạn.

Tôi có thể dùng Treg mà không cần Claude Code hay Codex không? Có. Dùng CLI từ bất kỳ shell nào, gọi https://treg.to/call/<tool-id> qua HTTP với X-Treg-Token, hoặc kết nối https://treg.to/mcp/ với claude.ai hoặc ChatGPT như một trình kết nối tùy chỉnh.

button