Subcuentas: claves, límites y uso por cliente final

Si usas querying.ai dentro de tu propio producto, crea una subcuenta por cliente. Una subcuenta tiene sus propias claves de API, límites, tareas, lotes y monitores. Sus créditos salen de tu saldo, y los endpoints de uso te indican cuánto cobrar a cada cliente.

Cómo funciona una subcuenta

Sus propias claves y resultados. Una clave de subcuenta envía y lee tareas, lotes y monitores como cualquier otra clave, y solo ve su propio trabajo. Una tarea creada con la clave de Acme devuelve 404 a la clave de Globex y a tus propias claves.
Tus créditos. Sus tareas se cobran de tu saldo. Una subcuenta no tiene saldo, así que sus claves reciben 403 SUB_ACCOUNT_FORBIDDEN de GET /v1/credits y GET /v1/usage.
Tu capacidad. El límite de concurrencia de tu plan o contrato cubre tus propias tareas y las de todas las subcuentas en conjunto, así que las subcuentas nunca añaden capacidad. GET /v1/async/status cuenta esa cola compartida con tu clave, y la clave de una subcuenta recibe 403 SUB_ACCOUNT_FORBIDDEN.
Tus límites de monitores. El límite monitors de GET /v1/monitors/capabilities cuenta tus monitores y los de todas las subcuentas en conjunto, y los límites prompts y tasksPerRun se aplican a los monitores de una subcuenta igual que a los tuyos.
Sus propios límites. monthlyCreditLimit limita lo que se le puede cobrar en un mes natural UTC. concurrencyLimit limita sus tareas en cola y en ejecución dentro de tu límite. Ambos son opcionales.
Un solo nivel. Una subcuenta no puede tener subcuentas. Los correos de alerta de sus monitores van a los administradores de tu cuenta.

Quién puede gestionar subcuentas

Llama a los endpoints /v1/sub-accounts con una de tus propias claves de API sin restricción de motores ni límite diario de créditos. Cualquier otra clave recibe 403 SUB_ACCOUNT_FORBIDDEN, porque una clave restringida podría emitir claves sin sus propias restricciones. Las claves de una subcuenta reciben el mismo error.

{
  "success": false,
  "error": {
    "code": "SUB_ACCOUNT_FORBIDDEN",
    "message": "Managing sub-accounts needs an API key without an engine scope or a daily credit limit",
    "timestamp": "2026-10-19T09:00:00.000Z"
  }
}

Crear una subcuenta y una clave

curl -X POST https://api.querying.ai/v1/sub-accounts \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme", "externalId": "cust_acme", "monthlyCreditLimit": 200000, "concurrencyLimit": 50}'

La respuesta es 201:

{
  "success": true,
  "data": {
    "id": "0199d2a4-5b10-7000-8000-000000000001",
    "name": "Acme",
    "externalId": "cust_acme",
    "status": "active",
    "monthlyCreditLimit": 200000,
    "concurrencyLimit": 50,
    "createdAt": "2026-10-09T09:00:00.000Z",
    "suspendedAt": null,
    "usage": { "month": "2026-10", "credits": 0, "tasks": 0, "reservedCredits": 0 }
  }
}

Campo	Obligatorio	Descripción
`name`	Sí	De 1 a 128 caracteres.
`externalId`	No	Tu id para este cliente, de 1 a 128 caracteres, único entre tus subcuentas. Crear otra con el mismo valor devuelve `409 SUB_ACCOUNT_EXISTS`, así que un reintento nunca crea un duplicado. Encuentra la existente con `GET /v1/sub-accounts?externalId=cust_acme`.
`monthlyCreditLimit`	No	De 0,01 a 20.000.000 créditos, con dos decimales como máximo. Omítelo o envía `null` para no poner límite.
`concurrencyLimit`	No	Entero de 1 a 100.000. Omítelo o envía `null` para no poner límite.

