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

# Get Usage Statistics

> Retrieve live proxy usage statistics for a datacenter order.

Retrieve live proxy usage statistics for a datacenter order — the same data shown on the dashboard's usage view.

<Note>
  Only available for **datacenter** orders. Residential and other product categories have no SquidAnalyzer source and return **400**.
</Note>

## How It Works

Usage values are scraped **live at request time** from each child proxy server's SquidAnalyzer report (no caching), aggregated across every server that hosts the order, and returned as a usage time series plus a list of the top requested domains.

Because the data is fetched live, if a child server hosting the order is not currently producing SquidAnalyzer reports, its slice of usage is omitted (each per-server fetch has a 5s timeout and fails open). Totals therefore reflect only the servers that are reporting.

## Request

### Headers

| Header          | Value                   | Required |
| --------------- | ----------------------- | -------- |
| `Authorization` | `Bearer {your_api_key}` | Yes      |

### Path Parameters

<ParamField path="order_id" type="string" required>
  The order ID returned from order creation.
</ParamField>

### Query Parameters

<ParamField query="period" type="string" default="monthly">
  The reporting granularity. One of `daily`, `weekly`, `monthly`.

  * `daily` — time series is keyed by hour (`"00"`–`"23"`)
  * `weekly` — time series is keyed by day of week
  * `monthly` — time series is keyed by day of month (`"01"`–`"31"`)
</ParamField>

<ParamField query="date" type="string">
  ISO date string selecting the reporting window (e.g. `2026-06-25`). Defaults to today.
</ParamField>

### Example Requests

```bash theme={null}
curl -X GET "https://dashboard.statproxies.com/api/v2/order/usage/sub_1rqjp3jb4g9i6pkhdwmkpjob" \
  -H "Authorization: Bearer {your_api_key}"
```

```bash theme={null}
# Daily usage for a specific date
curl -X GET "https://dashboard.statproxies.com/api/v2/order/usage/sub_1rqjp3jb4g9i6pkhdwmkpjob?period=daily&date=2026-06-25" \
  -H "Authorization: Bearer {your_api_key}"
```

## Response

### Success Response

```json theme={null}
{
  "response": "success",
  "order_id": "sub_1rqjp3jb4g9i6pkhdwmkpjob",
  "period": "monthly",
  "usage": {
    "timeseries": [
      { "date": "01", "usage": 1024.55, "requests": 84213 },
      { "date": "02", "usage": 980.12, "requests": 79002 }
    ],
    "totals": {
      "bytes_in": 2152000000,
      "bytes_out": 2152000000,
      "requests": 163215
    }
  },
  "top_domains": [
    {
      "url": "example.com",
      "requests": 50213,
      "megabytesTransferred": "1.21",
      "firstVisit": "Jun 01, 12:03:11 AM 2026",
      "mostRecentVisit": "Jun 25, 09:44:52 PM 2026",
      "requestPercentage": "30.77"
    }
  ]
}
```

### Response Fields

<ResponseField name="response" type="string">
  Status of the request.
</ResponseField>

<ResponseField name="order_id" type="string">
  The order the statistics are for.
</ResponseField>

<ResponseField name="period" type="string">
  The reporting granularity that was applied (`daily`, `weekly`, or `monthly`).
</ResponseField>

<ResponseField name="usage" type="object">
  The aggregated usage data.
</ResponseField>

<ResponseField name="usage.timeseries" type="array">
  Per-bucket usage. Each entry has a `date` key (hour, day of week, or day of month depending on `period`), `usage` (megabytes transferred for that bucket), and `requests` (the request/hit count for that bucket).
</ResponseField>

<ResponseField name="usage.totals" type="object">
  Aggregate totals across all reporting servers. `bytes_in` and `bytes_out` are raw byte totals; `requests` is the total hit count.
</ResponseField>

<ResponseField name="top_domains" type="array">
  The most-requested domains, sorted by request count (descending), limited to the top 100. `requestPercentage` is computed across the aggregated set.
</ResponseField>

### Error Responses

#### 400 Bad Request - Invalid Period

```json theme={null}
{
  "response": "error",
  "message": "Invalid period specified. Must be one of: daily, weekly, monthly"
}
```

#### 400 Bad Request - Invalid Date

```json theme={null}
{
  "response": "error",
  "message": "Invalid date format"
}
```

#### 400 Bad Request - Not a Datacenter Order

```json theme={null}
{
  "response": "error",
  "message": "Usage statistics are only available for datacenter proxies"
}
```

#### 401 Unauthorized

```json theme={null}
{
  "message": "Invalid authenticated user"
}
```

#### 404 Not Found

```json theme={null}
{
  "response": "error",
  "message": "Order not found"
}
```

```json theme={null}
{
  "response": "error",
  "message": "Order has no datacenter proxy username"
}
```

#### 500 Internal Server Error

```json theme={null}
{
  "response": "error",
  "message": "Internal server error"
}
```

## Notes

* The key must have the `order` service scope. Each call is rate-limited per key and recorded in the audit log (`service: order`, `action: read`).
* Data is fetched live with no caching, so response time depends on how many servers host the order.