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

# Consultar saldo e uso

> Use a CLI da CometAPI ou a API do serviço de consulta para recuperar saldo da conta, uso e detalhes de cota por chave.

A CometAPI oferece duas formas de verificar o saldo e o uso da conta: a **CLI da CometAPI** e a **API do serviço de consulta** em `query.cometapi.com`.

Se você usa um Workspace, consulte [Gerenciar uma equipe com o CometAPI Workspace](/pt/workspace/overview) para entender os créditos compartilhados da organização e as funções de faturamento.

***

## CLI da CometAPI

Verifique seu saldo pelo terminal com um único comando. Consulte a [visão geral da CLI da CometAPI](/pt/libraries/cli/overview) para instalação.

```bash theme={null}
cometapi balance
```

Adicione `--source token` para detalhes por chave:

```bash theme={null}
cometapi balance --source token
```

Consulte a [referência de comandos](/pt/libraries/cli/commands) para todas as opções disponíveis.

***

## API do serviço de consulta

`GET https://query.cometapi.com/user/quota`

Retorna saldo no nível da conta, uso cumulativo, contagem total de solicitações e detalhes de cota por chave. Este endpoint usa um serviço de consulta separado em `query.cometapi.com` e autentica via o parâmetro de consulta `key` em vez de um Bearer Token.

<Tip>
  Use uma chave de API dedicada para consultas de saldo. Se quiser limitar a exposição, desative Unlimited Quota e defina o menor limite de crédito positivo permitido pelo dashboard.
</Tip>

### Parâmetros da solicitação

| Parameter    | Type   | Required | Description                                                       |
| ------------ | ------ | -------- | ----------------------------------------------------------------- |
| `key`        | string | Sim      | Sua chave de API do CometAPI                                      |
| `start_date` | string | Não      | Data de início para o detalhamento diário (formato `YYYY-MM-DD`)  |
| `end_date`   | string | Não      | Data de término para o detalhamento diário (formato `YYYY-MM-DD`) |

Quando `start_date` e `end_date` são fornecidos, a resposta inclui um campo `daily_quota` com o uso por chave detalhado por dia.

### Campos da resposta

| Field                               | Type    | Description                                                                           |
| ----------------------------------- | ------- | ------------------------------------------------------------------------------------- |
| `username`                          | string  | Nome de usuário                                                                       |
| `total_quota`                       | number  | Saldo atual da conta (USD)                                                            |
| `total_used_quota`                  | number  | Uso cumulativo (USD)                                                                  |
| `request_count`                     | integer | Contagem total de solicitações                                                        |
| `keys`                              | array   | Detalhes de cota por chave                                                            |
| `keys[].name`                       | string  | Nome da chave de API                                                                  |
| `keys[].remain_quota`               | number  | Cota restante da chave; `-1` significa ilimitada                                      |
| `keys[].used_quota`                 | number  | Cota usada da chave; `-1` significa ilimitada                                         |
| `daily_quota`                       | object  | Detalhamento de uso diário (somente quando `start_date` e `end_date` estão definidos) |
| `daily_quota[date]`                 | array   | Entradas de uso por chave para essa data                                              |
| `daily_quota[date][].token_name`    | string  | Nome da chave de API                                                                  |
| `daily_quota[date][].quota_used`    | number  | Uso dessa chave nessa data (USD)                                                      |
| `daily_quota[date][].request_count` | integer | Contagem de solicitações dessa chave nessa data                                       |

### Exemplos de código

Consultar saldo da conta:

<CodeGroup>
  ```bash curl theme={null}
  curl "https://query.cometapi.com/user/quota?key=$COMETAPI_KEY"
  ```

  ```python Python theme={null}
  import os
  import requests

  resp = requests.get(
      "https://query.cometapi.com/user/quota",
      params={"key": os.environ["COMETAPI_KEY"]}
  )
  data = resp.json()
  print(f"Balance: ${data['total_quota']:.2f}")
  print(f"Used: ${data['total_used_quota']:.2f}")
  print(f"Requests: {data['request_count']}")
  ```

  ```javascript Node.js theme={null}
  const resp = await fetch(
    `https://query.cometapi.com/user/quota?key=${process.env.COMETAPI_KEY}`
  );
  const data = await resp.json();
  console.log(`Balance: $${data.total_quota.toFixed(2)}`);
  console.log(`Used: $${data.total_used_quota.toFixed(2)}`);
  console.log(`Requests: ${data.request_count}`);
  ```
</CodeGroup>

### Exemplo de resposta

```json theme={null}
{
  "username": "example_user",
  "total_quota": 2105.23,
  "total_used_quota": 21.07,
  "request_count": 1221,
  "keys": [
    {
      "name": "my-key",
      "remain_quota": 8.94,
      "used_quota": 2.10
    }
  ]
}
```

### Exemplo de detalhamento diário

Consultar uso diário para um intervalo de datas:

```bash theme={null}
curl "https://query.cometapi.com/user/quota?key=$COMETAPI_KEY&start_date=2026-04-13&end_date=2026-04-14"
```

A resposta inclui os mesmos campos de nível superior mais `daily_quota`:

```json theme={null}
{
  "username": "example_user",
  "total_quota": 2105.23,
  "total_used_quota": 21.07,
  "request_count": 1221,
  "daily_quota": {
    "2026-04-13T00:00:00Z": [
      {
        "token_name": "my-key",
        "quota_used": 4.27,
        "request_count": 59
      }
    ],
    "2026-04-14T00:00:00Z": [
      {
        "token_name": "my-key",
        "quota_used": 0.57,
        "request_count": 36
      }
    ]
  }
}
```