Cualquier otro campo devuelve 400 VALIDATION_ERROR, así que un límite mal escrito nunca deja a un cliente sin límite. Después, emite una clave para la subcuenta:

curl -X POST https://api.querying.ai/v1/sub-accounts/$SUB_ACCOUNT_ID/keys \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "production", "allowedTaskTypes": ["CHATGPT", "GEMINI"]}'

{
  "success": true,
  "data": {
    "id": "b7e4c1a2-...",
    "name": "production",
    "keyPrefix": "vt_3f9a1c2b",
    "createdAt": "2026-10-09T09:01:00.000Z",
    "allowedTaskTypes": ["CHATGPT", "GEMINI"],
    "dailyCreditLimit": null,
    "expiresAt": null,
    "key": "vt_3f9a1c2b..."
  }
}

key aparece solo en esta respuesta. Guárdala ahora; no se vuelve a mostrar.

Una clave admite los mismos ajustes opcionales que una clave del dashboard: name (de 1 a 64 caracteres, por defecto default), allowedTaskTypes, dailyCreditLimit y expiresAt (de 5 minutos a 2 años en el futuro). No envíes cuerpo para una clave sin restricciones. Una subcuenta puede tener hasta 5 claves activas; las revocadas y caducadas no cuentan. Una sexta devuelve 409 KEY_LIMIT. Revoca una antes. La clave de tu cliente funciona en todos los endpoints como cualquier otra:

curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $ACME_KEY" \
  -H "Content-Type: application/json" \
  -d '{"taskType": "CHATGPT", "payload": {"prompt": "best project management software", "country": "US"}}'

Gestionar claves

GET /v1/sub-accounts/{id}/keys lista todas las claves que ha tenido la subcuenta, de la más reciente a la más antigua, incluidas las revocadas y caducadas. Revisa revokedAt y expiresAt para encontrar las claves activas.

{
  "success": true,
  "data": {
    "keys": [
      {
        "id": "b7e4c1a2-...",
        "name": "production",
        "keyPrefix": "vt_3f9a1c2b",
        "createdAt": "2026-10-09T09:01:00.000Z",
        "revokedAt": null,
        "lastUsedAt": "2026-10-19T08:58:12.000Z",
        "allowedTaskTypes": ["CHATGPT", "GEMINI"],
        "dailyCreditLimit": null,
        "expiresAt": null
      },
      {
        "id": "4d2a9e10-...",
        "name": "staging",
        "keyPrefix": "vt_8c01d5e7",
        "createdAt": "2026-10-01T12:00:00.000Z",
        "revokedAt": "2026-10-09T09:02:00.000Z",
        "lastUsedAt": "2026-10-08T17:40:03.000Z",
        "allowedTaskTypes": [],
        "dailyCreditLimit": null,
        "expiresAt": null
      }
    ]
  }
}

DELETE /v1/sub-accounts/{id}/keys/{keyId} revoca una clave y devuelve {"success": true, "data": {"revoked": "<keyId>"}}. Una clave ya revocada, o que no pertenece a la subcuenta, devuelve 404 NOT_FOUND.

Límites

Límite	Cuenta	Al alcanzarlo
`monthlyCreditLimit`	Los cargos de la subcuenta en este mes UTC, más los créditos que retienen sus tareas aún en ejecución	`429 SUB_ACCOUNT_CREDIT_LIMIT`
`concurrencyLimit`	Las tareas en cola y en ejecución de la subcuenta	`429 PLAN_CONCURRENCY_LIMIT`, `details.source: "sub_account"`
El límite de tu plan o contrato	Tus tareas y las de todas las subcuentas	`429 PLAN_CONCURRENCY_LIMIT`, `details.source: "plan"` o `"contract"`
Tu saldo	Todos	`402 INSUFFICIENT_CREDITS`

Solo se rechaza la subcuenta que alcanzó su propio límite; tus demás clientes siguen funcionando. Un límite ampliado se aplica a la siguiente solicitud.

