Egress bytes by cache status over time
const url = 'https://api.nsin.ir/analytics/traffic-by-cache?domain=example.com&period=1h';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-by-cache?domain=example.com&period=1h' \ --header 'Authorization: Bearer <token>'Egress bytes and request counts per time bucket, split by cache status
(hit, miss, bypass). Compute a hit ratio from the request counts:
hits are small and misses large, so a bytes split understates it. Accepts
node to narrow to one edge node. Requires analytics.view and a plan
with monitoring.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Query Parameters
Section titled “Query Parameters ”The domain name (for example example.com). These endpoints take the
domain as a query parameter rather than a path segment.
Example
example.comTime window, ending now. Time series are bucketed by minute for 1h,
by hour up to 48h, and by day for 7d and 30d. Buckets are cut on
Asia/Tehran (UTC+03:30) boundaries and emitted as UTC instants, so an
hourly bucket starts at :30 UTC. An unrecognised value falls back to
24h.
Narrow to one subdomain. Matches the exact host, any subdomain of it, or
a bare label — so example.com matches api.example.com, and api
matches api.example.com, but exam matches neither.
Narrow to a URL path prefix.
Narrow to one edge node. Use name from GET /analytics/nodes.
Responses
Section titled “ Responses ”Time series.
object
One time bucket of traffic split by cache status. Bytes are egress to visitors; the request counts are the same buckets counted in requests, which is what a hit ratio should be computed from — hits are small and misses large, so a bytes split understates it.
object
Start of the bucket (UTC).
Egress bytes of responses served from cache (cache status hit).
Egress bytes of responses that missed the cache and came from the origin.
Egress bytes of responses that bypassed the cache.
Requests answered from cache.
Requests that missed the cache and went to the origin.
Requests that bypassed the cache.
Example generated
{ "data": [ { "timestamp": "2026-04-15T12:00:00Z", "cached_bytes": 1, "miss_bytes": 1, "bypass_bytes": 1, "hit_requests": 1, "miss_requests": 1, "bypass_requests": 1 } ]}The domain query parameter is missing.
The single error shape used by every endpoint.
object
Human-readable description of what went wrong.
Examples
{ "error": "domain is required"}Missing, malformed, revoked or expired API key. (A valid key whose
account has been deactivated gets 403 account is inactive instead.)
The single error shape used by every endpoint.
object
Human-readable description of what went wrong.
Examples
{ "error": "invalid API key"}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.)
The single error shape used by every endpoint.
object
Human-readable description of what went wrong.
Examples
{ "error": "This domain does not have an active plan."}The domain’s plan does not include the feature this endpoint needs
(monitoring for most sections, logs for raw and top-N request data).
The single error shape used by every endpoint.
object
Human-readable description of what went wrong.
Example
{ "error": "read-only API key"}No such domain, or it is not visible to this account. Domains you cannot access are reported as not found rather than forbidden.
The single error shape used by every endpoint.
object
Human-readable description of what went wrong.
Example
{ "error": "read-only API key"}The key exceeded its request budget (300 requests per minute by default).
The single error shape used by every endpoint.
object
Human-readable description of what went wrong.
Examples
{ "error": "rate limit exceeded"}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.
object
Human-readable description of what went wrong.
true when the query is still running rather than
failing. Retry after Retry-After seconds.
Examples
{ "error": "analytics unavailable"}{ "error": "still computing — try again in a few seconds", "pending": true}Headers
Section titled “Headers ”Example
5Seconds to wait before retrying. Sent only with pending.
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.
The single error shape used by every endpoint.
object
Human-readable description of what went wrong.
Examples
{ "error": "summary timed out for this period; try a shorter one"}