Subcontas: chaves, limites e uso por cliente final

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.

{
  "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

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:

{
  "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:

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

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.

{
  "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.

{
  "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 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.

{
  "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

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:

{
  "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

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:

{
  "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 de um monitor. Soma créditos, mas não tasks.

Suspender e reativar

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`	Criar
`GET /v1/sub-accounts`	Listar, com `externalId`, `limit` e `cursor`
`GET /v1/sub-accounts/{id}`	Uma subconta, com `activeTasks`
`PATCH /v1/sub-accounts/{id}`	Alterar configurações, suspender ou reativar
`GET /v1/sub-accounts/usage`	Totais por subconta
`GET /v1/sub-accounts/{id}/usage`	Uma subconta por dia e mecanismo
`GET /v1/sub-accounts/{id}/keys`	Listar as chaves, incluindo as revogadas e expiradas
`POST /v1/sub-accounts/{id}/keys`	Emitir uma chave
`DELETE /v1/sub-accounts/{id}/keys/{keyId}`	Revogar uma chave

Primeiros passos

Conceitos principais

Mecanismos de resposta

Busca e dados da web

Opções de requisição

Pesquisa

Monitoramento GEO

Conta e dados

Subcontas: chaves, limites e uso por cliente final

Como uma subconta funciona

Quem pode gerenciar subcontas

Crie uma subconta e uma chave

Gerencie as chaves

Limites

Consulte uma subconta agora

Uso e cobrança

Todas as subcontas

Uma subconta

Suspender e reativar

Erros

Endpoints

​Como uma subconta funciona

​Quem pode gerenciar subcontas

​Crie uma subconta e uma chave

​Gerencie as chaves

​Limites

​Consulte uma subconta agora

​Uso e cobrança

​Todas as subcontas

​Uma subconta

​Suspender e reativar

​Erros

​Endpoints

Como uma subconta funciona

Quem pode gerenciar subcontas

Crie uma subconta e uma chave

Gerencie as chaves

Limites

Consulte uma subconta agora

Uso e cobrança

Todas as subcontas

Uma subconta

Suspender e reativar

Erros

Endpoints