Clients whose traffic resembles a proxy tunnel

GET

/analytics/tunnel-suspects

const url = 'https://api.nsin.cloud/analytics/tunnel-suspects?period=3h';
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.cloud/analytics/tunnel-suspects?period=3h' \
  --header 'Authorization: Bearer <token>'

Clients whose WebSocket/gRPC traffic looks like a VPN or proxy tunnel run behind the CDN: sustained volume over a single fixed path, with opaque payloads and no sign of ordinary browsing (no real assets fetched, no referer).

This is a heuristic for investigation, not proof of abuse. balance is informational — tunnels used for browsing are download-heavy, so symmetry is not a criterion.

Authorizations

bearerAuth
apiKeyAuth

Parameters

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

200

Suspected tunnel clients.

application/json

object

suspects

Array<object>

object

remote_addr

string

network

The client’s network operator (AS organisation).

string

country

string

hostname

string

transport

string

Allowed values: ws grpc xhttp http

reqs

All requests from this client to this host.

integer

tunnel_reqs

Requests with opaque payloads.

integer

tunnel_paths

Distinct paths used — around 1 for a tunnel.

integer

Client-to-edge bytes.

integer

down

Edge-to-client bytes.

integer

balance

min/max of up and down. Informational only.

number

max_secs

Longest single connection, in seconds.

integer

sample_path

The heaviest single path.

string

ja4

TLS fingerprint.

string

ja4h

HTTP fingerprint.

string

Example

{
  "suspects": [
    {
      "transport": "ws"
    }
  ]
}

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.

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

invalidKey

{
  "error": "invalid API key"
}

429

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

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.

string

Examples

limited

{
  "error": "rate limit exceeded"
}

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.

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.

string

Examples

unavailable

{
  "error": "analytics unavailable"
}