{
  "success": false,
  "error": {
    "code": "SUB_ACCOUNT_CREDIT_LIMIT",
    "message": "Sub-account monthly credit limit 200000 would be exceeded (199998 used, 3 needed)",
    "details": { "limit": 200000, "used": 199998, "needed": 3, "retryAfterSec": 1814400 },
    "timestamp": "2026-10-09T09:00:00.000Z"
  }
}

retryAfterSec cuenta hasta el inicio del siguiente mes UTC, cuando el cómputo mensual vuelve a empezar. Consulta Créditos y límites para los límites de toda la cuenta.

Consultar una subcuenta ahora

GET /v1/sub-accounts/{id} devuelve la subcuenta con el uso de este mes y activeTasks, el número de sus tareas en cola o en ejecución en este momento. Compáralo con concurrencyLimit para ver lo cerca que está el cliente de su límite.

{
  "success": true,
  "data": {
    "id": "0199d2a4-5b10-7000-8000-000000000001",
    "name": "Acme",
    "externalId": "cust_acme",
    "status": "active",
    "monthlyCreditLimit": 200000,
    "concurrencyLimit": 50,
    "createdAt": "2026-10-09T09:00:00.000Z",
    "suspendedAt": null,
    "usage": { "month": "2026-10", "credits": 48211.5, "tasks": 39870, "reservedCredits": 37.5 },
    "activeTasks": 31
  }
}

Los valores de arriba son un ejemplo. En usage, credits y tasks son lo cobrado en este mes UTC, y reservedCredits es lo retenido por tareas aún en ejecución.

Uso y facturación

Cada cargo aparece también en tu propio libro de facturación; estos endpoints lo dividen por cliente. Las tareas fallidas nunca se cobran ni se cuentan. Las cantidades de créditos llevan hasta dos decimales.

GET /v1/sub-accounts lista tus subcuentas, de la más antigua a la más reciente, cada una con el usage de este mes. Pagina con limit (100 por defecto, 1.000 como máximo) y devuelve nextCursor como cursor.
GET /v1/sub-accounts/usage suma cada subcuenta en un rango de fechas UTC.
GET /v1/sub-accounts/{id}/usage devuelve los cargos de una subcuenta por día y motor.

Ambos endpoints de uso aceptan from y to como YYYY-MM-DD, inclusivos. from es por defecto el día 1 del mes UTC actual y to hoy; un rango abarca como máximo 366 días.

Todas las subcuentas

curl "https://api.querying.ai/v1/sub-accounts/usage?from=2026-10-01&to=2026-10-31" \
  -H "Authorization: Bearer $QUERYING_API_KEY"

Por ejemplo:

{
  "success": true,
  "data": {
    "from": "2026-10-01",
    "to": "2026-10-31",
    "credits": 184200,
    "tasks": 61400,
    "subAccounts": [
      { "id": "0199d2a4-5b10-7000-8000-000000000001", "name": "Acme", "externalId": "cust_acme", "credits": 150000, "tasks": 50000 },
      { "id": "0199d2a4-6c20-7000-8000-000000000002", "name": "Globex", "externalId": "cust_globex", "credits": 34200, "tasks": 11400 }
    ]
  }
}

Las subcuentas aparecen de mayor a menor. Una subcuenta sin cargos en el rango se deja fuera.

Una subcuenta

curl "https://api.querying.ai/v1/sub-accounts/$SUB_ACCOUNT_ID/usage?from=2026-10-08&to=2026-10-09" \
  -H "Authorization: Bearer $QUERYING_API_KEY"

Por ejemplo:

{
  "success": true,
  "data": {
    "id": "0199d2a4-5b10-7000-8000-000000000001",
    "from": "2026-10-08",
    "to": "2026-10-09",
    "credits": 3062.5,
    "tasks": 2950,
    "days": [
      { "date": "2026-10-08", "taskType": "CHATGPT", "credits": 1500, "tasks": 1500 },
      { "date": "2026-10-08", "taskType": "GEMINI", "credits": 312.5, "tasks": 250 },
      { "date": "2026-10-08", "taskType": "OTHER", "credits": 50, "tasks": 0 },
      { "date": "2026-10-09", "taskType": "CHATGPT", "credits": 1200, "tasks": 1200 }
    ]
  }
}

