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

# Usage History

> Consumption time series for your pool and for individual sub-users.

Where `includeUsage=true` gives you a live snapshot, these endpoints give you consumption **over time** as a zero-filled time series.

| Endpoint                                      | Scope                                                          |
| --------------------------------------------- | -------------------------------------------------------------- |
| `GET /reseller/usage-history`                 | Pool-wide — your own retail account plus all sub-users, summed |
| `GET /reseller/users/:username/usage-history` | One sub-user                                                   |

Both are served entirely from stored history and make **no gateway calls**, so they're fast and safe to call freely.

```bash cURL theme={null}
curl "https://api.roundproxies.com/reseller/usage-history?granularity=day" \
  -H "x-reseller-key: $KEY"
```

**200 OK**

```json theme={null}
{
  "granularity": "day",
  "from": "2026-07-16T00:00:00.000Z",
  "to": "2026-08-15T00:00:00.000Z",
  "totalBytes": 5801,
  "series": [
    { "start": "2026-08-14T00:00:00.000Z", "usedBytes": 5801 },
    { "start": "2026-08-15T00:00:00.000Z", "usedBytes": 0 }
  ]
}
```

Every bucket in the range is present, including empty ones. Weeks start Monday, UTC.

## Query parameters

| Parameter     | Description                                                              |
| ------------- | ------------------------------------------------------------------------ |
| `granularity` | `hour`, `day` (default), `week`, `month`, or `year`                      |
| `from` / `to` | ISO 8601 timestamps. Defaults and caps depend on granularity             |
| `live`        | `true` folds consumption since the last snapshot into the current bucket |

### Defaults and range caps

| Granularity | Default range  |
| ----------- | -------------- |
| `hour`      | Last 48 hours  |
| `day`       | Last 30 days   |
| `week`      | Last 12 weeks  |
| `month`     | Last 12 months |
| `year`      | Last 5 years   |

Each granularity has a maximum range. Asking for more returns `400` — narrow the range or use a coarser granularity.

### Real-time totals

Stored history can be up to 15 minutes behind. Pass `live=true` to read the gateway counters at request time and fold the delta into the current bucket:

```bash cURL theme={null}
curl "https://api.roundproxies.com/reseller/usage-history?granularity=hour&live=true" \
  -H "x-reseller-key: $KEY"
```

The response then carries `"live": true` and a `liveFailedLookups` count.

<Note>
  `live=true` costs one gateway call per account in scope — your retail account plus every sub-user, the same cost as `includeUsage`. It's skipped automatically for ranges that don't reach the present, so historical queries stay cheap.
</Note>

## How the data is produced

* A cron snapshots every gateway account's cumulative counters **every 15 minutes**. `hour` series build on these, so they lag up to 15 minutes, and snapshots are retained for **90 days**.
* A daily rollup at **00:20 UTC** condenses each UTC day into one document per account, kept **forever**. `day`, `week`, `month`, and `year` build on these.
* The current, not-yet-rolled-up day is blended in live from snapshots, so "today" is never an empty bucket.
* Counter resets — for example an account recreated upstream — are clamped. A bucket is never negative.

<Warning>
  History begins when this feature was deployed. There is no retroactive backfill, so ranges reaching further back will show empty buckets.
</Warning>

Deleting a sub-user does not erase its contribution: consumption history for your account is preserved.