The files that used the most bytes

GET

/analytics/top-files

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

The paths (without query string) that sent the most bytes, with their share of the window’s billable bytes and their request counts. Under a wildcard record (*.example.com) a file is reported with the real host it was requested on when the origin request named it.

Figures come from per-hour sketches of the top 100 files per hostname and are estimates (approx is always true; bytes_error bounds each one). The window is whole UTC hours: a Tehran day’s first half hour rounds down, at both ends. Files are kept 35 days: a window reaching further back is cut to the last 35 days (clamped: true). Until the sketches cover the window, a window of one day is read from the request log (slower) and a longer one answers available: false with no items.

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.

limit

integer

default: 20 >= 1 <= 100

How many files to return.

Responses

200

Files 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

approx

required

The figures come from sketches and are estimates.

boolean

available

required

false when the window cannot be answered (files are kept 35 days; see the endpoint); items is then empty.

boolean

clamped

required

The window reached past the last 35 days and was cut to them.

boolean

total_bytes

required

Billable bytes of the same hour-aligned window, the denominator of share.

integer

items

required

Most bytes first.

Array<object>

object

host

required

The host the file was requested on. Under a wildcard record this is the real host when the origin request named it, else the record.

string

record

required

The hostname value it was logged under (with the most of its bytes).

string

path

required

The path without query string or fragment, cut to 300 characters.

string

bytes

required

Estimated egress bytes (the sketch’s count).

integer

bytes_error

required

The sketch’s error bound on bytes.

integer

share

required

bytes / total_bytes, a fraction 0–1.

number

requests

required

Estimated requests; null when the file is not in the request sketch.

integer | null

avg_bytes

required

bytes / requests; null with requests.

integer | null

Example

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

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"
}