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 conectadas y consultas mensuales. Un documento es 1 archivo subido (PDF, Word, Excel…) o 1 página web indexada — los bloques internos en que Kelova divide cada documento para la búsqueda ("bloques de información") no cuentan contra ningún límite. El límite de fuentes (max_sources) cuenta solo fuentes conectadas con sincronización (sitio web, Google Drive, OneDrive, Notion…): los archivos que subes directamente no ocupan ese cupo — los gobierna max_documents — y una fuente cuyo sync falló sin llegar a indexar nada tampoco cuenta. 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": 149,
"limits": {
"max_documents": 750,
"max_queries_month": 3000,
"max_sources": 10,
"max_doc_size_mb": 30
},
"usage": {
"docs_indexed": 312,
"queries_count": 1870,
"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": 312, "limit": 750, "pct": 42 },
"queries_month": { "used": 1870, "limit": 3000, "pct": 62 },
"sources": { "used": 2, "limit": 10, "pct": 20 }
}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 tres casos que sí bloquean: el límite de fuentes conectadas (POST /ingest/sources responde 402 SOURCE_LIMIT_REACHED al alcanzar max_sources — solo aplica a conectores con sync; subir archivos nunca choca con este límite), el límite de documentos en el plan Free (POST /ingest/sources/upload responde 402 PLAN_LIMIT_REACHED al llegar a max_documents), 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 | Planes pagos: la ingesta continúa; el exceso queda en overage.docs y se factura a $0.10 por archivo adicional. Plan Free: POST /ingest/sources/upload responde 402 hasta liberar espacio o hacer upgrade |
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 conectadas nuevas — 402 SOURCE_LIMIT_REACHED. Los archivos subidos no cuentan, y una fuente en error que nunca indexó nada tampoco. Registrar un sitio web cuya URL ya existe en tu espacio responde 409 apuntando a la fuente existente |
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.