---
title: "Summarise spend over a window"
method: GET
path: "/api/v1/usage/summary"
---

# Summarise spend over a window

`GET /api/v1/usage/summary`

## Request

- Base URL: `https://prowl.chat`
- URL: `https://prowl.chat/api/v1/usage/summary`
- Auth: HTTP bearer

Spend rolled up over the last `days` days — totals, the twenty tools that cost the most, and the current balances alongside them so a budget decision needs one request rather than two.

## Query parameters

- `days` integer

## Headers

- `authorization` string, nullable

## Cookies

- `prowl_session` string, nullable

## Response `200`

Successful Response

- UsageSummaryResponse: Spend over a window, with the current balances alongside it. Inherits `WalletBalances` because the handler spreads the wallet into its reply (`persistence/wallet.py:2405`) — modelling it any other way would make the enforced filter drop the four balance fields the dashboard reads.
  - `subscription_balance_usd` number, required: Plan credit for the current period. Burns at period end, spent first.
  - `extra_balance_usd` number, required: Top-up credit. Never expires, spent after the subscription pool.
  - `total_available_usd` number, required: What the next call can draw on: the two pools added together.
  - `updated_at` string, nullable: ISO-8601 timestamp of the last balance change, or null if never moved.
  - `days` integer, required: Length of the window this summary covers, in days.
  - `invocation_count` integer, required: Metered calls inside the window.
  - `total_billed_usd` number, required: Total debited from the wallet inside the window.
  - `total_provider_usd` number, required: Total upstream provider cost inside the window.
  - `by_tool` UsageByTool[], required: Top 20 tools by spend, highest first.
    - `tool_name` string, required
    - `calls` integer, required
    - `billed_usd` number, required

## Other responses

- `401`: Missing, malformed or expired credential.
- `422`: Validation Error

---

[API](https://skmtc.dev/prowl/apis/prowl-rest-api-v1.md) · [All operations](https://skmtc.dev/prowl/apis/prowl-rest-api-v1/llms.txt) · [OpenAPI document](https://skmtc.dev/prowl/apis/prowl-rest-api-v1/revisions/897e8b30c330?raw)