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

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

{
  "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:

{ "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

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:

{
  "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