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

# Usage & Billing

> Track conversation volumes and message counts across your sub-accounts.

## Get Usage Stats

`GET /usage`

Aggregate usage across all sub-accounts for the billing period.

<ParamField query="period" type="string" default="current">
  `current`, `previous`, or `YYYY-MM`
</ParamField>

<ParamField query="account_id" type="string">
  Filter to a specific sub-account
</ParamField>

<ParamField query="group_by" type="string">
  `account` for per-account breakdown
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.recoverbiz.com/v1/usage?period=current&group_by=account \
    -H "X-Partner-Key: pk_live_abc123def456..."
  ```

  ```typescript JavaScript theme={null}
  const res = await fetch('https://api.recoverbiz.com/v1/usage?period=current&group_by=account', {
    headers: { 'X-Partner-Key': 'pk_live_abc123def456...' },
  });
  const usage = await res.json();
  console.log(`Total conversations: ${usage.totals.conversations}`);
  ```

  ```python Python theme={null}
  usage = requests.get(f'{BASE_URL}/usage?period=current&group_by=account', headers=headers).json()
  print(f'Total conversations: {usage["totals"]["conversations"]}')
  ```
</CodeGroup>

**Response: `200 OK`**

```json theme={null}
{
  "period": "2026-02",
  "totals": {
    "conversations": 4820,
    "messages_sent": 28400,
    "messages_received": 22100,
    "leads_imported": 3200,
    "documents_collected": 890,
    "sequences_completed": 1540,
    "active_accounts": 47
  },
  "by_account": [
    {
      "account_id": "acc_8f3a1b2c",
      "account_name": "Acme Lending",
      "conversations": 289,
      "messages_sent": 1720,
      "messages_received": 1340,
      "leads_imported": 180,
      "documents_collected": 45
    }
  ]
}
```

## Billing Models

The Usage API gives you the data to implement any billing model:

| Model                | How It Works                                          |
| -------------------- | ----------------------------------------------------- |
| **Per conversation** | Charge based on `conversations` count                 |
| **Per message**      | Charge based on `messages_sent` + `messages_received` |
| **Flat fee**         | Fixed monthly rate per active account                 |
| **Bundled**          | Include in your existing SaaS pricing                 |

<Info>
  Usage data is updated in real-time. Pull stats at any frequency to power your billing system.
</Info>