GET /v1/usage · cnpj.ia.br

Créditos

chamada · 0 créditos

Respostas

200 OK

Uso do ciclo corrente.

Header	Tipo	Descrição
`X-Request-Id`	`string`	Identificador da requisição para suporte.
`X-Client-Request-Id`	`string`	Eco do X-Request-Id enviado pelo cliente quando casa ^[A-Za-z0-9_-]{8,64}$. Ausente se o cliente não enviou ou o valor é inválido. Nunca usado como identificador interno.
`X-Credits-Charged`	`integer`	Créditos debitados nesta resposta.
`X-Credits-Remaining`	`integer`	Créditos restantes (franquia + pacotes).
`X-Credits-Reset`	`string` formato: `date-time`	Instante do próximo reset da franquia (RFC 3339).
`X-RateLimit-Limit`	`integer`	Requisições por minuto do plano (por conta).
`X-RateLimit-Remaining`	`integer`	Requisições restantes no minuto corrente.

{
  "plan": "free",
  "credits_allowance": 0,
  "credits_used": 0,
  "credits_remaining": 0,
  "packs": [],
  "rpm": 3,
  "search_enabled": false,
  "cycle_reset_at": "2026-10-01T00:00:00-03:00"
}

401 Não autorizado

Chave ausente, desconhecida, revogada ou expirada.

Header	Tipo	Descrição
`X-Request-Id`	`string`	Identificador da requisição para suporte.
`X-Client-Request-Id`	`string`	Eco do X-Request-Id enviado pelo cliente quando casa ^[A-Za-z0-9_-]{8,64}$. Ausente se o cliente não enviou ou o valor é inválido. Nunca usado como identificador interno.

{
  "error": {
    "code": "invalid_api_key",
    "message": "Chave de API ausente ou inválida.",
    "request_id": "req_01J8ZK3Q9X",
    "retryable": false,
    "docs_url": "https://cnpj.ia.br/docs/erros-e-retentativas#invalid_api_key"
  }
}

403 Proibido

Conta com billing_state blocked (payment_required).

Header	Tipo	Descrição
`X-Request-Id`	`string`	Identificador da requisição para suporte.
`X-Client-Request-Id`	`string`	Eco do X-Request-Id enviado pelo cliente quando casa ^[A-Za-z0-9_-]{8,64}$. Ausente se o cliente não enviou ou o valor é inválido. Nunca usado como identificador interno.

{
  "error": {
    "code": "payment_required",
    "message": "Sua conta está com pagamento pendente. Regularize para continuar usando a API.",
    "request_id": "req_01J8ZK3Q9X",
    "retryable": false,
    "docs_url": "https://cnpj.ia.br/docs/erros-e-retentativas#payment_required"
  }
}

404 Não encontrado

API desligada (CNPJIA_API_ENABLED diferente de on).

Header	Tipo	Descrição
`X-Request-Id`	`string`	Identificador da requisição para suporte.
`X-Client-Request-Id`	`string`	Eco do X-Request-Id enviado pelo cliente quando casa ^[A-Za-z0-9_-]{8,64}$. Ausente se o cliente não enviou ou o valor é inválido. Nunca usado como identificador interno.

{
  "error": {
    "code": "not_found",
    "message": "Recurso não encontrado.",
    "request_id": "req_01J8ZK3Q9X",
    "retryable": false,
    "docs_url": "https://cnpj.ia.br/docs/erros-e-retentativas#not_found"
  }
}

429 Excesso de requisições

Requisições por minuto da conta excedidas. Header Retry-After. Sem X-RateLimit-* quando o limite atingido é o de requisições sem chave por IP.

Header	Tipo	Descrição
`X-Request-Id`	`string`	Identificador da requisição para suporte.
`X-Client-Request-Id`	`string`	Eco do X-Request-Id enviado pelo cliente quando casa ^[A-Za-z0-9_-]{8,64}$. Ausente se o cliente não enviou ou o valor é inválido. Nunca usado como identificador interno.
`Retry-After`	`integer`	Só em 429 e 503: segundos até tentar de novo.
`X-RateLimit-Limit`	`integer`	Requisições por minuto do plano (por conta).
`X-RateLimit-Remaining`	`integer`	Requisições restantes no minuto corrente.

{
  "error": {
    "code": "rate_limited",
    "message": "Limite de requisições excedido. Tente novamente em instantes.",
    "request_id": "req_01J8ZK3Q9X",
    "retryable": true,
    "docs_url": "https://cnpj.ia.br/docs/erros-e-retentativas#rate_limited"
  }
}

500 Erro interno

Erro não previsto. retryable: true; esta operação não consome créditos. X-RateLimit-* presentes quando a requisição passou pelo controle de requisições por conta.

Header	Tipo	Descrição
`X-Request-Id`	`string`	Identificador da requisição para suporte.
`X-Client-Request-Id`	`string`	Eco do X-Request-Id enviado pelo cliente quando casa ^[A-Za-z0-9_-]{8,64}$. Ausente se o cliente não enviou ou o valor é inválido. Nunca usado como identificador interno.
`X-RateLimit-Limit`	`integer`	Requisições por minuto do plano (por conta).
`X-RateLimit-Remaining`	`integer`	Requisições restantes no minuto corrente.

{
  "error": {
    "code": "internal_error",
    "message": "Erro interno. Tente novamente; se persistir, fale com o suporte.",
    "request_id": "req_01J8ZK3Q9X",
    "retryable": true,
    "docs_url": "https://cnpj.ia.br/docs/erros-e-retentativas#internal_error"
  }
}

504 Tempo esgotado

Timeout de consulta. retryable: true; nada é cobrado. X-RateLimit-* presentes quando a requisição passou pelo controle de requisições por conta.

Header	Tipo	Descrição
`X-Request-Id`	`string`	Identificador da requisição para suporte.
`X-Client-Request-Id`	`string`	Eco do X-Request-Id enviado pelo cliente quando casa ^[A-Za-z0-9_-]{8,64}$. Ausente se o cliente não enviou ou o valor é inválido. Nunca usado como identificador interno.
`X-RateLimit-Limit`	`integer`	Requisições por minuto do plano (por conta).
`X-RateLimit-Remaining`	`integer`	Requisições restantes no minuto corrente.

{
  "error": {
    "code": "upstream_timeout",
    "message": "A operação demorou mais que o esperado. Tente novamente.",
    "request_id": "req_01J8ZK3Q9X",
    "retryable": true,
    "docs_url": "https://cnpj.ia.br/docs/erros-e-retentativas#upstream_timeout"
  }
}

Ferramenta MCP

No servidor MCP oficial esta operação é a ferramenta ver_uso, com a mesma chave e os mesmos créditos da API.

Exemplo

curl -s "https://api.cnpj.ia.br/v1/usage" \
  -H "Authorization: Bearer $CNPJIA_KEY"