Usage History

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.

cURL

curl "https://api.roundproxies.com/reseller/usage-history?granularity=day" \
  -H "x-reseller-key: $KEY"

200 OK

{
  "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:

cURL

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.

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.

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.

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

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

Getting Started

Residential Proxies

ISP Proxies

Datacenter Proxies

Reseller

Reseller API

Query parameters

Defaults and range caps

Real-time totals

How the data is produced

​Query parameters

​Defaults and range caps

​Real-time totals

​How the data is produced

Query parameters

Defaults and range caps

Real-time totals

How the data is produced