Raw request logs

GET

/analytics/logs

const url = 'https://api.nsin.cloud/analytics/logs?domain=example.com&period=3h&limit=100&offset=0&cache=hit&reqStatus=cache&threat=waf&md=converted';
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/logs?domain=example.com&period=3h&limit=100&offset=0&cache=hit&reqStatus=cache&threat=waf&md=converted' \
  --header 'Authorization: Bearer <token>'

Individual request records, newest first, with every filter applied as an AND. Requires a plan including the logs feature.

Header and body fields are retained for a shorter window than the rest of the row, so older entries return them empty.

Authorizations

bearerAuth
apiKeyAuth

Parameters

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.

limit

integer

default: 100 >= 1 <= 500

Rows per page, 1–500. Values outside the range fall back to 100.

offset

integer

status

string

One exact status code (404), or a whole class written 4xx / 5xx, which matches 400-499 / 500-599. Only the first character of an xx value is read, and it goes into the query as a digit: a non-digit there is not rejected, it breaks the query and the endpoint answers 500.

method

string

HTTP method — case-insensitive.

uri

string

Substring of the request URI. The stored URI is percent-encoded exactly as the client sent it, and the filter tries both the raw column and its decoded form, so a readable non-ASCII string and its already-encoded equivalent find the same rows.

cache

string

Allowed values: hit miss bypass

Cache status: hit, miss or bypass.

reqStatus

string

Allowed values: cache proxied direct

Serving path: cache, proxied or direct.

rayId

string

Exact ray id of a single request.

hostname

string

Exact host, a subdomain of it, or a bare subdomain label.

originHost

string

Case-insensitive substring of the Host header the edge sent upstream. Matched inside the JSON of the edge-to-origin request headers, under that key specifically, so another header carrying the same text cannot produce a false hit.

originSni

string

Case-insensitive substring of the SNI presented to the origin, read the same way as originHost - from the Nsn-Origin-Sni key of the origin request headers.

originAddr

string

Substring of the resolved origin address the edge connected to. It is stored as ip:port, so a bare 1.2.3.4 also matches 1.2.3.4:443.

originAddrs

string

Comma-separated list, OR’d together - but despite the name this is not the plural of originAddr. Each value is matched as a case-insensitive substring anywhere in the origin request-header JSON, not against the origin address column, so a value can hit on a header that is not an address at all.

remoteAddr

string

Substring of the visitor’s IP, so a prefix like 10.0. or a partial IPv6 address works.

country

string

Visitor country, derived from the client IP, as an exact ISO 3166-1 alpha-2 code. Upper-cased for you, so ir and IR are the same filter.

nodeCountry

string

ISO country of the edge node that served the request. Resolved against the node inventory first and then matched on those node names, so a country with no nodes returns an empty page rather than an error.

node

string

Edge node name, from name in GET /analytics/nodes. Matched exactly, case-insensitively, and never as a substring: ir does not also match ir-2.

threat

string

Allowed values: waf bot action any

waf is any request that scored above zero, bot any request classified as a bot, action any request a detection rule acted on, and any the union of the three. An unrecognised value applies no filter at all rather than erroring, so a typo returns everything.

detectAction

string

The action a detection rule took, matched exactly against the lower-cased action name - unless the value contains a %, which turns it into a SQL LIKE pattern.

botKind

string

Substring of the classified bot kind, case-sensitive.

wafRuleId

string

Substring of the row’s fired-rule-id list, not an exact id match, so 94 also matches a row that fired 942100. Pass the whole id.

headerSearch

string

Case-insensitive substring across the captured client request headers only. The origin request, origin response and client response headers are not searched.

uriPatterns

string

Comma-separated URI globs, OR’d against each other while every other filter is AND’d. * is the wildcard; a pattern without one matches as a prefix, so /api means “starts with /api” and never “contains /api”.

recordId

integer

Narrow to one proxied DNS record. A value that is not a number is ignored rather than rejected, so a typo silently widens the result back to the whole domain.

string

Allowed values: converted failed any

Markdown-for-Agents view. converted keeps requests whose response was converted, failed those where a conversion was attempted and failed, any either. Unrecognised values apply no filter.

Responses

200

A page of request logs.

application/json

object

data

Array<object>

One request. Header and body fields are retained for a shorter window than the rest of the row, so older entries return them empty.

object

domain_id

integer

timestamp

string format: date-time

hostname

string

method

string

uri

Percent-encoded exactly as the client sent it.

string

status

Status returned to the visitor.

integer

remote_addr

string

country

string

duration

Total request duration in ms. For WebSockets this spans the whole connection.

number

bytes_in

integer

bytes_out

integer

cache_status

string

Allowed values: hit miss bypass

bypass_reason

string

req_status

string

Allowed values: cache proxied direct

user_agent

string

headers

Request headers as captured by the edge.

string

origin_req_headers

Headers the edge sent to the origin.

string

origin_headers

Headers the origin returned.

string

client_resp_headers

Headers returned to the visitor.

string

body

string

is_ws

boolean

content_type

string

error

string

node

Edge node that served the request.

string

ray_id

Unique id for this request.

string

protocol

Client-to-edge protocol, e.g. HTTP/2.0.

string

origin_protocol

Edge-to-origin protocol. Empty on a cache hit.

string

origin_status

Status the origin returned. 0 on a cache hit.

integer

origin_error_body

Bounded prefix of the body the origin sent with a 5xx, which the edge replaced with an error page.

string

origin_addr

Origin IP:port the edge connected to.

string

tls_version

string

tls_cipher

string

tls_resumed

boolean

content_encoding

string

referer

string

cache_age

Seconds the served object had been cached.

integer

asn

integer

asn_org

string

bot_kind

Bot classification, when the request was identified as one.

string

bot_verified

Whether the bot’s identity was verified, rather than merely claimed.

boolean

detect_action

Action a detection rule took.

string

detect_dry_run

True when the rule was in dry-run, so nothing was enforced.

boolean

waf_score

WAF anomaly score.

integer

waf_rule_ids

CRS rule ids that fired.

string

ja4

string

ja4h

string

md_converted

The response was served as Markdown.

boolean

md_tokens

integer

orig_tokens

integer

md_fail_reason

string

total

Rows matching the filters, before paging.

integer

limit

integer

offset

integer

Example

{
  "data": [
    {
      "cache_status": "hit",
      "req_status": "cache"
    }
  ]
}

400

The domain query parameter is missing.

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

missing

{
  "error": "domain is required"
}

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.

string

Examples

invalidKey

{
  "error": "invalid API key"
}

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

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

404

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

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