Límites de uso
Consultar el plan activo, límites del período y excesos
Cada tenant tiene un plan activo con límites de documentos, fuentes y consultas mensuales. Dos endpoints exponen esta información: uno pensado para lógica de negocio (/subscription, cifras completas incluido el exceso estimado en USD) y otro pensado para UI (/usage, con porcentajes precalculados).
Plan y límites — GET /tenants/me/subscription
curl https://api.kelova.app/tenants/me/subscription \
-H "Authorization: Bearer <token>"{
"plan_id": "pro",
"status": "active",
"monthly_price_usd": 299,
"limits": {
"max_documents": 5000,
"max_queries_month": 10000,
"max_sources": 30
},
"usage": {
"docs_indexed": 3120,
"queries_count": 4870,
"audio_minutes_used": 12
},
"overage": {
"docs": 0,
"queries": 0,
"estimated_usd": 0
},
"current_period_start": "2026-07-01T00:00:00Z",
"current_period_end": "2026-08-01T00:00:00Z",
"trial_ends_at": null
}Uso del período — GET /tenants/me/usage
Pensado para pintar barras de progreso — cada métrica ya trae used, limit y pct calculados.
curl https://api.kelova.app/tenants/me/usage \
-H "Authorization: Bearer <token>"{
"period": "2026-07",
"plan": { "id": "pro", "name": "Pro" },
"docs_indexed": { "used": 3120, "limit": 5000, "pct": 62 },
"queries_month": { "used": 4870, "limit": 10000, "pct": 49 },
"sources": { "used": 18, "limit": 30, "pct": 60 }
}Cómo se aplican los límites
En planes pagos, los excesos de documentos y consultas no bloquean la operación — se registran y se facturan al cierre del período. Hay dos excepciones que sí bloquean con 402: el límite de fuentes en todos los planes (POST /ingest/sources y POST /ingest/sources/upload responden 402 PLAN_LIMIT_REACHED al alcanzar max_sources), y el límite de consultas en el plan Free (los endpoints de query responden 402 al agotar max_queries_month) — ver Errores.
| Recurso | Al exceder el límite |
|---|---|
max_documents | La ingesta continúa; el exceso queda en overage.docs y se factura |
max_queries_month | Planes pagos: las queries siguen respondiendo y el exceso queda en overage.queries. Plan Free: responde 402 y las queries se bloquean hasta el siguiente período o upgrade |
max_sources | Bloquea la creación de fuentes nuevas — 402 PLAN_LIMIT_REACHED |
Frecuencia de sync automático por plan
El plan también determina qué frecuencias de sync automático están disponibles en PUT /ingest/sources/{id}/schedule (ver Fuentes):
| Plan | Frecuencias permitidas |
|---|---|
| Starter | manual, 24h |
| Pro | manual, 6h, 24h |
| Enterprise | manual, 1h, 6h, 24h, weekly |
Pedir una frecuencia no incluida en tu plan responde 402 con el detalle del plan requerido.
Estado del tenant
El campo status en la respuesta de subscription (y en GET /tenants/me, ver Introducción) puede ser active o suspended. Un tenant suspended conserva acceso de lectura completo — puede consultar a sus agentes y ver sus fuentes — pero no puede indexar documentos nuevos, crear fuentes, ejecutar syncs, ni crear agentes o endpoints MCP nuevos.