Busiest day and hour, and what changed

GET

/analytics/traffic-highlights

const url = 'https://api.nsin.ir/analytics/traffic-highlights?domain=example.com&range=today&from=2026-09-21&to=2026-09-27&hostname=*.example.com';
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/traffic-highlights?domain=example.com&range=today&from=2026-09-21&to=2026-09-27&hostname=*.example.com' \
  --header 'Authorization: Bearer <token>'

The window’s busiest Asia/Tehran day and busiest UTC hour (each with the hostname that carried most of it), and what changed: up to 5 hosts and files whose billable bytes per day moved the most between “now” — the last N full days of the window — and “before”, the N days right before them, N = min(7, max(1, days / 2)). A change is listed when it is at least 1 GB (1024³ bytes) a day and at least 20% of the domain’s daily average over both periods, biggest move first. Hosts come from the traffic rollups; files from the files sketch, and are left out while it does not cover both periods. today has no full day, so no changes.

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.

Responses

200

Peaks and changes.

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

peak_day

required

One of:

object
null

object

required

Start of the Tehran day (UTC).

string format: date-time

bytes

required

Billable bytes that day.

integer

requests

required

integer

top_host

required

The hostname with the most bytes that day.

string

top_host_bytes

required

integer

peak_hour

required

One of:

object
null

object

required

Start of the UTC hour.

string format: date-time

bytes

required

Billable bytes in that hour.

integer

requests

required

integer

avg_mbps

required

The hour’s average rate: bytes × 8 / 3600 / 10⁶, one decimal.

number

top_host

required

The hostname with the most bytes in that hour.

string

top_host_bytes

required

integer

changes

required

Biggest move first. Empty when nothing moved enough, or the window has no full day.

Array<object>

<= 5 items

A host or file whose bytes per day moved between “before” and “now” (see traffic-highlights).

object

kind

required

string

Allowed values: host file

host

required

The hostname — for a file under a wildcard record, the real host it was requested on (the record itself when that is unknown).

string

record

required

The hostname value the traffic is logged under (a wildcard record: *.example.com).

string

path

required

A file’s path, without query string; empty for a host.

string

bytes_per_day_now

required

Average billable bytes per day over “now”. Files are sketch estimates.

integer

bytes_per_day_before

required

The same over “before”.

integer

delta_per_day

required

bytes_per_day_now − bytes_per_day_before; negative for a decrease.

integer

share_now

required

The item’s share of the domain’s bytes over “now”, a fraction 0–1.

number

first_seen

required

For an increase, the first UTC hour (looking back up to 35 days for a file, 90 for a host) whose bytes reached 10% of the item’s average hourly bytes over “now”. null for a decrease.

string | null format: date-time

Example

{
  "window": {
    "from": "2026-09-21T20:30:00Z",
    "to": "2026-09-28T14:20:00Z",
    "tz": "Asia/Tehran",
    "granularity": "hour"
  },
  "changes": [
    {
      "kind": "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"
}