Run a custom query over your request logs

POST

/analytics/query

const url = 'https://api.nsin.cloud/analytics/query';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"sql":"SELECT toStartOfHour(event_time) AS h, count() AS c FROM requests WHERE status >= 500 GROUP BY h ORDER BY h"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.nsin.cloud/analytics/query \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "sql": "SELECT toStartOfHour(event_time) AS h, count() AS c FROM requests WHERE status >= 500 GROUP BY h ORDER BY h" }'

Runs a read-only SQL SELECT against the requests table — your raw request log — for analyses the dedicated endpoints do not cover.

Scoping is enforced by the database engine, not by your query: a filter restricting rows to the domains this key can access is appended to every read of requests. You cannot read another account’s traffic, however the query is written.

Restrictions:

A single statement only, starting with SELECT or WITH.
Only the requests table may be read. Common table expressions you define yourself are fine; other tables and any db.table reference are rejected.
Writes, DDL and settings changes are rejected.
Execution is capped at 30 seconds and 10 000 returned rows — truncated tells you when the cap was hit.

Useful requests columns: event_time, domain_id, hostname, method, uri, status, bytesIn, bytesOut, duration (ms), remoteAddr, country, asn, asnOrg, userAgent, cacheStatus, reqStatus, isWS, protocol, referer, originStatus, originAddr, error.

Authorizations

bearerAuth
apiKeyAuth

Request Body^required

application/json

object

sql

required

The query to run.

string

Responses

200

Query result.

application/json

object

columns

Column names, in result order.

Array<string>

rows

One entry per row, keyed by column name.

Array<object>

object

key

additional properties

any

row_count

integer

truncated

True when the 10 000-row cap was reached and results were cut short.

boolean

Example ^generated

{
  "columns": [
    "example"
  ],
  "rows": [
    {}
  ],
  "row_count": 1,
  "truncated": true
}

400

The query was rejected by validation, or the database refused it. detail carries the underlying message when the engine rejected it.

application/json

object

error

string

detail

string

Examples

disallowedTable

{
  "error": "querying \"system.parts\" is not allowed; only the 'requests' table may be read"
}

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

403

Read-only key, or the account has no domains whose logs could be queried.

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

Example

{
  "error": "read-only 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"
}

Run a custom query over your request logs

Authorizations

Request Body required

Responses

200

Example generated

400

Examples

401

Examples

403

Example

429

Examples

503

Examples

Request Body^required

Example ^generated