Traffic across my whole tenancy

GET

/reseller/v1/analytics/overview

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

• Production

Per-domain traffic for every domain across every client, plus the roll-up over all of them.

Both halves come back in one response on purpose: the dashboard shows the totals as headline figures and the rows as the table underneath, and two endpoints would guarantee the two disagree whenever a request lands between the calls.

totals.unique_visitors is not the sum of the per-domain figures. Distinct visitor counts do not add — one person browsing three of your sites is one visitor — so it is computed over the whole tenancy.

Authorizations

• bearerAuth

Parameters

Query Parameters

period

string

default: 24h

Allowed values: 3h 6h 12h 24h 7d 30d

Look-back window. Anything unrecognised is treated as 24h rather than rejected, so a dashboard cannot break itself with a stale value.

Responses

200

Per-domain rows and the tenancy roll-up

Media type application/json

object

data

required

Array<object>

One domain’s traffic in the requested period.

object

domain_id

required

integer

domain_name

required

string

total_requests

required

integer

total_bandwidth

required

Bytes served to visitors.

integer

unique_visitors

required

Distinct (client IP, JA4 TLS fingerprint) pairs. Pairing the two separates people sharing one CGNAT address by device stack; on plain HTTP it degrades to counting IPs.

integer

error_rate

Percentage of this domain’s responses with status >= 400.

number

latest_event

When this domain last served a request in the window, or null if it served none. null is a real answer — “silent” — and a caller must not render it as a date it invented.

string format: date-time

nullable

series

Requests per bucket, oldest first, for a sparkline. Present but empty for a domain with no traffic; a caller must draw nothing rather than a flat line along zero, which reads as measured silence when it may be an unanswered question.

Array<object>

One time bucket of request counts.

object

timestamp

required

Bucket start, server-local, YYYY-MM-DD HH:MM:SS or ISO-8601.

string

count

required

integer

totals

required

The roll-up across every domain of every client.

object

domains

required

How many domains the figures cover.

integer

total_requests

required

integer

total_bandwidth

required

integer

unique_visitors

required

Computed over the whole tenancy, NOT summed from the rows: one person browsing three of your sites is one visitor.

integer

error_rate

required

Percentage of responses with status >= 400.

number

Example

{
  "data": [
    {
      "domain_name": "shop.example.ir"
    }
  ]
}

401

Missing, malformed, expired, or revoked credential.

Media type application/json

Every error body carries error, a human-readable sentence. Some also carry code, a stable machine-readable reason — branch on that, never on the sentence, which is prose and gets reworded.

object

error

required

string

code

Present only on the failures worth branching on, and deliberately not an exhaustive enum: treat a code you do not recognise as if it were absent and fall back to the status code.

The ones that exist today:

• credit_limit_reached — 402 from POST /services and POST /services/{serviceId}/change-plan. Your wallet, not the client’s: funding the purchase would take you past your overdraft (default 0, i.e. past zero). Top up; do not credit the client.
• domain_disabled — 409 from a configuration write on a disabled domain (records, rules, cache, SSL, members, settings). The domain is read-only until POST /domains/{domainId}/enable.
• unknown_rule_type — 404 from the rules paths when ruleType is not one of the documented values. You get this rather than an empty array, so a typo cannot read as a rule set that happens to be empty.
• rate_limited — 429 from any route. Keyed per credential, so one runaway integration cannot lock its owner out of the dashboard.
• session_check_failed — 503, and only on calls made with a dashboard session JWT. The session could not be verified, which is not the same as knowing it is revoked, so it is retryable and the session survives. Machine tokens never see this.

string

Example

{
  "error": "forbidden",
  "code": "credit_limit_reached"
}

403

Authenticated, but the target does not belong to you — or you are not a reseller at all.

This is the response the tenant-isolation matrix asserts on. Every route in this document is called with reseller B’s credential against reseller A’s ids, and must answer 403 or 404 with none of A’s data in the body.

Media type application/json

Every error body carries error, a human-readable sentence. Some also carry code, a stable machine-readable reason — branch on that, never on the sentence, which is prose and gets reworded.

object

error

required

string

code

Present only on the failures worth branching on, and deliberately not an exhaustive enum: treat a code you do not recognise as if it were absent and fall back to the status code.

The ones that exist today:

