Skip to content
nsin nsin nsin Docs

Cache hit, miss and bypass counts

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

hit_rate is hits / (hits + misses) — bypasses are excluded from the denominator, since a bypassed request was never a caching candidate. bypass_reasons breaks down why requests bypassed the cache.

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 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.

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 ”

Cache counters.

Media type application/json
object
hits
integer
misses
integer
bypass
integer
hit_rate

hits / (hits + misses); 0 when there were no cache lookups.

number
bypass_reasons

Why requests bypassed the cache, by reason.

object
key
additional properties
integer
Example generated
{
  "hits": 1,
  "misses": 1,
  "bypass": 1,
  "hit_rate": 1,
  "bypass_reasons": {
    "additionalProperty": 1
  }
}

400

Section titled “400 ”

The domain query parameter is missing.

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 missing 
{
  "error": "domain is required"
}

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

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