Usage

Bandwidth per product, bucketed by hour or day, for the last day, week or month. The same numbers as the Statistics page.

Get usage

GET/api/usage?range=7d
Query parameters
range"24h" | "7d" | "30d"The window. 24h comes in hourly buckets; 7d and 30d in daily ones. Default 7d.
curl https://birdieproxies.com/api/usage?range=24h \
  -H "Authorization: Bearer $BIRDIE_API_KEY"
200 OK
{
  "range": "24h",
  "granularity": "hour",
  "total_bytes": 4515954688,
  "products": [
    {
      "type": "residential",
      "total_bytes": 4515954688,
      "buckets": [
        { "at": "2026-09-21T10:00:00.000Z", "bytes": 318932582 },
        { "at": "2026-09-21T11:00:00.000Z", "bytes": 967311360 },
        { "at": "2026-09-21T12:00:00.000Z", "bytes": 0 }
      ]
    }
  ]
}

Fields

Fields
rangestringThe window you asked for.
granularity"hour" | "day"The size of each bucket.
total_bytesintegerEverything in the window, across products.
products[].typestringThe product, as on plans. Products with no traffic in the window are left out.
products[].total_bytesintegerThat product's total in the window.
products[].buckets[]arrayOne at (bucket start, UTC) and bytes per bucket, oldest first. Empty buckets are present as zero.

Notes

Bytes, not gigabytes, because hourly figures are small and rounding would lose them. Divide by 1048576000 for gigabytes as balances count them (1000 MB of 1,048,576 bytes). Buckets are aligned to the hour or the UTC day. The current bucket is still filling, so the last entry grows until the hour or day ends.

Where the numbers come from

Usage is measured by the proxy network as traffic flows and can lag a few minutes behind. For the balance itself, use plans, which is live.