• credit_limit_reached — 402 from POST /services and POST /services/{serviceId}/change-plan. Your wallet, not the client’s: funding the purchase would take you past your overdraft (default 0, i.e. past zero). Top up; do not credit the client.
• domain_disabled — 409 from a configuration write on a disabled domain (records, rules, cache, SSL, members, settings). The domain is read-only until POST /domains/{domainId}/enable.
• unknown_rule_type — 404 from the rules paths when ruleType is not one of the documented values. You get this rather than an empty array, so a typo cannot read as a rule set that happens to be empty.
• rate_limited — 429 from any route. Keyed per credential, so one runaway integration cannot lock its owner out of the dashboard.
• session_check_failed — 503, and only on calls made with a dashboard session JWT. The session could not be verified, which is not the same as knowing it is revoked, so it is retryable and the session survives. Machine tokens never see this.

string

Example

{
  "error": "forbidden",
  "code": "credit_limit_reached"
}

500

Something failed on our side. The body carries a human sentence and never an internal detail — a live sweep of this API once returned dial tcp 127.0.0.1:9000: connect: connection refused, which is our topology rather than an error message. That is now impossible.

Distinguish it from 503. A 503 means a dependency is down and the identical request will succeed later, so retry it. A 500 means the request hit a genuine fault: retrying it unchanged will fail the same way, and it should be reported with the X-Request-Id from the response header.

Declared on every operation because every operation can reach it. It was previously declared on exactly one, which left a generated client with no branch for the answer it is most likely to be surprised by.

Media type application/json

Every error body carries error, a human-readable sentence. Some also carry code, a stable machine-readable reason — branch on that, never on the sentence, which is prose and gets reworded.

object

error

required

string

code

Present only on the failures worth branching on, and deliberately not an exhaustive enum: treat a code you do not recognise as if it were absent and fall back to the status code.

The ones that exist today:

• credit_limit_reached — 402 from POST /services and POST /services/{serviceId}/change-plan. Your wallet, not the client’s: funding the purchase would take you past your overdraft (default 0, i.e. past zero). Top up; do not credit the client.
• domain_disabled — 409 from a configuration write on a disabled domain (records, rules, cache, SSL, members, settings). The domain is read-only until POST /domains/{domainId}/enable.
• unknown_rule_type — 404 from the rules paths when ruleType is not one of the documented values. You get this rather than an empty array, so a typo cannot read as a rule set that happens to be empty.
• rate_limited — 429 from any route. Keyed per credential, so one runaway integration cannot lock its owner out of the dashboard.
• session_check_failed — 503, and only on calls made with a dashboard session JWT. The session could not be verified, which is not the same as knowing it is revoked, so it is retryable and the session survives. Machine tokens never see this.

string

Example

{
  "error": "forbidden",
  "code": "credit_limit_reached"
}

503

The analytics store (ClickHouse) is unreachable.

Deliberately an error rather than a zeroed page: a page of zeros is indistinguishable from “your customers’ traffic stopped”, and someone would act on it.

Media type application/json

Every error body carries error, a human-readable sentence. Some also carry code, a stable machine-readable reason — branch on that, never on the sentence, which is prose and gets reworded.

object

error

required

string

code

Present only on the failures worth branching on, and deliberately not an exhaustive enum: treat a code you do not recognise as if it were absent and fall back to the status code.

The ones that exist today:

• credit_limit_reached — 402 from POST /services and POST /services/{serviceId}/change-plan. Your wallet, not the client’s: funding the purchase would take you past your overdraft (default 0, i.e. past zero). Top up; do not credit the client.
• domain_disabled — 409 from a configuration write on a disabled domain (records, rules, cache, SSL, members, settings). The domain is read-only until POST /domains/{domainId}/enable.
• unknown_rule_type — 404 from the rules paths when ruleType is not one of the documented values. You get this rather than an empty array, so a typo cannot read as a rule set that happens to be empty.
• rate_limited — 429 from any route. Keyed per credential, so one runaway integration cannot lock its owner out of the dashboard.
• session_check_failed — 503, and only on calls made with a dashboard session JWT. The session could not be verified, which is not the same as knowing it is revoked, so it is retryable and the session survives. Machine tokens never see this.

string

Example

{
  "error": "forbidden",
  "code": "credit_limit_reached"
}