# Uso do projeto

Fonte: https://apiwpp.com/docs/api/uso/uso-do-projeto
Seção: Uso
Atualizado em: 2026-09-28

`GET /tenants/{id}/usage`

Mensagens enviadas hoje e neste mês (dias em UTC) pelo projeto e pela organização dele. Os planos são da organização, e todos os projetos dela contam para os limites diário e mensal: os envios são recusados com `429` quando o uso da organização passa deles. Traz também o plano, a assinatura da organização e o histórico diário do projeto nos últimos `days` dias (padrão 30, no máximo 366). Escopo necessário: `usage:read`.

## Cabeçalhos

| Nome | Obrigatório | Descrição |
| --- | --- | --- |
| `Authorization` | sim | `Bearer <chave de API>`; ou envie a chave em `X-Api-Key`. |

## Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string · uuid` | sim | Identificador do projeto (`tenantId`), um UUID. Precisa ser um projeto que a chave alcança. |

## Parâmetros de consulta

| Nome | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `days` | `string` | não | Quantos dias de histórico trazer em `dailyUsage`, no máximo `366`: um valor maior vira `366`, e um valor que não é um número inteiro positivo vira `30`. (padrão: "30") |

## Exemplo de requisição

### cURL

```bash
curl "https://api.apiwpp.com/tenants/$TENANT_ID/usage?days=7" \
  -H "Authorization: Bearer $API_KEY"
```

### Node.js

```javascript
const res = await fetch(`https://api.apiwpp.com/tenants/${tenantId}/usage?days=7`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
})
const data = await res.json()
```

### PHP

```php
$response = Http::withToken($apiKey)
    ->get("https://api.apiwpp.com/tenants/{$tenantId}/usage", [
        'days' => '7',
    ]);
```

### Python

```python
import requests

response = requests.get(
    f"https://api.apiwpp.com/tenants/{tenant_id}/usage",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={
        "days": "7",
    },
)
```

## Respostas

| Código | Erro | Descrição |
| --- | --- | --- |
| 200 |  | O uso do projeto e o da organização: `tenantId`; `plan`, o plano da organização (`name`, `displayName`, `maxMessagesDay` e `maxMessagesMonth`, em que `-1` é ilimitado; `null`: sem limites); `usage`, as mensagens enviadas pelo próprio projeto (`today`, `thisMonth`) e quanto elas representam dos limites da organização (`percentOfDailyLimit`, `percentOfMonthlyLimit`, em porcentagem); `organization`, com `id` e o mesmo `usage` somando todos os projetos da organização, que é sobre o que os limites valem; `subscription`, a assinatura da organização (`status`: `trialing`, `active`, `past_due`, `unpaid`, `incomplete`, `paused`, `canceled`, `expired` ou `suspended`; `trialEndsAt` e `currentPeriodEnd` em ISO 8601, ou `null`); e `dailyUsage`, o histórico do projeto (`date` no formato `AAAA-MM-DD` em UTC, `messagesSent`, `messagesRecv`). |
| 400 | `FST_ERR_VALIDATION` | O `id` do projeto não é um UUID; `message` diz o que está errado. |
| 401 |  | Sem chave de API, ou com uma chave inválida: desconhecida, revogada, expirada ou de um projeto desativado. O corpo é `{"error": "Unauthorized"}`. |
| 403 |  | A chave não tem o escopo `usage:read`; a mensagem cita o escopo (`This credential lacks the usage:read scope`). |
| 404 |  | O projeto não existe ou a chave não o alcança (`{"error": "Tenant not found"}`): o projeto de outra pessoa responde exatamente como um que não existe. |
| 429 |  | Requisições demais deste IP de origem (por padrão, 600 por minuto), ou autenticações com falha demais (por padrão, 20 a cada 5 minutos): espere os segundos de `Retry-After`. Veja [Limites](https://apiwpp.com/docs/referencia/limites). Cabeçalhos: `Retry-After`. |

### 200 OK

```json
{
  "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
  "plan": {
    "name": "pro",
    "displayName": "Pro",
    "maxMessagesDay": 1000,
    "maxMessagesMonth": 20000
  },
  "usage": {
    "today": 12,
    "thisMonth": 540,
    "percentOfDailyLimit": 1.2,
    "percentOfMonthlyLimit": 2.7
  },
  "organization": {
    "id": "2d5e8a1b-4c7f-4e9a-8b3d-6f0a2c4e8b1d",
    "usage": {
      "today": 30,
      "thisMonth": 1200,
      "percentOfDailyLimit": 3,
      "percentOfMonthlyLimit": 6
    }
  },
  "subscription": {
    "status": "active",
    "trialEndsAt": null,
    "currentPeriodEnd": "2026-10-24T12:00:00.000Z"
  },
  "dailyUsage": [
    {
      "date": "2026-09-23",
      "messagesSent": 42,
      "messagesRecv": 17
    },
    {
      "date": "2026-09-24",
      "messagesSent": 12,
      "messagesRecv": 5
    }
  ]
}
```

## Detalhes

As contas de `usage` e de `organization.usage` usam só as mensagens **enviadas**: uma mensagem conta quando a fila do número a entrega ao WhatsApp, não quando o `POST /connections/{id}/send` a aceita. As recebidas aparecem só no histórico (`dailyUsage[].messagesRecv`).

As cotas valem sobre `organization.usage`, não sobre o uso do projeto. Por padrão, o gateway avisa a partir de 80% da cota (cabeçalho `X-Usage-Warning` no envio) e recusa a partir de 110% (uma folga de 10% para envios simultâneos), e no envio as mensagens aceitas e ainda na fila também contam. Veja [Limites de envio](https://apiwpp.com/docs/guias/limites-de-envio).

As porcentagens não são arredondadas e podem passar de 100. Com `plan` igual a `null`, ou com um limite `-1` (ilimitado), a porcentagem correspondente vem `0`.

`dailyUsage` traz só os dias em que o projeto enviou ou recebeu alguma mensagem, do mais antigo ao mais recente, desde `days` dias atrás até hoje. Para uma série com os dias zerados, use [Uso diário](https://apiwpp.com/docs/api/uso/uso-diario).

Guia: [Uso e registros](https://apiwpp.com/docs/guias/uso-e-registros).
