Cache counters for verified search-engine crawlers

GET

/analytics/bot-cache

const url = 'https://api.nsin.ir/analytics/bot-cache?domain=example.com&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.ir/analytics/bot-cache?domain=example.com&period=3h' \
  --header 'Authorization: Bearer <token>'

The cache section restricted to requests from verified search-engine crawlers (Googlebot, Bingbot, Applebot, DuckDuckBot, YandexBot) — the traffic the domain’s bot cache serves — split per crawler. A spoofed User-Agent never counts: “verified” is the edge’s own verdict against the operator’s published IP ranges or reverse DNS. With the bot cache off the numbers show what crawlers get from the ordinary cache, which is the baseline the feature improves.

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.

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

200

Crawler cache counters.

application/json

object

requests

Requests from verified search-engine crawlers.

integer

hits

integer

misses

integer

bypass

integer

hit_rate

hits / (hits + misses) as a percentage; 0 with no cache lookups.

number

by_kind

The same counters per crawler, busiest first.

Array<object>

object

kind

string

requests

integer

hits

integer

misses

integer

bypass

integer

hit_rate

number

Example

{
  "by_kind": [
    {
      "kind": "googlebot"
    }
  ]
}

400

The domain query parameter is missing.

application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Examples

missing

{
  "error": "domain is required"
}

401

Missing, malformed, revoked or expired API key — or the owning account is inactive.

application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

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 single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

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 single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Example

{
  "error": "read-only API key"
}

429

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

application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Examples

limited

{
  "error": "rate limit exceeded"
}

503

The analytics backend is temporarily unreachable. Retry; no data is lost.

application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Examples

unavailable

{
  "error": "analytics unavailable"
}