Usage statistics

Which dimensions are queryable, how time boundaries are computed, how long data is retained, and how to export it yourself.

Usage data is what lets you notice abnormal consumption. This page covers what each endpoint returns, where the time boundaries fall, and how long data survives.

Summary

GET/api/v1/proxy/usage/summary

An account-level global view:

Current traffic pool balance and lifetime purchases
Billed bytes for this month and last month

shell

curl 'https://api.example.com/api/v1/proxy/usage/summary' \
  -H 'Authorization: Bearer at_YOUR_ACCESS_TOKEN'

This is the endpoint a monitoring script should poll — alert when the balance drops below a threshold.

Per-day breakdown

GET/api/v1/proxy/usage/daily

Range: 1–90 days.

shell

curl 'https://api.example.com/api/v1/proxy/usage/daily?days=30' \
  -H 'Authorization: Bearer at_YOUR_ACCESS_TOKEN'

Usage series

GET/api/v1/proxy/usage/series

Available granularities:

Granularity	Range
Hour	Today's 24 hours
Day	Last 7 or 30 days (Beijing calendar days)

It also supports filtering by target domain, which helps pin down which site consumed the traffic.

Domains visited

GET/api/v1/proxy/usage/domains

Returns recently visited domains, up to 500.

shell

curl 'https://api.example.com/api/v1/proxy/usage/domains' \
  -H 'Authorization: Bearer at_YOUR_ACCESS_TOKEN'

Retention

Data	Retention
Daily aggregates	Long-term
Hourly detail	60 days
Hourly per-domain detail	60 days

Dimension limits in the client API

Plan for this if you're doing team chargeback. A workable alternative:

One sub-account per business unit, labelled through the remark field, with your own accounting on top. See Proxy sub-accounts.

Accounting definitions

Raw traffic = bidirectional payload bytes, upload plus download.

Billed traffic = raw traffic × product multiplier, floored after accumulation.

The two are identical at a 1:1 multiplier. Full accounting (what counts and what doesn't) is in Traffic accounting.

Exporting for your own records

python

import csv
import json
from datetime import date, timedelta


def export_daily_usage(client, days: int = 90, path: str = "usage.csv") -> None:
    """Export the per-day breakdown.

    Hourly detail is retained 60 days and daily aggregates are long-term, but
    exporting regularly is still worthwhile — the endpoint returns 90 days at most.
    """
    payload = client.get("/api/v1/proxy/usage/daily", days=days)

    with open(path, "w", newline="", encoding="utf-8") as handle:
        writer = csv.DictWriter(
            handle,
            fieldnames=["date", "uploadBytes", "downloadBytes", "bytesBilled"],
        )
        writer.writeheader()
        writer.writerows(payload["items"])


def export_hourly_snapshot(client, path: str = "hourly.jsonl") -> None:
    """Export hourly detail. This data disappears after 60 days, so run it regularly."""
    payload = client.get("/api/v1/proxy/usage/series", granularity="hour")

    with open(path, "a", encoding="utf-8") as handle:
        for point in payload["items"]:
            handle.write(json.dumps(point, ensure_ascii=False) + "\n")


def export_domains(client, path: str = "domains.csv") -> None:
    """Domain detail caps at 500 entries and is a rolling "recently visited" window."""
    payload = client.get("/api/v1/proxy/usage/domains")

    with open(path, "w", newline="", encoding="utf-8") as handle:
        writer = csv.DictWriter(handle, fieldnames=["domain", "bytesBilled"])
        writer.writeheader()
        writer.writerows(payload["items"])

Transaction history

Traffic purchases, top-ups and refunds go through the transaction endpoints, which are separate from usage statistics:

GET/api/v1/transactions

GET/api/v1/transactions/metrics

metrics returns aggregated top-up / spend / refund figures.

Wallet balance and recent ledger:

GET/api/v1/wallet

A daily inspection script

python

def daily_check(client, *, warn_gb: float = 20.0, spike_ratio: float = 2.0) -> None:
    """Run once a day: balance alert plus consumption spike detection."""
    summary = client.get("/api/v1/proxy/usage/summary")
    remaining_gb = summary["trafficRemainBytes"] / 1024 ** 3

    if remaining_gb < warn_gb:
        alert(f"traffic balance {remaining_gb:.1f} GB, below {warn_gb} GB")

    daily = client.get("/api/v1/proxy/usage/daily", days=8)["items"]
    if len(daily) < 8:
        return

    # Compare the latest day against the previous seven-day mean; a spike means trouble
    recent = daily[-1]["bytesBilled"]
    baseline = sum(item["bytesBilled"] for item in daily[-8:-1]) / 7

    if baseline > 0 and recent > baseline * spike_ratio:
        domains = client.get("/api/v1/proxy/usage/domains")["items"][:5]
        top = ", ".join(f"{d['domain']}" for d in domains)
        alert(
            f"usage spike: {recent / 1024 ** 3:.1f} GB vs mean "
            f"{baseline / 1024 ** 3:.1f} GB. Top domains: {top}"
        )

Platform-side alerts

The platform's built-in traffic balance alert fires at most once per day (while below the threshold, on Beijing calendar days) and supports email, webhook, Bark and Telegram.

Configuration and capability limits are in Notifications and webhooks. For more timely or more dimensional alerting, polling yourself is currently the only option.

More in this section