---
title: "Edge traffic for one domain"
method: GET
path: "/connections/{id}/traffic"
tags: ["Analytics"]
---

# Edge traffic for one domain

`GET /connections/{id}/traffic`

## Request

- Base URL: `https://api.customdomain.ai/v1`
- URL: `https://api.customdomain.ai/v1/connections/{id}/traffic`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://api.customdomain.ai/oauth/agent/authorize`, token URL `https://api.customdomain.ai/oauth/agent/token`, scopes: `domains:read`)

What the edge served for one connected domain: requests by status class, bytes relayed to visitors, the origin's time to first byte (p50, p95, p99 and mean over the requests that reached it) and approximate unique visitors, as a series with totals, plus when the edge last served a request for it. `serving` says whether the domain's visitors reach the edge at all: `live` and `verifying` are served by the edge; `not_live` will be once the domain is live; `dns_only` means its records point somewhere other than the edge (it was connected for DNS only), so its traffic never passes through CustomDomain™ and there is nothing to count. Visitors are estimated from a sketch of keyed hashes of client addresses; no address is stored, and a visitor seen on two UTC days counts once on each. A tenant API key reads a domain of any application in its tenant; a widget token minted with scope `app` (or a delegated agent token) reads its own application's domains; an end user's connect-scoped widget token is refused.

A delegated agent token needs `domains:read`.

## Path parameters

- `id` string, required

## Query parameters

- `range` '24h' | '7d' | '30d' | '90d'

## Response `200`

Domain traffic

- ConnectionTraffic
  - `connection_id` string, required
  - `domain` string, required
  - `range` '24h' | '7d' | '30d' | '90d', required
  - `granularity` 'hour' | 'day', required
  - `from` string, date-time, required: Start of the first bucket.
  - `to` string, date-time, required: End of the last bucket (exclusive); the last bucket is the current one.
  - `serving` object, required
    - `through_edge` boolean, required: Whether this domain's visitors reach the edge.
    - `reason` 'live' | 'verifying' | 'not_live' | 'dns_only', required
  - `last_request_at` string, date-time, nullable, required: End of the last minute in which the edge served this domain; null when never (within retention).
  - `totals` object, required
    - `requests` integer, required
    - `status` TrafficStatusCounts, required: Requests by the status class of the answer the visitor got.
      - `1xx` integer, required: Mostly 101 Switching Protocols (websockets).
      - `2xx` integer, required
      - `3xx` integer, required: Includes the edge's own redirects (redirect_to and the www redirect).
      - `4xx` integer, required: Includes 421 answered by the edge when the domain has no origin set.
      - `5xx` integer, required: Includes 502 answered by the edge when the origin could not be reached.
    - `bytes_out` integer, required: Response body bytes relayed to visitors.
    - `error_rate` number, required: Share of requests answered with a 5xx, 0 to 1.
    - `latency_ms` TrafficLatency, required: The origin's time to first response byte, in milliseconds, over the requests that reached it.
      - `p50` number, required
      - `p95` number, required
      - `p99` number, required: Estimated from a fixed histogram; anything slower than 10 seconds reads as 10000.
      - `mean` number, required
      - `samples` integer, required
    - `visitors` integer, required: Approximate unique visitors; one seen on two UTC days counts once on each.
  - `series` object[], required
    - `t` string, date-time, required: Bucket start.
    - `requests` integer, required
    - `status` TrafficStatusCounts, required: Requests by the status class of the answer the visitor got.
      - `1xx` integer, required: Mostly 101 Switching Protocols (websockets).
      - `2xx` integer, required
      - `3xx` integer, required: Includes the edge's own redirects (redirect_to and the www redirect).
      - `4xx` integer, required: Includes 421 answered by the edge when the domain has no origin set.
      - `5xx` integer, required: Includes 502 answered by the edge when the origin could not be reached.
    - `bytes_out` integer, required
    - `error_rate` number, required
    - `latency_ms` TrafficLatency, required: The origin's time to first response byte, in milliseconds, over the requests that reached it.
      - `p50` number, required
      - `p95` number, required
      - `p99` number, required: Estimated from a fixed histogram; anything slower than 10 seconds reads as 10000.
      - `mean` number, required
      - `samples` integer, required
    - `visitors` integer, required
  - `retention` TrafficRetention, required
    - `hourly_days` integer, required: How long hourly figures are kept.
    - `daily_days` integer, required: How long daily figures are kept.

## Other responses

- `400`: Error envelope: {code, title, details}.
- `401`: Error envelope: {code, title, details}.
- `403`: Error envelope: {code, title, details}.
- `404`: Error envelope: {code, title, details}.
- `503`: Error envelope: {code, title, details}.

---

[API](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api.md) · [All operations](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api/llms.txt) · [OpenAPI document](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api/revisions/34d89cb7a7cd?raw)