Skip to content
nsin nsin nsin Docs

Origin-direction bandwidth across your domains

GET
/analytics/bandwidth-overview
 
curl --request GET \
  --url 'https://api.nsin.cloud/analytics/bandwidth-overview?period=3h' \
  --header 'Authorization: Bearer <token>'

Bytes sent to and received from origins, as a time series plus per-domain totals.

ratio is min(up,down) / max(up,down). A value near 1.0 means the domain pushes about as much to the origin as it pulls back, which is unusual for web traffic (downloads normally dominate) and sets flagged.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters ”
period
string
default: 24h
Allowed values: 3h 6h 12h 24h 7d 30d

Time window, ending now. Buckets are hourly up to 24h and daily for 7d and 30d. An unrecognised value falls back to 24h.

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Bandwidth series and per-domain totals.

Media type application/json
object
series
Array<object>
object
timestamp
string format: date-time
up

Bytes sent to the origin.

integer
down

Bytes received from the origin.

integer
domains
Array<object>
object
domain
string
up
integer
down
integer
ratio

min(up,down) / max(up,down).

number
flagged

Set when ratio is close to 1.0, which is unusual for web traffic.

boolean
Example generated
{
  "series": [
    {
      "timestamp": "2026-04-15T12:00:00Z",
      "up": 1,
      "down": 1
    }
  ],
  "domains": [
    {
      "domain": "example",
      "up": 1,
      "down": 1,
      "ratio": 1,
      "flagged": true
    }
  ]
}

401

Section titled “401 ”

Missing, malformed, revoked or expired API key, or a key whose owning user row is gone. A key whose owning account has merely been deactivated is not this: that is 403 with code: account_suspended, because the credential itself is intact and re-issuing it changes nothing.

Media type application/json

The error shape used by every endpoint. error is always present. code is present only on the failures that have one — do not require it, and do not parse error to recover it.

object
error
required

Human-readable description of what went wrong.

string
code

Stable machine-readable reason. Present on some failures only; the wording of error may change, this will not.

  • account_suspended — 403. The account behind the credential has been switched off, by an admin or by its provider. Every authenticated route answers this, so treat it as terminal rather than retrying.
  • domain_disabled — 409, not 403. You have every right to the operation; the domain is simply switched off and is not being served, so its configuration cannot change. It stays readable, and writes work again once it is enabled.
  • managed_by_reseller — 403. The account is a reseller’s client and this surface belongs to its provider. See If your account is managed by a reseller.
  • invite_email_mismatch — 403 from POST /invites/{token}/accept. The invitation was addressed to a different email; the body also carries invited_email, masked.

A panel session — not an API key — can additionally see session_check_failed on a 503, which means the session could not be verified, not that it is invalid. Retry it; do not discard the token.

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

429

Section titled “429 ”

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

Media type application/json

The error shape used by every endpoint. error is always present. code is present only on the failures that have one — do not require it, and do not parse error to recover it.

object
error
required

Human-readable description of what went wrong.

string
code

Stable machine-readable reason. Present on some failures only; the wording of error may change, this will not.

  • account_suspended — 403. The account behind the credential has been switched off, by an admin or by its provider. Every authenticated route answers this, so treat it as terminal rather than retrying.
  • domain_disabled — 409, not 403. You have every right to the operation; the domain is simply switched off and is not being served, so its configuration cannot change. It stays readable, and writes work again once it is enabled.
  • managed_by_reseller — 403. The account is a reseller’s client and this surface belongs to its provider. See If your account is managed by a reseller.
  • invite_email_mismatch — 403 from POST /invites/{token}/accept. The invitation was addressed to a different email; the body also carries invited_email, masked.

A panel session — not an API key — can additionally see session_check_failed on a 503, which means the session could not be verified, not that it is invalid. Retry it; do not discard the token.

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

503

Section titled “503 ”

The process holds no ClickHouse client at all - the connection was never opened at startup. It is built once and never rebuilt, so this state lasts until the backend restarts.

It is NOT what you get when the store is merely down, and that is the trap. Startup opens the client and pings it as a separate step; a failed ping is logged and the client is kept, so a ClickHouse that was unreachable at boot still leaves a usable handle behind and this 503 stays rare. Every failure at query time answers 500 instead - the store unreachable, or a query outrunning its timeout of 10s for windows up to 24h, 20s for 7d, 45s for 30d - carrying either {"error": "query failed"} or a “Could not load analytics right now” message.

So retry on 500 exactly as you retry on 503. On the analytics endpoints a 500 nearly always means the store could not answer, not that your request was wrong.

Media type application/json

The error shape used by every endpoint. error is always present. code is present only on the failures that have one — do not require it, and do not parse error to recover it.

object
error
required

Human-readable description of what went wrong.

string
code

Stable machine-readable reason. Present on some failures only; the wording of error may change, this will not.

  • account_suspended — 403. The account behind the credential has been switched off, by an admin or by its provider. Every authenticated route answers this, so treat it as terminal rather than retrying.
  • domain_disabled — 409, not 403. You have every right to the operation; the domain is simply switched off and is not being served, so its configuration cannot change. It stays readable, and writes work again once it is enabled.
  • managed_by_reseller — 403. The account is a reseller’s client and this surface belongs to its provider. See If your account is managed by a reseller.
  • invite_email_mismatch — 403 from POST /invites/{token}/accept. The invitation was addressed to a different email; the body also carries invited_email, masked.

A panel session — not an API key — can additionally see session_check_failed on a 503, which means the session could not be verified, not that it is invalid. Retry it; do not discard the token.

string
Examples
Example unavailable 
{
  "error": "analytics unavailable"
}