What used the traffic, by one dimension

GET

/analytics/breakdown

const url = 'https://api.nsin.ir/analytics/breakdown?domain=example.com&range=today&from=2026-09-21&to=2026-09-27&hostname=*.example.com&dim=host&limit=10';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.nsin.ir/analytics/breakdown?domain=example.com&range=today&from=2026-09-21&to=2026-09-27&hostname=*.example.com&dim=host&limit=10' \
  --header 'Authorization: Bearer <token>'

The domain’s traffic over the window broken down by one dimension, ranked by bytes:

host — hostnames, billable bytes (kept 400 days).
content_type — response Content-Type without parameters, billable bytes; a response without one is "", labelled (none).
country — visitor country (ISO code), all egress bytes.
asn — visitor network (AS number, labelled with its name), all egress bytes.
status — HTTP status code, all egress bytes.
client — client IP, labelled network · country, all egress bytes. The top clients are picked with a sketch (approx: true) and then counted exactly. Requires the logs feature as well (403 without it).

Every dimension but host is kept 35 days (client 34): a window reaching further back is cut (clamped: true). Until a dimension’s rollup covers the window, a window of one day is read from the request log and a longer one answers available: false. total_bytes is always the window’s billable bytes.

Requires analytics.view on the domain and a plan with the monitoring feature. Cached like traffic-trend.

Authorizations

bearerAuth
apiKeyAuth

Parameters

Query Parameters

domain

required

string

The domain name (for example example.com). These endpoints take the domain as a query parameter rather than a path segment.

Example

example.com

range

string

default: 7d

Allowed values: today 7d 30d 90d custom

The window, in whole Asia/Tehran days (UTC+03:30), ending today: today is today so far, 7d today and the 6 days before it, 30d and 90d likewise. custom takes from and to. The window is [Tehran midnight of the first day, min(Tehran midnight after the last day, now)) — a Tehran day starts at 20:30 UTC the evening before.

from

string format: date

Example

2026-09-21

First day of a range=custom window, inclusive: the Gregorian date of an Asia/Tehran calendar day. At most 400 days before today; the window spans at most 400 days. Refused with any other range.

string format: date

Example

2026-09-27

Last day of a range=custom window, inclusive (a Tehran calendar day, YYYY-MM-DD). Not before from, not after today. When it is today the window ends now.

hostname

string

Example

*.example.com

Narrow to one hostname of the domain, as the hostname values these endpoints return (host keys, a file’s record) — for example *.example.com for a wildcard record. Matched exactly, ignoring case; unlike HostnameFilter it does not match subdomains.

dim

required

string

Allowed values: host content_type country asn status client

The dimension.

limit

integer

default: 10 >= 1 <= 50

How many values to return.

Responses

200

Values by bytes.

application/json

object

window

required

The window the answer covers, [from, to): whole Asia/Tehran days. from is the Tehran midnight that starts the first day (20:30 UTC the evening before); to is the Tehran midnight after the last day, or now when the last day is today.

object

from

required

string format: date-time

required

string format: date-time

required

string

Allowed value: Asia/Tehran

days

required

Tehran days in the window, a partial today included.

integer

granularity

required

The bucket size the answer uses. On traffic-trend this is the granularity actually drawn (see its granularity parameter); on the other endpoints it is what auto would pick.

string

Allowed values: hour day

partial_last

required

The last day is today, so to is now and the last bucket is still filling.

boolean

dim

required

string

Allowed values: host content_type country asn status client

approx

required

true for client, whose winners come from a sketch.

boolean

available

required

false when no table covers the window and it is longer than a day; items is then empty.

boolean

clamped

required

The window reached past what the table keeps and was cut to it.

boolean

total_bytes

required

The window’s billable bytes (after any clamp), the denominator of share.

integer

items

required

Most bytes first.

Array<object>

object

key

required

The value: a hostname, a content type ("" for none), an ISO country code, an AS number, an HTTP status code, or a client IP.

string

label

required

What to print: the network’s name for asn, network · country for client, (none) for a missing content type, (unknown) for an unresolved country; the key otherwise.

string

bytes

required

integer

requests

required

integer

share

required

bytes / total_bytes, a fraction 0–1.

number

Example

{
  "window": {
    "from": "2026-09-21T20:30:00Z",
    "to": "2026-09-28T14:20:00Z",
    "tz": "Asia/Tehran",
    "granularity": "hour"
  },
  "dim": "host"
}

400

The domain query parameter is missing, or another parameter is not valid: an unknown range, from/to without range=custom (or missing with it), a date that is not YYYY-MM-DD, to before from or after today, a custom window over 400 days or starting more than 400 days ago, granularity=hour on a window over 7 days, an unknown split, compare, dim, or a limit out of range.

application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Examples

{
  "error": "range must be today, 7d, 30d, 90d or custom"
}

{
  "error": "a custom window spans at most 400 days"
}

{
  "error": "granularity=hour needs a window of 7 days or less"
}

401

Missing, malformed, revoked or expired API key. (A valid key whose account has been deactivated gets 403 account is inactive instead.)

application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Examples

invalidKey

{
  "error": "invalid API key"
}

402

The domain has no active plan at all, so no plan feature is available on it. Buy or renew a plan for the domain. (A plan that is active but does not include the feature answers 403 instead.)

application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Examples

noPlan

{
  "error": "This domain does not have an active plan."
}

403

The domain’s plan does not include the feature this endpoint needs (monitoring for most sections, logs for raw and top-N request data).

application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Example

{
  "error": "read-only API key"
}

404

No such domain, or it is not visible to this account. Domains you cannot access are reported as not found rather than forbidden.

application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Example

{
  "error": "read-only API key"
}

429

The key exceeded its request budget (300 requests per minute by default).

application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Examples

limited

{
  "error": "rate limit exceeded"
}

503

Either the analytics backend is temporarily unreachable (retry; no data is lost), or the answer is still being computed. The per-domain sections and the cached account-wide views (domains-overview, global-summary, global-summary/peak, requests-compare, bandwidth-overview, nodes-overview) wait at most about 25 seconds for their query; past that they answer 503 with pending: true and a Retry-After header, while the query keeps running and caches its result, so the retry is served from that cache instead of starting the same scan again. Identical concurrent requests share one computation.

application/json

object

error

required

Human-readable description of what went wrong.

string

pending

true when the query is still running rather than failing. Retry after Retry-After seconds.

boolean

Examples

{
  "error": "analytics unavailable"
}

{
  "error": "still computing — try again in a few seconds",
  "pending": true
}

Headers

Retry-After

integer

Example

Seconds to wait before retrying. Sent only with pending.

504

The query ran out of time for this period. Retrying the same request runs the same query again, so ask for a shorter period (or narrow it with hostname/path) instead.

application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Examples

timedOut

{
  "error": "summary timed out for this period; try a shorter one"
}