Skip to content
nsin docs
EN فا

This period against the one before it

GET
/analytics/overview-compare
 
curl --request GET \
  --url 'https://api.nsin.ir/analytics/overview-compare?domain=example.com&period=3h' \
  --header 'Authorization: Bearer <token>'

Totals for the last period and for the equally long window just before it, each with its status-code breakdown, plus an hourly cache-split series spanning both windows. It is everything a period-over-period overview needs — KPI tiles with deltas, a “previous period” ghost line, a status-class bar — from one request and one scan of the request log, instead of calling summary, cache, status-codes and traffic-by-cache once per window.

Only 3h, 6h, 12h and 24h are accepted; any other period is a 400. The windows are [since, boundary) (previous) and [boundary, now) (current). Series buckets are clock hours in Asia/Tehran (UTC+03:30), emitted as UTC instants, oldest first; the bucket that contains boundary carries traffic from both windows.

Requires analytics.view on the domain and a plan with the monitoring feature. Answers are cached for 2 minutes (3h, 6h) or 5 minutes (12h, 24h) and shared between identical requests.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “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
period
string
default: 24h
Allowed values: 3h 6h 12h 24h

Length of each of the two windows. The previous window is the same length, ending where the current one starts.

hostname
string

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.

path
string

Narrow to a URL path prefix.

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Both windows’ totals and the combined series.

Media type application/json
object
period

The window length that was asked for.

string
Allowed values: 3h 6h 12h 24h
since

Start of the previous window (UTC) — now − 2 × period.

string format: date-time
boundary

Start of the current window and end of the previous one (UTC) — now − period.

string format: date-time
current

One window’s totals in /analytics/overview-compare.

object
requests

Requests served in the window.

integer
bytes

Egress bytes sent to visitors in the window.

integer
hits

Requests with cache status hit.

integer
misses

Requests with cache status miss.

integer
bypass

Requests with cache status bypass.

integer
status_codes

Requests per HTTP status code, busiest first (ties by code).

Array<object>
object
status_code
integer
count
integer
previous

One window’s totals in /analytics/overview-compare.

object
requests

Requests served in the window.

integer
bytes

Egress bytes sent to visitors in the window.

integer
hits

Requests with cache status hit.

integer
misses

Requests with cache status miss.

integer
bypass

Requests with cache status bypass.

integer
status_codes

Requests per HTTP status code, busiest first (ties by code).

Array<object>
object
status_code
integer
count
integer
series

Hourly cache split across both windows, oldest first. Buckets are Asia/Tehran clock hours given as UTC instants; hours with no traffic are absent rather than zero.

Array<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
timestamp

Start of the bucket (UTC).

string format: date-time
cached_bytes

Egress bytes of responses served from cache (cache status hit).

integer
miss_bytes

Egress bytes of responses that missed the cache and came from the origin.

integer
bypass_bytes

Egress bytes of responses that bypassed the cache.

integer
hit_requests

Requests answered from cache.

integer
miss_requests

Requests that missed the cache and went to the origin.

integer
bypass_requests

Requests that bypassed the cache.

integer
Example 
{
  "period": "3h"
}

400

Section titled “400 ”

The domain query parameter is missing, or period is not one of the accepted values.

Media type application/json

The single error shape used by every endpoint.

object
error
required

Human-readable description of what went wrong.

string
Examples
Example badPeriod 
{
  "error": "period must be 3h, 6h, 12h or 24h"
}

401

Section titled “401 ”

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

Media type application/json

The single error shape used by every endpoint.

object
error
required

Human-readable description of what went wrong.

string
Examples
Example invalidKey 
{
  "error": "invalid API key"
}

402

Section titled “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.)

Media type application/json

The single error shape used by every endpoint.

object
error
required

Human-readable description of what went wrong.

string
Examples
Example noPlan 
{
  "error": "This domain does not have an active plan."
}

403

Section titled “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).

Media type 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

Section titled “404 ”

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

Media type 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

Section titled “429 ”

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

Media type application/json

The single error shape used by every endpoint.

object
error
required

Human-readable description of what went wrong.

string
Examples
Example limited 
{
  "error": "rate limit exceeded"
}

503

Section titled “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.

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

Headers

Section titled “Headers ”
Retry-After
integer
Example 
5

Seconds to wait before retrying. Sent only with pending.

504

Section titled “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.

Media type application/json

The single error shape used by every endpoint.

object
error
required

Human-readable description of what went wrong.

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