---
title: "Get traffic breakdown for proxy usage"
method: POST
path: "/v1/proxy/analytics/traffic"
tags: ["Analytics"]
---

# Get traffic breakdown for proxy usage

`POST /v1/proxy/analytics/traffic`

## Request

- Base URL: `https://api.platform.soax.com`
- URL: `https://api.platform.soax.com/v1/proxy/analytics/traffic`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/soax/apis/soax-api/docs/v1/proxy/analytics/traffic/post.ts> (a function with typed inputs; its response is checked against the schema)

Retrieve traffic (in GB) grouped by a dimension (`package`, `proxy_type`, `tier`, `country`, `domain`, or `ingress_ip`), as a series of interval buckets. When `group_by=package`, keys are package names. The date range may span at most 365 days. If `interval` is omitted it is chosen automatically from the range (< 24 h → `hour`, < 60 days → `day`, otherwise `month`). Explicit intervals are validated: `hour` needs a range of at most 24 hours, `day` between 24 hours and 180 days, `month` at least 60 days.

If the API key is restricted to specific packages, results (and any `package_ids` filter) are limited to those packages.

Requires the `proxy:analytics:read` scope.

## Request body

- TrafficRequest: Request model for traffic breakdown analysis.
  - `from_date` string, date-time, required: Start of the query range (ISO 8601).
  - `to_date` string, date-time, required: End of the query range (ISO 8601). At most 365 days after `from_date`.
  - `group_by` 'package' | 'proxy_type' | 'tier' | 'country' | 'domain' | 'ingress_ip': Allowed grouping dimensions for analytics queries.
  - `interval` 'hour' | 'day' | 'month': Allowed time intervals for analytics aggregation.
  - `package_ids` string[], nullable: Restrict results to these package IDs.
  - `network_types` string[], nullable: Restrict results to network types: `residential` and/or `mobile`.
  - `tiers` integer[], nullable: Restrict results to tiers (1, 2, or 3).
  - `countries` string[], nullable: Restrict results to these ISO country codes.
  - `target_addresses` string[], nullable: Restrict results to traffic sent to these domains.

## Response `200`

Successful Response

- TrafficResponseItem[]
  - `data` TrafficDataPoint[], required
    - `key` string, required
    - `value` number, required

## Other responses

- `400`: A parameter value or combination is invalid. Service-level validation errors use the `error` key; endpoint-level checks use `detail`. Read `detail ?? error`.
- `401`: Missing, invalid, or revoked API key.
- `403`: The API key does not carry the scope this endpoint requires.
- `422`: Validation Error
- `429`: Rate limit exceeded (5 requests/second per API key, 500 requests/minute per IP). The response includes `Retry-After` (seconds), `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` (Unix time) headers — wait `Retry-After` seconds and retry.

---

[API](https://skmtc.dev/soax/apis/soax-api.md) - [All operations](https://skmtc.dev/soax/apis/soax-api/llms.txt) - [OpenAPI document](https://skmtc.dev/soax/apis/soax-api/revisions/2abdaa934277?raw)