> ## 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.

# Subcontas: chaves, limites e uso por cliente final

> Dê a cada um dos seus clientes suas próprias chaves de API, limite de créditos e limite de concorrência, mantenha os resultados separados e consulte o uso de cada um. Você recebe uma única fatura.

Se você usa o querying.ai dentro do seu próprio produto, crie uma subconta para cada cliente. Uma subconta tem
suas próprias chaves de API, limites, tarefas, lotes e monitores. Os créditos saem do seu saldo, e os endpoints
de uso mostram quanto cobrar de cada cliente.

## Como uma subconta funciona

* **Chaves e resultados próprios.** Uma chave de subconta envia e lê tarefas, lotes e monitores como qualquer
  outra chave e só vê o próprio trabalho. Uma tarefa criada com a chave da Acme retorna `404` para a chave da
  Globex e para as suas próprias chaves.
* **Seus créditos.** As tarefas dela são cobradas do seu saldo. Uma subconta não tem saldo, então as
  chaves dela recebem `403 SUB_ACCOUNT_FORBIDDEN` em `GET /v1/credits` e `GET /v1/usage`.
* **Sua capacidade.** O limite de concorrência do seu plano ou contrato cobre as suas tarefas e as de todas as
  subcontas juntas, então subcontas nunca adicionam capacidade. `GET /v1/async/status` conta essa fila
  compartilhada com a sua chave, e a chave de uma subconta recebe `403 SUB_ACCOUNT_FORBIDDEN` nele.
* **Seus limites de monitores.** O limite `monitors` de `GET /v1/monitors/capabilities` conta os seus monitores
  e os de todas as subcontas juntos, e os limites `prompts` e `tasksPerRun` valem para os monitores de uma
  subconta como valem para os seus.
* **Limites próprios.** `monthlyCreditLimit` limita quanto pode ser cobrado dela em um mês civil UTC.
  `concurrencyLimit` limita as tarefas na fila e em execução dela dentro do seu limite. Ambos são opcionais.
* **Um único nível.** Uma subconta não pode ter subcontas. Os e-mails de alerta dos monitores dela vão para os
  administradores da sua conta.

## Quem pode gerenciar subcontas

Chame os endpoints `/v1/sub-accounts` com uma das suas próprias chaves de API, sem escopo de mecanismo e sem
limite diário de créditos. Qualquer outra chave recebe `403 SUB_ACCOUNT_FORBIDDEN`, porque, do contrário, uma
chave restrita poderia emitir chaves sem as suas restrições. As chaves da própria subconta recebem o mesmo erro.

```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"
  }
}
```

## Crie uma subconta e uma chave

```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}'
```

A resposta é `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 | Obrigatório | Descrição |
| - | - | - |
| `name` | Sim | De 1 a 128 caracteres. |
| `externalId` | Não | O seu id para este cliente, de 1 a 128 caracteres, único entre as suas subcontas. Criar outra com o mesmo valor retorna `409 SUB_ACCOUNT_EXISTS`, então uma nova tentativa nunca cria duplicata. Encontre a existente com `GET /v1/sub-accounts?externalId=cust_acme`. |
| `monthlyCreditLimit` | Não | De 0,01 a 20.000.000 créditos, com no máximo duas casas decimais. Omita ou envie `null` para não ter limite. |
| `concurrencyLimit` | Não | Inteiro de 1 a 100.000. Omita ou envie `null` para não ter limite. |

Qualquer outro campo retorna `400 VALIDATION_ERROR`, então um limite escrito errado nunca deixa um cliente sem
limite.

Depois, emita uma chave para a subconta:

```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 somente nesta resposta. Guarde-a agora; ela nunca é mostrada de novo.

Uma chave aceita as mesmas configurações opcionais de uma chave do painel: `name` (de 1 a 64 caracteres, padrão
`default`), `allowedTaskTypes`, `dailyCreditLimit` e `expiresAt` (de 5 minutos a 2 anos à frente). Não envie
corpo para uma chave sem restrições.

Uma subconta pode ter até 5 chaves ativas; chaves revogadas e expiradas não contam. Uma sexta retorna
`409 KEY_LIMIT`. Revogue uma antes.

A chave do seu cliente funciona em todos os endpoints como qualquer outra:

```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"}}'
```

## Gerencie as chaves

`GET /v1/sub-accounts/{id}/keys` lista todas as chaves que a subconta já teve, da mais recente para a mais
antiga, incluindo as revogadas e expiradas. Confira `revokedAt` e `expiresAt` para encontrar as chaves ativas.

```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}` revoga uma chave e retorna
`{"success": true, "data": {"revoked": "<keyId>"}}`. Uma chave já revogada, ou que não é da subconta, retorna
`404 NOT_FOUND`.

## Limites

| Limite | Conta | Ao atingir |
| - | - | - |
| `monthlyCreditLimit` | As cobranças da subconta neste mês UTC, mais os créditos reservados por tarefas dela ainda em execução | `429 SUB_ACCOUNT_CREDIT_LIMIT` |
| `concurrencyLimit` | As tarefas na fila e em execução da subconta | `429 PLAN_CONCURRENCY_LIMIT`, `details.source: "sub_account"` |
| O limite do seu plano ou contrato | As suas tarefas e as de todas as subcontas | `429 PLAN_CONCURRENCY_LIMIT`, `details.source: "plan"` ou `"contract"` |
| Seu saldo | Todos | `402 INSUFFICIENT_CREDITS` |

