Reclee

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ónConsumeNotas
enrich_contactCréditosSolo por cada dato encontrado. Lo ya conocido, buscado hace poco o en búsqueda se saltea sin cobrar.
search_talentUso de IAUna búsqueda más el enriquecimiento de cada persona de la página que el workspace no había pagado antes.
load_more_talentUso de IAIgual que search_talent, por cada página siguiente.
search_talent_previewUso de IAUna sola búsqueda en el proveedor, sin enriquecer a nadie. Mucho más barata que search_talent.
enrich_profileUso de IAPor cada persona que de verdad hay que traer; las que están al día se saltean.
run_sourcingUso de IACada página de la corrida busca, enriquece y puntúa. Lo acotan targetSize y profileCap.
continue_sourcingUso de IAUna página más de una corrida.
run_match_scoreUso de IAPor cada candidato puntuado.
upload_cvUso de IAPor 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_reportUso de IALas 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
  }
}
CampoQué es
aiUsagePctLa fracción del uso de IA del mes que consumió (0 a 1).
teamUsagePctLa fracción del cupo de equipo del mes que consumió (0 a 1).
creditsLos créditos que consumió.
billedLatertrue 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/estimate recibe el mismo cuerpo que el lote (profileIds o longlistId, y types) 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-standing dice, 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) y assistBlock (propuestas de IA). null significa que pasaría; un código (USAGE_WINDOW, USAGE_EXHAUSTED…) es el 402 que recibirías.
  • Acotar el gasto: run_sourcing acepta targetSize y profileCap; search_talent_preview mira una página sin enriquecer a nadie antes de pagar search_talent; enrich_profile y enrich_contact saltean solos lo que no hace falta comprar.
  • Las negativas previas no cuestan: códigos como NOTHING_TO_ENRICH, NOTHING_TO_REVEAL, NOTHING_TO_SCORE o NOTHING_CHANGED se contestan antes de llamar a nadie.

Consultar el saldo

RutaQuiénQué devuelve
GET /billing/usage-standingCualquier rolDó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-movementsOWNERLos movimientos de créditos, del más nuevo al más viejo, paginados (hasta 100 por página).
GET /billing/creditsCualquier rolLos paquetes de créditos a la venta (no el saldo).
GET /billing/entitlementsOWNEREl 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ódigoQué se agotólimitTrae
USAGE_WINDOWTu uso de IA de las últimas 5 horas.WINDOWusedPct, resetsAt
USAGE_EXHAUSTEDEl uso de IA del mes, sin créditos comprados que lo cubran.MONTHusedPct, periodEnd
TEAM_WINDOWTu cupo de equipo de las últimas 5 horas.WINDOWusedPct, resetsAt
TEAM_USAGE_EXHAUSTEDEl cupo de equipo del mes.MONTHusedPct, periodEnd
NO_CREDITSLos créditos para revelar contactos.CREDITScreditsLeft, revealCredits, periodEnd
SEAT_LIMITLos asientos del plan.SEATSseats, maxSeats
PLAN_REQUIRED, FREE_WORKSPACE_LIMITLa función no está en el plan.PLAN
PAYMENT_FAILEDLa 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_WINDOW y TEAM_WINDOW: espera hasta resetsAt y reintenta.
  • USAGE_EXHAUSTED, NO_CREDITS: un OWNER compra créditos o cambia de plan desde la app; si no, se renueva en periodEnd. La API no compra: POST /billing/credits con una API key contesta 403 FORBIDDEN.
  • El resto lo resuelve un OWNER desde la facturación de la app.

Otros errores relacionados que no son del saldo del workspace:

CódigoStatusQué significa
SEAT_REQUIRED403La operación necesita un rol con asiento. Se contesta antes de mirar el saldo.
PROVIDER_NO_CREDITS503La revelación de contactos no está disponible en este momento. No depende de tu plan: avisa a soporte de Reclee.
INSUFFICIENT_CREDITS503El 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_UNAVAILABLE503El proveedor de datos no respondió. Reintenta más tarde.
RATE_LIMITED429El 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.

En esta página