# Statistics

ISP statistics are dimensioned **per IP** rather than per request flow. Each IP is a billable resource you own; the dashboard and API help you see which ones are paying off.

## Dashboard

**Dashboard → ISP → Statistics** shows:

* **Per-IP usage** — bytes, request count, error rate
* **Per-batch health score** — composite (errors + replacements + saturation)
* **Top targets** — which sites you hit through ISP
* **IP utilization** — which IPs in a batch are idle (candidates for release)
* **Replacement history** — IPs replaced over time
* **Renewal calendar** — upcoming billing dates

Granularity: 1-minute for the last 24 hours, 5-minute for 7 days, hourly beyond.

## REST API

Per-IP traffic over time:

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

Response:

```json
{
  "rows": [
    { "ip": "198.51.100.42", "bytes_in": 1234567, "bytes_out": 9876543, "requests": 4210, "error_rate": 0.012 },
    { "ip": "198.51.100.43", "bytes_in": 222345,  "bytes_out": 134567,  "requests": 88,   "error_rate": 0.0 }
  ]
}
```

`group_by` accepts `ip`, `batch`, `target_domain`, `day`.

Per-IP detail (most-recent N requests):

```bash
curl -H "Authorization: Bearer API_KEY" \
     "https://api.helodata.com/v1/isp/ips/{ip_id}/requests?limit=100"
```

Returns the last 1,000 sampled requests with status, target, bytes, and timestamp.

## Per-response headers

Each ISP IP returns these on every response:

```
X-Helodata-Bytes-In: 1248
X-Helodata-Bytes-Out: 38745
X-Helodata-IP-Health: 96
X-Helodata-Request-Id: req_01HX2K3PQ4M5
```

`X-Helodata-IP-Health` is the live 0–100 score for the IP — drop below 80 and the dashboard alert (if configured) fires.

## Tagging requests

Same mechanism as residential — `X-Helodata-Tag` request header. Tags surface in dashboard filters and traffic API `group_by`.

```bash
curl -x http://helo_s1a2b3c4d5e:PASSWORD@198.51.100.42:8000 \
     -H "X-Helodata-Tag: campaign-acme-q2" \
     https://example.com
```

## Spotting idle IPs

The dashboard flags IPs that haven't been used in the last 7 days. Two options:

* **Reassign** — start sending traffic through them
* **Release** — drop them at the next renewal to save cost

## Health-based alerts

**Dashboard → Alerts** offers ISP-specific alerts:

* IP health drops below threshold X
* Batch health drops below X
* Replacement count exceeds Y per period
* Batch is in grace (renewal warning)
* Per-IP error rate exceeds Z% over Z minutes

Alerts deliver via email and optional Slack webhook.

## Billing reconciliation

ISP is billed per IP per month — flat fee, regardless of usage. The invoice line on **Billing → Invoices** is `qty × monthly_price`. There's no bandwidth charge to reconcile.

If you replace IPs mid-period, the count on your invoice stays the same — replacement is included in your monthly fee up to the 10% allowance.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.helodata.com/products/overview-2/statistics.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.