Créditos y uso
Qué acciones consumen uso de IA o créditos, cómo estimar antes de gastar, cómo consultar el saldo y qué errores devuelve quedarse sin saldo.
La mayoría de las operaciones de la API son gratis. Las que llaman a un modelo de IA o a un proveedor externo de datos consumen el saldo del workspace, medido de dos formas: uso de IA y créditos. Esta página dice qué gasta qué, cómo saberlo antes de llamar y qué pasa cuando no alcanza.
Las dos medidas
Uso de IA. Lo consume todo lo que llama a un modelo o a un proveedor de datos: buscar y enriquecer personas, el sourcing, el match score, leer CVs y cada propuesta generada. Se expresa siempre como fracción, de 0 a 1, nunca en dinero, y tiene dos topes:
- El mes: el uso que trae el plan del workspace para el período de facturación. Cuando se agota y el workspace tiene créditos comprados, esos créditos siguen cubriendo el uso.
- La ventana de 5 horas: un tope por persona que arranca con su primer gasto y se repone entero al vencer. Evita que una sola persona consuma el mes en una tarde. Las tareas que ya están corriendo (una corrida de sourcing, una cola de CVs) no se cortan por la ventana: se pregunta al arrancarlas.
En el plan gratuito, las propuestas generadas por IA consumen un cupo de equipo separado, con su propio tope mensual y su propia ventana de 5 horas.
Créditos. Los consume revelar contactos (email laboral, email personal, teléfono). Cada tipo de dato tiene un precio en créditos que depende del plan. El plan trae créditos por mes, y un OWNER puede comprar más desde la app. Revelar se cobra solo por lo que se encuentra: un dato que no aparece no consume créditos.
Qué consume qué
Las acciones de las familias DO y CRM no consumen nada (con la excepción de upload_cv, que es PROVIDER). Las que consumen son las de las familias PROVIDER y GENERATE:
| Acción | Consume | Notas |
|---|---|---|
enrich_contact | Créditos | Solo por cada dato encontrado. Lo ya conocido, buscado hace poco o en búsqueda se saltea sin cobrar. |
search_talent | Uso de IA | Una búsqueda más el enriquecimiento de cada persona de la página que el workspace no había pagado antes. |
load_more_talent | Uso de IA | Igual que search_talent, por cada página siguiente. |
search_talent_preview | Uso de IA | Una sola búsqueda en el proveedor, sin enriquecer a nadie. Mucho más barata que search_talent. |
enrich_profile | Uso de IA | Por cada persona que de verdad hay que traer; las que están al día se saltean. |
run_sourcing | Uso de IA | Cada página de la corrida busca, enriquece y puntúa. Lo acotan targetSize y profileCap. |
continue_sourcing | Uso de IA | Una página más de una corrida. |
run_match_score | Uso de IA | Por cada candidato puntuado. |
upload_cv | Uso de IA | Por cada CV leído; con linkPublicProfile: true, también por cada perfil público que vincula. Un CV que el workspace ya tenía no se cobra. |
create_job_post, write_talent_icp, write_sourcing_criteria, write_screening_criteria, write_evaluation_criteria, generate_interview_questions, generate_answers_from_transcript, generate_scorecard, draft_report | Uso de IA | Las acciones GENERATE: una llamada al modelo cada una. |
Las rutas REST que hacen lo mismo consumen lo mismo: por ejemplo POST /talent/contacts/reveal y /reveal/batch (créditos), POST /talent/searches y /talent/searches/{searchId}/next, POST /talent/profiles/enrich, agregar personas por su LinkedIn, POST /job-posts/{jobPostId}/match-score, las rutas de sourcing que arrancan o avanzan una corrida, POST /talent/pool/cvs/jobs, y las rutas que proponen o generan con IA (…/propose, …/generate, …/draft, …/summary, …/translation). Importar una planilla no consume nada, salvo que pidas vincular los perfiles públicos.
Armar el informe de un candidato sin IA (generate_report) es gratis; lo que cuesta es pedirle a la IA que proponga sus textos (draft_report).
Lo que dice cada respuesta: cost
Toda acción PROVIDER o GENERATE exitosa agrega cost a su respuesta con lo que gastó esa llamada:
{
"data": { "...": "..." },
"links": [],
"cost": {
"aiUsagePct": 0.0125,
"teamUsagePct": 0,
"credits": 0,
"billedLater": false
}
}| Campo | Qué es |
|---|---|
aiUsagePct | La fracción del uso de IA del mes que consumió (0 a 1). |
teamUsagePct | La fracción del cupo de equipo del mes que consumió (0 a 1). |
credits | Los créditos que consumió. |
billedLater | true cuando parte del gasto se cobra después, mientras la tarea sigue en segundo plano (una corrida de sourcing, una cola de CVs). |
Si el gasto no se pudo leer, cost no aparece: nunca vuelve un 0 inventado.
Estimar antes de gastar
- Revelar contactos:
POST /talent/contacts/reveal/estimaterecibe el mismo cuerpo que el lote (profileIdsolonglistId, ytypes) y dice cuánto costaría sin gastar nada: cuántos datos hay que comprar, cuántos ya se tienen o se están buscando, los créditos que se descontarían si se encuentra todo (workspaceCredits) y si alcanzan (fitsCredit).
curl -X POST https://app.reclee.com/api/v1/talent/contacts/reveal/estimate \
-H "Authorization: Bearer $RECLEE_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "longlistId": "9e4d2c7a-3b1f-4a8e-b6d5-0c2a4e6f8b17", "types": ["EMAIL_WORK"] }'{
"profiles": 42,
"requested": 42,
"toBuy": 35,
"alreadyHave": 4,
"alreadySearched": 2,
"inFlight": 1,
"withoutLinkedin": 0,
"workspaceCredits": 175,
"fitsInBalance": true,
"balanceUnchecked": false,
"fitsCredit": true,
"exceedsCap": false
}- Uso de IA:
GET /billing/usage-standingdice, para la persona de la key, qué le contestaría el sistema a su próxima llamada que gasta:aiBlock(búsquedas, enriquecimientos, sourcing),scoreBlock(match score) yassistBlock(propuestas de IA).nullsignifica que pasaría; un código (USAGE_WINDOW,USAGE_EXHAUSTED…) es el402que recibirías. - Acotar el gasto:
run_sourcingaceptatargetSizeyprofileCap;search_talent_previewmira una página sin enriquecer a nadie antes de pagarsearch_talent;enrich_profileyenrich_contactsaltean solos lo que no hace falta comprar. - Las negativas previas no cuestan: códigos como
NOTHING_TO_ENRICH,NOTHING_TO_REVEAL,NOTHING_TO_SCOREoNOTHING_CHANGEDse contestan antes de llamar a nadie.
Consultar el saldo
| Ruta | Quién | Qué devuelve |
|---|---|---|
GET /billing/usage-standing | Cualquier rol | Dónde está parado el workspace para ti: plan, uso del mes y de tu ventana como fracción, créditos disponibles, precio de cada tipo de contacto y qué bloquearía tu próxima llamada. Sin montos. |
GET /billing/credit-movements | OWNER | Los movimientos de créditos, del más nuevo al más viejo, paginados (hasta 100 por página). |
GET /billing/credits | Cualquier rol | Los paquetes de créditos a la venta (no el saldo). |
GET /billing/entitlements | OWNER | El detalle completo del plan y su consumo. |
Por MCP, la tool get_usage devuelve un resumen de usage-standing.
{
"plan": "PRO",
"position": "PAID",
"metered": true,
"periodEnd": "2026-11-01T00:00:00+00:00",
"aiUsedPct": 0.42,
"teamUsedPct": 0,
"window": { "usedPct": 0.18, "endsAt": "2026-10-22T19:40:00+00:00" },
"teamWindow": { "usedPct": 0, "endsAt": null },
"aiBlock": null,
"scoreBlock": null,
"assistBlock": null,
"creditsLeft": 1240,
"revealCredits": { "EMAIL_WORK": 5, "EMAIL_PERSONAL": 5, "PHONE": 10 },
"spendingCredit": false
}(Extracto; los precios de revealCredits son de ejemplo y dependen del plan.)
Los movimientos de créditos tienen un kind: PURCHASE (compra), REVEAL (contacto revelado), GRANT y REFERRAL (créditos otorgados), REFUND (devolución), CHARGEBACK y CHARGEBACK_WON (disputas de pago) y AI_USAGE (un día de uso de IA pagado con créditos comprados). Un gasto es negativo.
Errores por saldo
Quedarse sin saldo contesta 402 Payment Required con el detalle de qué se agotó, cuándo vuelve y qué lo destraba:
{
"error": "USAGE_EXHAUSTED",
"limit": "MONTH",
"usedPct": 1,
"periodEnd": "2026-11-01T00:00:00Z",
"unlockedBy": ["BUY_CREDITS", "UPGRADE_PLAN", "WAIT"],
"position": "PAID",
"billingUrl": "https://app.reclee.com/settings/billing"
}| Código | Qué se agotó | limit | Trae |
|---|---|---|---|
USAGE_WINDOW | Tu uso de IA de las últimas 5 horas. | WINDOW | usedPct, resetsAt |
USAGE_EXHAUSTED | El uso de IA del mes, sin créditos comprados que lo cubran. | MONTH | usedPct, periodEnd |
TEAM_WINDOW | Tu cupo de equipo de las últimas 5 horas. | WINDOW | usedPct, resetsAt |
TEAM_USAGE_EXHAUSTED | El cupo de equipo del mes. | MONTH | usedPct, periodEnd |
NO_CREDITS | Los créditos para revelar contactos. | CREDITS | creditsLeft, revealCredits, periodEnd |
SEAT_LIMIT | Los asientos del plan. | SEATS | seats, maxSeats |
PLAN_REQUIRED, FREE_WORKSPACE_LIMIT | La función no está en el plan. | PLAN | |
PAYMENT_FAILED | La tarjeta fue rechazada. | PAYMENT |
Todos traen además unlockedBy (qué lo destraba, en orden: WAIT, START_TRIAL, CHOOSE_PLAN, UPGRADE_PLAN, BUY_CREDITS, ASSIGN_SEAT, UPDATE_PAYMENT_METHOD), position (FREE, TRIAL, PAID o CHURNED), billingUrl (la pantalla de facturación de la app) y, sin plan pago, trialAvailable. Un campo que no se pudo leer no aparece: el código solo ya alcanza.
Qué hacer:
USAGE_WINDOWyTEAM_WINDOW: espera hastaresetsAty reintenta.USAGE_EXHAUSTED,NO_CREDITS: unOWNERcompra créditos o cambia de plan desde la app; si no, se renueva enperiodEnd. La API no compra:POST /billing/creditscon una API key contesta403 FORBIDDEN.- El resto lo resuelve un
OWNERdesde la facturación de la app.
Otros errores relacionados que no son del saldo del workspace:
| Código | Status | Qué significa |
|---|---|---|
SEAT_REQUIRED | 403 | La operación necesita un rol con asiento. Se contesta antes de mirar el saldo. |
PROVIDER_NO_CREDITS | 503 | La revelación de contactos no está disponible en este momento. No depende de tu plan: avisa a soporte de Reclee. |
INSUFFICIENT_CREDITS | 503 | El proveedor de datos de búsqueda y enriquecimiento no está disponible. A pesar del nombre, no son tus créditos: avisa a soporte de Reclee. |
PROVIDER_UNAVAILABLE | 503 | El proveedor de datos no respondió. Reintenta más tarde. |
RATE_LIMITED | 429 | El proveedor de datos pidió esperar. Trae retryAfterSeconds. |
Una corrida de sourcing que se queda sin uso del mes no se cierra: queda abierta, deja de avanzar y retoma sola cuando vuelve el uso.