Analytics API

All endpoints require authentication via JWT Bearer token or API key (x-api-key header).

All endpoints accept from and to as ISO 8601 date strings (max 2 month range).
Optional filters: domain (exact match), orderId (hashid-encoded).

Data is stored in 15-minute aggregated buckets using ClickHouse SummingMergeTree.
Metrics (count, bytes_sent, bytes_received, error_count, duration_ms) are auto-summed on merge.

---

POST /analytics/ingest

Push pre-aggregated request logs from proxy workers.

Body:

{
  "logs": [
    {
      "ts": "2026-03-15 10:15:00",
      "user_id": 1,
      "order_id": 3,
      "port": 443,
      "protocol": "HTTPS",
      "ip_out": "185.199.100.10",
      "ip_from": "78.100.50.12",
      "peer_id": "peer-001",
      "worker": "worker-01",
      "domain": "google.com",
      "error": "",
      "count": 12,
      "bytes_sent": 10240,
      "bytes_received": 524800,
      "error_count": 0,
      "duration_ms": 15000,
      "max_concurrency": 5
    }
  ]
}

Response: 204 No Content

---

GET /analytics/traffic

Chart data — bytes sent/received over time.

Query params:

Param	Type	Required	Description
from	string	yes	Start date (ISO 8601)
to	string	yes	End date (ISO 8601)
domain	string	no	Filter by exact domain
orderId	string	no	Filter by order (hashid)

Response:

{
  "data": [
    {
      "bucket": "2026-03-15 00:00:00",
      "total_bytes_sent": "1048576",
      "total_bytes_received": "52428800",
      "bytes_total": "53477376",
      "total_count": "1542"
    }
  ]
}

---

GET /analytics/requests

Chart data — request count over time.

Query params: same as /analytics/traffic

Response:

{
  "data": [
    {
      "bucket": "2026-03-15 00:00:00",
      "total_count": "1542",
      "total_errors": "23"
    }
  ]
}

---

GET /analytics/concurrency

Chart data — concurrency over time.

Query params: same as /analytics/traffic

Response:

{
  "data": [
    {
      "bucket": "2026-03-15 00:00:00",
      "max_concurrency": "48",
      "total_count": "1542"
    }
  ]
}

---

GET /analytics/domains

Domain breakdown — top domains by bytes or request count.

Query params:

Param	Type	Required	Default	Description
from	string	yes		Start date (ISO 8601)
to	string	yes		End date (ISO 8601)
sortBy	string	no	bytes	Sort by: bytes or count
limit	number	no	30	Max results (1–100)
orderId	string	no		Filter by order (hashid)

Response:

{
  "data": [
    {
      "domain": "google.com",
      "total_count": "5420",
      "bytes_total": "268435456",
      "total_bytes_sent": "5242880",
      "total_bytes_received": "263192576",
      "total_errors": "12"
    }
  ]
}

---

GET /analytics/errors

Error breakdown grouped by error type.

Query params:

Param	Type	Required	Default	Description
from	string	yes		Start date (ISO 8601)
to	string	yes		End date (ISO 8601)
domain	string	no		Filter by exact domain
orderId	string	no		Filter by order (hashid)
limit	number	no	50	Max results (1–100)

Response:

{
  "data": [
    {
      "error": "ECONNREFUSED",
      "total_errors": "142",
      "first_seen": "2026-02-01 08:15:00",
      "last_seen": "2026-03-19 22:45:00",
      "sample_domains": ["google.com", "facebook.com", "github.com"]
    }
  ]
}

---

GET /analytics/websites

Visited websites — paginated list of distinct domains.

Query params:

Param	Type	Required	Default	Description
from	string	yes		Start date (ISO 8601)
to	string	yes		End date (ISO 8601)
domain	string	no		Filter by exact domain
orderId	string	no		Filter by order (hashid)
page	number	no	1	Page number
limit	number	no	25	Items per page (1–100)

Response:

{
  "data": [
    {
      "domain": "google.com",
      "total_count": "5420",
      "bytes_total": "268435456",
      "first_visit": "2026-02-01 08:15:00",
      "last_visit": "2026-03-19 22:45:00"
    }
  ],
  "page": 1,
  "limit": 25,
  "total": 48,
  "totalPages": 2
}