# Bandwidth Usage

Source: https://docs.evomi.com/public-api/endpoints/bandwidth-usage/

The **Bandwidth Usage** endpoint returns the same proxy bandwidth and request statistics as the Evomi dashboard (**GET /products/proxy-history**), including Core Residential `extra` / `default` / `total` breakdowns.

## Endpoint

```
GET https://api.evomi.com/public/usage
```

## Query Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `period` | `24h`, `3d`, or `7d` | No | `3d` | Time range preset. `24h` uses hourly buckets; `3d` and `7d` use daily buckets (same as the dashboard). |
| `product` | string | Yes | — | Proxy product code: `rp`, `rpc`, `dcp`, `mp`, or `sdc`. |

### Product Codes

| Code | Product |
|------|---------|
| `rp` | Premium Residential |
| `rpc` | Core Residential |
| `sdc` | Datacenter Proxies |
| `mp` | Mobile Proxies |
| `sdc` | Static Datacenter |

## Authentication

Use your **personal** or **team** API key. See [Authentication](/public-api/authentication/).

- A **personal API key** reports usage for your personal proxy account only.
- A **team API key** reports usage for that team's shared proxy identity.

## Example Request

Match the dashboard default (**Last 3 days**, Core Residential):

```bash
curl -H "x-apikey: YOUR_API_KEY" \
  "https://api.evomi.com/public/usage?period=3d&product=rpc"
```

Last 7 days (daily):

```bash
curl -H "x-apikey: YOUR_API_KEY" \
  "https://api.evomi.com/public/usage?period=7d&product=rpc"
```

Last 24 hours (hourly):

```bash
curl -H "x-apikey: YOUR_API_KEY" \
  "https://api.evomi.com/public/usage?period=24h&product=rpc"
```

## Response Format

```json
{
  "success": true,
  "data": {
    "bandwidth": {
      "products": [
        {
          "name": "Residential",
          "code": "rpc",
          "totalBandwidth": 43971237.38,
          "stats": {
            "2026-05-26 00:00": { "default": 19072705.92, "extra": 0.26, "total": 19072706.18 }
          }
        }
      ]
    },
    "requests": {}
  },
  "meta": {
    "period": "3d",
    "product": "rpc",
    "duration": "3d",
    "granularity": "day",
    "ownership_scope": "personal",
    "auth_type": "personal",
    "proxy_username": "example_core_user",
    "bandwidth_unit": "MB",
    "total_bandwidth_mb": 43971237.38,
    "total_bandwidth_gb": 43971.23738,
    "total_bandwidth_tb": 43.97123738
  }
}
```

### Fields

- **data.bandwidth.products** — Only the requested `product`. Values are in **megabytes (MB)**, same as the dashboard chart total.
- **data.bandwidth.products[].stats** — Per bucket (`hour` or `day`). For Core Residential (`rpc`), each bucket may include `default`, `extra`, and `total` (MB).
- **data.bandwidth.products[].totalBandwidth** — Period total in MB (matches the dashboard bandwidth chart total).
- **meta.total_bandwidth_mb** — Same as `totalBandwidth` for the requested product (MB).
- **meta.total_bandwidth_gb** — `total_bandwidth_mb ÷ 1,000`
- **meta.total_bandwidth_tb** — `total_bandwidth_mb ÷ 1,000,000` (e.g. `43971237` MB ≈ `43.97` TB)
- **requests** — Recent request statistics (last 12 hours, hourly), same as the dashboard.

## Common Errors

- **400 Bad Request** — Invalid `period` or `product`, or upstream stats error.
- **401 Unauthorized** — Missing or invalid API key.
- **403 Forbidden** — Email verification required (personal keys only).
- **500 Internal Server Error** — Server-side failure.

For authentication details, see [Authentication](/public-api/authentication/).