> For the complete documentation index, see [llms.txt](https://docs.helodata.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.helodata.com/api-reference/traffic.md).

# Traffic & usage

Read bandwidth and request analytics across products. Same shape per product — only the path prefix changes.

## Endpoints

| Path                   | Product     |
| ---------------------- | ----------- |
| `/residential/traffic` | Residential |
| `/mobile/traffic`      | Mobile      |
| `/isp/traffic`         | ISP         |

| Path                  | Purpose                                     |
| --------------------- | ------------------------------------------- |
| `/{product}/traffic`  | Aggregated bandwidth                        |
| `/{product}/requests` | Sampled request log                         |
| `/{product}/sessions` | Sticky-session inventory (gateway products) |

## Get aggregate traffic

```bash
curl -H "Authorization: Bearer API_KEY" \
     "https://api.helodata.com/v1/residential/traffic?from=2026-05-01&to=2026-05-28&group_by=subuser"
```

### Query parameters

| Param      | Required | Description                                      |
| ---------- | -------- | ------------------------------------------------ |
| `from`     | yes      | RFC 3339 start of range                          |
| `to`       | yes      | RFC 3339 end of range (exclusive)                |
| `group_by` | no       | `subuser`, `region`, `asn`, `tag`, `day`, `hour` |
| `subuser`  | no       | Filter to one sub-user                           |
| `region`   | no       | Filter to one ISO country code                   |
| `tag`      | no       | Filter to one `X-Helodata-Tag` value             |

### Response

```json
{
  "from": "2026-05-01T00:00:00Z",
  "to":   "2026-05-28T00:00:00Z",
  "rows": [
    {
      "subuser":   "sub_01HX2K3PQ4M5",
      "bytes_in":  12345678,
      "bytes_out": 9876543,
      "requests":  4210,
      "errors":    51,
      "error_rate": 0.012
    }
  ]
}
```

ISP adds per-IP rollups; mobile adds `asn` and `carrier_name`:

```json
{ "ip": "198.51.100.42", "bytes_in": 1234567, "bytes_out": 9876543, "requests": 4210 }
{ "asn": 6167, "carrier_name": "Verizon Wireless", "bytes_in": 222345 }
```

## Sampled request log

```bash
curl -H "Authorization: Bearer API_KEY" \
     "https://api.helodata.com/v1/residential/requests?subuser=sub_01HX2K3PQ4M5&limit=100"
```

Returns up to 1,000 sampled requests for the last 48 hours:

```json
{
  "data": [
    {
      "request_id":  "req_01HX2K3PQ4M5",
      "ts":          "2026-05-28T07:14:22Z",
      "subuser":     "sub_01HX2K3PQ4M5",
      "method":      "GET",
      "target_host": "example.com",
      "status":      200,
      "bytes":       38745,
      "exit_ip":     "198.51.100.42",
      "exit_geo":    "us/ca/la",
      "exit_asn":    7922,
      "tag":         "campaign-acme-q2"
    }
  ]
}
```

Useful for spotting hot-spots and debugging individual call patterns. Don't use it for billing — it's sampled, not exhaustive.

## Granularity

Data resolution downsamples over time:

| Age        | Resolution |
| ---------- | ---------- |
| < 24 h     | 1 minute   |
| 1–14 days  | 5 minutes  |
| 14–90 days | 1 hour     |
| > 90 days  | 1 day      |

Pull historical data sooner than your retention window if you need finer detail.

## Errors

| Status | Code               | Meaning                    |
| ------ | ------------------ | -------------------------- |
| `422`  | `range_too_wide`   | `from..to` exceeds 90 days |
| `422`  | `invalid_group_by` | Unknown `group_by` value   |