> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Da a cada uno de tus clientes sus propias claves de API, límite de créditos y límite de concurrencia, mantén sus resultados separados y consulta lo que usó cada uno. Tú recibes una sola factura.

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.

```json theme={"theme":"css-variables"}
{
  "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

```bash theme={"theme":"css-variables"}
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`:

```json theme={"theme":"css-variables"}
{
  "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:

```bash theme={"theme":"css-variables"}
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"]}'
```

```json theme={"theme":"css-variables"}
{
  "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..."
  }
}
```

> [!WARNING]
>
> `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:

```bash theme={"theme":"css-variables"}
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.

```json theme={"theme":"css-variables"}
{
  "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.

```json theme={"theme":"css-variables"}
{
  "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](/es/concepts/credits-and-limits.md) 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.

```json theme={"theme":"css-variables"}
{
  "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

```bash theme={"theme":"css-variables"}
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:

```json theme={"theme":"css-variables"}
{
  "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

```bash theme={"theme":"css-variables"}
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:

```json theme={"theme":"css-variables"}
{
  "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](/es/monitors.md#coste-y-calendario) de un monitor. Suma créditos pero no `tasks`.

## Suspender y reanudar

```bash theme={"theme":"css-variables"}
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`](/es/api-reference/sub-accounts/create-sub-account) | Crear |
| [`GET /v1/sub-accounts`](/es/api-reference/sub-accounts/list-sub-accounts) | Listar, con `externalId`, `limit` y `cursor` |
| [`GET /v1/sub-accounts/{id}`](/es/api-reference/sub-accounts/get-sub-account) | Una subcuenta, con `activeTasks` |
| [`PATCH /v1/sub-accounts/{id}`](/es/api-reference/sub-accounts/update-sub-account) | Cambiar ajustes, suspender o reanudar |
| [`GET /v1/sub-accounts/usage`](/es/api-reference/sub-accounts/list-usage) | Totales por subcuenta |
| [`GET /v1/sub-accounts/{id}/usage`](/es/api-reference/sub-accounts/get-usage) | Una subcuenta por día y motor |
| [`GET /v1/sub-accounts/{id}/keys`](/es/api-reference/sub-accounts/list-keys) | Listar sus claves, incluidas las revocadas y caducadas |
| [`POST /v1/sub-accounts/{id}/keys`](/es/api-reference/sub-accounts/issue-key) | Emitir una clave |
| [`DELETE /v1/sub-accounts/{id}/keys/{keyId}`](/es/api-reference/sub-accounts/revoke-key) | Revocar una clave |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.