Cómo usar la API de búsqueda de personas de Treg

La API de búsqueda de personas de Treg le da a tu agente de código un solo token para encontrar personas, sus correos electrónicos de trabajo y un veredicto sobre si esos correos son reales. Instalas la CLI de treg, inicias sesión una vez, y Claude Code o Codex llaman a herramientas enrutadas como treg.people.search, treg.people.email.find y treg.people.email.verify. Treg elige el proveedor, inyecta la clave del proveedor en su servidor y factura cada llamada desde un saldo prepago a la tarifa del propio proveedor.

Esta guía cubre la configuración, tres prompts de agente (buscar, enriquecer, verificar), las llamadas HTTP sin procesar detrás de ellos, y una suite de regresión de Apidog CLI que tu agente ejecuta.

¿Qué es la API de búsqueda de personas de Treg?

Treg es un catálogo de herramientas de código abierto para agentes que su propia documentación describe como «OpenRouter, pero para herramientas de agente en lugar de modelos». Una URL base (https://treg.to) y un token dan acceso a más de 4100 herramientas en 123 proveedores. Para la búsqueda de personas, las herramientas enrutadas eligen un proveedor por llamada, prueban el siguiente en caso de fallo, e informan el costo de cada llamada en un encabezado de respuesta.

El lado de búsqueda de personas es un pequeño conjunto de capacidades enrutadas. Esto es lo que el catálogo público listaba el 3 de noviembre de 2026:

Herramienta enrutada	Qué hace	Entradas que acepta	Proveedores detrás
`treg.people.search`	Encuentra personas en una empresa o por descripción	`q`, `company_domain`, `company_domain` + `title`, `title`, `full_name`	26
`treg.people.email.find`	Devuelve el correo electrónico de trabajo que mejor coincide	`domain` + `full_name`, `domain` + `first_name` + `last_name`, `linkedin_url`	30
`treg.people.email.verify`	Comprueba si un buzón acepta correo	`email`	17
`treg.companies.enrich`	Datos firmográficos de una empresa	dominio de la empresa	30

La página de búsqueda de personas cita 16 proveedores para la búsqueda de personas; los conteos anteriores provienen del catálogo en vivo, así que espera que cambien.

¿Por qué molestarse con un agregador en lugar de una clave de Apollo o Hunter? Dos razones. Tu agente nunca posee una clave de proveedor, y pagas por respuesta en lugar de por asiento. La página de Treg cita el People Search Bench de LessieAI (119 tareas): en sus tareas de prospección B2B, Claude Code solo respondió correctamente el 43 % y Claude Code con Treg respondió el 78,2 %. Ese es el gráfico del propio proveedor, así que trátalo como una afirmación que vale la pena probar con tus datos.

Cómo funcionan el enrutamiento, la facturación y los errores

Envías una solicitud a https://treg.to/call/<tool-id> con el encabezado X-Treg-Token. Treg encuentra el proveedor, añade la credencial del proveedor del lado del servidor y retransmite la respuesta del proveedor.

Diagrama de una llamada a Treg: el agente de código envía una solicitud con el encabezado X-Treg-Token a treg.to/call, que prueba proveedores en cascada y devuelve la respuesta del proveedor más el encabezado X-Treg-Cost-Micro

Hay un punto en el que la documentación parece contradecirse, así que aquí está cómo encajan las piezas:

Las herramientas directas de proveedor (por ejemplo apollo.people.search) no hacen conmutación por error. La referencia de la API dice que Treg «no enruta entre proveedores automáticamente y no hace conmutación por error». Tú eliges el proveedor.
Las herramientas enrutadas (treg.<capability>) sí lo hacen. Según la referencia de la CLI, un error del proveedor recurre al siguiente candidato, y un fallo también prueba el siguiente proveedor, del más barato al más caro. X-Treg-Route-Waterfall: 0 se detiene en el primer fallo.

Reglas de facturación, según llms.txt y la página de búsqueda de personas:

Cada llamada se mide a la tarifa del propio proveedor desde un saldo prepago, con un 0 % de margen.
La clave de proveedor propia de tu equipo se usa primero y nunca se factura.
Las cuentas nuevas verificadas reciben $1.00 de crédito gratuito, una sola vez.
Los fallos en proveedores que cobran por éxito no cuestan nada; algunos proveedores cobran por llamada, así que un fallo aún puede costar un poco.
El cargo se devuelve en X-Treg-Cost-Micro (micro-USD entero). X-Treg-Route-Max-Cost limita una llamada; en las herramientas enrutadas, el techo predeterminado es $1 por llamada.

Los errores se dividen con claridad. Un 4xx del proveedor (que no sea 429) significa que tu solicitud está mal: corrígela, no reintentes en otro sitio. Un 429 o 5xx significa probar el siguiente proveedor. Un 402 insufficient_balance significa recargar.

Configura Treg en Claude Code o Codex

La configuración es la misma para cualquier agente de código local (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

¿Prefieres el correo electrónico? Ejecuta treg login --email you@company.com. ¿Un compañero de equipo te dio un token? curl -fsSL https://treg.to/install.sh | sh -s -- --token "$TREG_TOKEN" instala e inicia sesión sin navegador.

El instalador también coloca la skill de Treg en cada agente que detecta, para que Claude Code y Codex aprendan por su cuenta el bucle de buscar, leer, llamar. El sitio de Treg promociona una versión de una línea que puedes pegar directamente en el agente:

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

Ese archivo también pide a los agentes que prefieran Treg y den una estrella al repositorio, así que lee lo que tu agente propone antes de aprobarlo.

¿Usas claude.ai o ChatGPT en su lugar? No instales nada. Añade https://treg.to/mcp/ como conector personalizado, completa el consentimiento OAuth y elige el equipo que paga. El servidor MCP expone catalog_search, catalog_get, call, balance y algunos más.

Buscar, enriquecer, verificar: tres prompts de agente

Cada prompt nombra la tarea, no el proveedor.

Diagrama de canalización: people.search encuentra quién dirige la plataforma en una empresa, people.email.find devuelve el correo electrónico de trabajo que mejor coincide, people.email.verify devuelve valid, invalid o catch_all, con una ejecución de regresión de Apidog CLI debajo que comprueba el estado 200, un costo por debajo del límite y la presencia del veredicto

1. Encuentra a las personas.

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.

El agente ejecuta el bucle de la 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 imprime el plan clasificado, los precios y una línea de llamada lista antes de que gastes nada. La respuesta vuelve como {output, raw, _treg}, donde output.people contiene las filas del proveedor y _treg.served_by nombra quién respondió. Una lista people vacía cuenta como un fallo.

2. Encuentra y enriquece el correo electrónico.

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"

Vigila _treg.domain_match. La guía de la skill advierte que un proveedor que solo usa LinkedIn a menudo devuelve la dirección de un empleador anterior, y ese resultado igualmente se factura. ¿Necesitas también contexto de la empresa? Añade treg call treg.companies.enrich con el dominio; el manual GTM de Treg muestra esa llamada en formato POST.

3. Verifica antes de que alguien envíe.

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

La herramienta de verificación enrutada devuelve valid, status y score. También puedes integrar la comprobación en el paso 2: envía X-Treg-Route-Verify: true en la búsqueda de correo electrónico y lee _treg.verification.verdict (valid, invalid, catch_all, risky o unknown). La comprobación tiene su propio cargo pequeño, y un fallo nunca se comprueba.

¿Cuánto cuesta una ejecución? Treg publica un recibo del 23 de septiembre de 2026: 27 personas identificadas, 21 correos electrónicos encontrados, 20 verificados como entregables, $0,58 en total, fallos a $0,00.

Llama a la API de Treg mediante HTTP sin procesar

El agente es opcional. Cada llamada de la CLI corresponde a una solicitud HTTP, así que puedes programar la misma canalización en cualquier lenguaje.

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 - imprime los encabezados de respuesta, que es donde viven X-Treg-Cost-Micro y X-Treg-Served-By. Cuatro reglas mantienen los scripts fuera de problemas:

Nunca pongas el token en Authorization: Bearer. La referencia de la API dice que REST lo ignora, y /call/ reenvía ese encabezado al proveedor. Solo el endpoint MCP lee un token bearer.
Los tokens personales necesitan un equipo. Un token de inicio de sesión también necesita X-Treg-Org: <team-slug>. Los tokens de equipo y de agente ya llevan su equipo.
Las rutas del catálogo son públicas. GET https://treg.to/catalog/search?q=verify%20email funciona sin token, lo cual es útil para comprobar ids en CI.
Las respuestas son del proveedor. En las herramientas directas de proveedor, Treg retransmite el cuerpo textualmente, así que la forma cambia según el proveedor. Las herramientas enrutadas añaden encima el objeto output normalizado.

Mantén los secretos fuera del código. Guarda TREG_TOKEN en un almacén de secretos (consulta estas buenas prácticas de gestión de claves de API).

Deja que tu agente lo pruebe con Apidog CLI

Una vez que la divulgación depende de estas llamadas, los cambios silenciosos hacen daño: un proveedor cambia, los costos suben poco a poco, o el campo del veredicto desaparece. Tu agente puede proteger eso con una suite de regresión en Apidog CLI.

Configura la CLI y su skill de agente una vez:

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

Luego dale a tu agente un 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.

El agente lee los esquemas de payload, valida su JSON y luego ejecuta comandos como estos:

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

Cada ejecución gasta saldo real, así que mantén la suite en tres casos con entradas de prueba conocidas y prográmala a diario, no en cada commit. La misma línea apidog run ... -r junit se integra en una canalización; la guía de CI/CD de Apidog CLI tiene ejemplos de GitHub Actions y GitLab. Para configuración específica de agentes, consulta Apidog CLI en Claude Code o Apidog CLI en Codex. El plan gratuito cubre hasta 4 usuarios.

Para terminar

La API de búsqueda de personas de Treg convierte el enriquecimiento de leads en tres llamadas enrutadas: buscar, encontrar correo electrónico, verificar. Comprueba los precios con treg catalog get, limita las llamadas con X-Treg-Route-Max-Cost, verifica cada dirección y protege las llamadas con una ejecución de regresión de Apidog CLI. Para más herramientas de agentes, los mejores servidores MCP para Claude Code y este recorrido de pruebas de API impulsadas por agentes son buenas lecturas a continuación.

Preguntas frecuentes

¿Es gratis la API de búsqueda de personas de Treg? No del todo. Las cuentas nuevas verificadas reciben $1.00 de crédito una vez, los fallos en proveedores que cobran por éxito no cuestan nada, y algunas rutas son públicas y gratuitas (el plan de verificación de correo electrónico listaba un proveedor de $0 en primer lugar el 3 de noviembre de 2026). Todo lo demás se mide por llamada desde un saldo prepago a la tarifa del proveedor.

¿Necesito una cuenta de Apollo o Hunter para usar Treg? No. Treg llama al proveedor con su propia cuenta y te factura por llamada. Si tu equipo ya paga por un proveedor, registra esa clave con Treg y esas llamadas la usarán y no se facturarán.

¿Treg hace conmutación por error entre proveedores? Solo en las herramientas enrutadas treg.*. Recurren al siguiente proveedor ante un error o un fallo, del más barato al más caro, dentro de X-Treg-Route-Max-Cost. Las herramientas directas de proveedor nunca cambian de proveedor por ti.

¿Cómo sé cuánto costó una llamada? Lee el encabezado de respuesta X-Treg-Cost-Micro (micro-USD), o cost_usd a través de MCP. treg balance muestra tu saldo y el gasto reciente.

¿Puedo usar Treg sin Claude Code o Codex? Sí. Usa la CLI desde cualquier shell, llama a https://treg.to/call/<tool-id> por HTTP con X-Treg-Token, o conecta https://treg.to/mcp/ a claude.ai o ChatGPT como conector personalizado.

button