credits y tasks en el nivel superior son los totales de days.
days tiene una fila por fecha UTC y motor con algún cargo, ordenadas por fecha y después por taskType. Los días sin cargos no tienen fila.
taskType: "OTHER" es un cargo que no es una tarea, como la lectura de competidores de un monitor. Suma créditos pero no tasks.

Suspender y reanudar

curl -X PATCH https://api.querying.ai/v1/sub-accounts/$SUB_ACCOUNT_ID \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "suspended"}'

Sus claves devuelven 401 en cinco segundos.
Sus monitores dejan de ejecutarse y los elementos de lote que no han empezado terminan como API_KEY_INACTIVE.
Las tareas ya en cola o en ejecución terminan y se cobran.

{"status": "active"} restaura sus claves y monitores. Cada monitor se ejecuta una vez al volver en lugar de recuperar las ejecuciones perdidas. El mismo PATCH cambia name, externalId, monthlyCreditLimit y concurrencyLimit; null elimina un límite o el externalId. Una subcuenta no se puede eliminar; suspéndela.

Errores

Estado	Código	Causa
`400`	`VALIDATION_ERROR`	JSON no válido, un campo desconocido, un valor fuera de rango o un rango de uso incorrecto.
`403`	`SUB_ACCOUNT_FORBIDDEN`	La clave tiene restricción de motores o límite diario de créditos, o pertenece a una subcuenta.
`404`	`NOT_FOUND`	Ninguna de tus subcuentas tiene ese id, o no hay ninguna clave activa con ese id.
`409`	`SUB_ACCOUNT_EXISTS`	Otra subcuenta ya tiene ese `externalId`.
`409`	`KEY_LIMIT`	La subcuenta ya tiene 5 claves activas.

Endpoints

Método y ruta	Uso
`POST /v1/sub-accounts`	Crear
`GET /v1/sub-accounts`	Listar, con `externalId`, `limit` y `cursor`
`GET /v1/sub-accounts/{id}`	Una subcuenta, con `activeTasks`
`PATCH /v1/sub-accounts/{id}`	Cambiar ajustes, suspender o reanudar
`GET /v1/sub-accounts/usage`	Totales por subcuenta
`GET /v1/sub-accounts/{id}/usage`	Una subcuenta por día y motor
`GET /v1/sub-accounts/{id}/keys`	Listar sus claves, incluidas las revocadas y caducadas
`POST /v1/sub-accounts/{id}/keys`	Emitir una clave
`DELETE /v1/sub-accounts/{id}/keys/{keyId}`	Revocar una clave

Primeros pasos

Conceptos clave

Motores de respuesta

Búsqueda y datos web

Opciones de solicitud

Investigación

Monitorización GEO

Cuenta y datos

Subcuentas: claves, límites y uso por cliente final

Cómo funciona una subcuenta

Quién puede gestionar subcuentas

Crear una subcuenta y una clave

Gestionar claves

Límites

Consultar una subcuenta ahora

Uso y facturación

Todas las subcuentas

Una subcuenta

Suspender y reanudar

Errores

Endpoints

​Cómo funciona una subcuenta

​Quién puede gestionar subcuentas

​Crear una subcuenta y una clave

​Gestionar claves

​Límites

​Consultar una subcuenta ahora

​Uso y facturación

​Todas las subcuentas

​Una subcuenta

​Suspender y reanudar

​Errores

​Endpoints

Cómo funciona una subcuenta

Quién puede gestionar subcuentas

Crear una subcuenta y una clave

Gestionar claves

Límites

Consultar una subcuenta ahora

Uso y facturación

Todas las subcuentas

Una subcuenta

Suspender y reanudar

Errores

Endpoints