# Spend by category over the selected period

Source: https://docs.usetone.ai/reference/wallet/usage

> Calls, numbers and adjustments, each as a single figure.

`GET /v1/wallet/usage`
Calls, numbers and adjustments, each as a single figure. A purchase and its reversal fall in the same bucket, so the numbers show what something actually cost rather than a gross figure beside a credit that cancels it.

Requires the `read` scope.

## Parameters

| Name | In | | Meaning |
|---|---|---|---|
| `period` | query | optional | How far back to look. A closed set rather than an arbitrary window — this is a billing summary, not a reporting API. Open set — handle an unrecognised value rather than throwing. Today: `7d`, `30d`, `all`. |
| `agent_id` | query | optional | Narrow the breakdown to one agent calls. |

## Response

| Field | Type | | Meaning |
|---|---|---|---|
| `addedPaise` | integer | required | Top-ups net of refunds over the same window, for context beside the spend. |
| `agentId` | string | null | required | Echo of the filter. When set, only `calls` is narrowed — rentals, adjustments and top-ups do not belong to an agent, so those report zero rather than pretending an org-wide figure is agent-specific. |
| `categories` | object[] | required | Always one row per category, zeroes included, so a rendered breakdown never reflows. |
| `categories[].category` | string | required | Which kind of spend this row totals. Open set — handle an unrecognised value rather than throwing. Today: `calls`, `numbers`, `compliance`, `adjustments`. |
| `categories[].entries` | integer | required | Ledger entries behind the figure, so a row can say "42 calls". |
| `categories[].spentPaise` | integer | required | Net spend as a POSITIVE figure. Negative only if refunds outweighed spend. |
| `from` | string | null | required | Start of the window this breakdown covers. RFC 3339, UTC. Null for `all` — there is no start date. |
| `period` | string | required | The window this breakdown covers, echoing the period you asked for. |
| `to` | string | required | The end of the window this breakdown covers. RFC 3339, UTC. |
| `totalSpentPaise` | integer | required | Sum of the categories below. Positive means money left the wallet. |

### Example response

```json
{
  "data": {
    "addedPaise": 0,
    "agentId": "9f1c2d84-4e3a-4f6c-b902-7d1e8a33c451",
    "categories": [
      {
        "category": "calls",
        "entries": 0,
        "spentPaise": 0
      }
    ],
    "from": "2026-08-25T09:14:22Z",
    "period": "7d",
    "to": "2026-08-25T09:14:22Z",
    "totalSpentPaise": 0
  }
}
```