Só a subconta que atingiu o próprio limite é recusada; os seus outros clientes continuam rodando. Um limite
ampliado vale a partir da próxima requisição.

```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` conta até o início do próximo mês UTC, quando a contagem mensal recomeça. Veja
[Créditos e limites](/pt/concepts/credits-and-limits.md) para os limites da conta como um todo.

## Consulte uma subconta agora

`GET /v1/sub-accounts/{id}` retorna a subconta com o uso deste mês e `activeTasks`, o número de tarefas dela na
fila ou em execução neste momento. Compare com `concurrencyLimit` para ver o quanto o cliente está perto do
limite.

```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
  }
}
```

Os valores acima são um exemplo. Em `usage`, `credits` e `tasks` são o que foi cobrado neste mês UTC, e
`reservedCredits` é o que está reservado por tarefas ainda em execução.

## Uso e cobrança

Toda cobrança também aparece no seu próprio extrato de cobrança; estes endpoints a dividem por cliente. Tarefas
que falham nunca são cobradas nem contadas. Os valores em créditos têm até duas casas decimais.

* `GET /v1/sub-accounts` lista as suas subcontas, da mais antiga para a mais nova, cada uma com o `usage` deste
  mês. Pagine com `limit` (padrão 100, no máximo 1.000) e envie `nextCursor` de volta como `cursor`.
* `GET /v1/sub-accounts/usage` soma cada subconta em um intervalo de datas UTC.
* `GET /v1/sub-accounts/{id}/usage` traz as cobranças de uma subconta por dia e mecanismo.

Os dois endpoints de uso aceitam `from` e `to` como `YYYY-MM-DD`, inclusivos. `from` é por padrão o dia 1º do
mês UTC atual e `to` é hoje; um intervalo abrange no máximo 366 dias.

### Todas as subcontas

```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 exemplo:

```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 }
    ]
  }
}
```

As subcontas aparecem da maior para a menor. Uma subconta sem cobranças no intervalo fica de fora.

### Uma subconta

```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 exemplo:

```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` e `tasks` no nível superior são os totais de `days`.
* `days` tem uma linha por data UTC e mecanismo com cobrança, ordenada por data e depois por `taskType`. Dias
  sem cobranças não têm linha.
* `taskType: "OTHER"` é uma cobrança que não é uma tarefa, como a
  [leitura de concorrentes](/pt/monitors.md#custo-e-agenda) de um monitor. Soma créditos, mas não `tasks`.

## Suspender e reativar

```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"}'
```

* As chaves dela passam a retornar `401` em até cinco segundos.
* Os monitores dela param de rodar, e os itens de lote que ainda não começaram terminam como
  `API_KEY_INACTIVE`.
* Tarefas já na fila ou em execução terminam e são cobradas.

`{"status": "active"}` restaura as chaves e os monitores. Cada monitor roda uma vez ao voltar, em vez de
recuperar as execuções perdidas. O mesmo `PATCH` altera `name`, `externalId`, `monthlyCreditLimit` e
`concurrencyLimit`; `null` remove um limite ou o `externalId`. Uma subconta não pode ser excluída; suspenda-a.

## Erros

| Status | Código | Causa |
| - | - | - |
| `400` | `VALIDATION_ERROR` | JSON inválido, um campo desconhecido, um valor fora do intervalo ou um intervalo de uso inválido. |
| `403` | `SUB_ACCOUNT_FORBIDDEN` | A chave tem escopo de mecanismo ou limite diário de créditos, ou pertence a uma subconta. |
| `404` | `NOT_FOUND` | Nenhuma subconta sua com esse id, ou nenhuma chave ativa com esse id. |
| `409` | `SUB_ACCOUNT_EXISTS` | Outra subconta já tem esse `externalId`. |
| `409` | `KEY_LIMIT` | A subconta já tem 5 chaves ativas. |

## Endpoints

| Método e caminho | Uso |
| - | - |
| [`POST /v1/sub-accounts`](/pt/api-reference/sub-accounts/create-sub-account) | Criar |
| [`GET /v1/sub-accounts`](/pt/api-reference/sub-accounts/list-sub-accounts) | Listar, com `externalId`, `limit` e `cursor` |
| [`GET /v1/sub-accounts/{id}`](/pt/api-reference/sub-accounts/get-sub-account) | Uma subconta, com `activeTasks` |
| [`PATCH /v1/sub-accounts/{id}`](/pt/api-reference/sub-accounts/update-sub-account) | Alterar configurações, suspender ou reativar |
| [`GET /v1/sub-accounts/usage`](/pt/api-reference/sub-accounts/list-usage) | Totais por subconta |
| [`GET /v1/sub-accounts/{id}/usage`](/pt/api-reference/sub-accounts/get-usage) | Uma subconta por dia e mecanismo |
| [`GET /v1/sub-accounts/{id}/keys`](/pt/api-reference/sub-accounts/list-keys) | Listar as chaves, incluindo as revogadas e expiradas |
| [`POST /v1/sub-accounts/{id}/keys`](/pt/api-reference/sub-accounts/issue-key) | Emitir uma chave |
| [`DELETE /v1/sub-accounts/{id}/keys/{keyId}`](/pt/api-reference/sub-accounts/revoke-key) | Revogar uma chave |


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