nsindocs Search the docs⌘K
API
  1. Docs
  2. API reference
  3. Analytics

Cache counters for verified search-engine crawlers

gethttps://api.nsin.ir/analytics/bot-cache

Auth: Authorization: Bearer nsin_… or X-Api-Key: nsin_… — see API keys.

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.

Query parameters

  • domainstringrequiredquery

    The domain name (for example example.com). These endpoints take the domain as a query parameter rather than a path segment.

  • periodstringquery

    Time window, ending now. Time series are bucketed by minute for 1h, by hour up to 48h, and by day for 7d and 30d. Buckets are cut on Asia/Tehran (UTC+03:30) boundaries and emitted as UTC instants, so an hourly bucket starts at :30 UTC. An unrecognised value falls back to 24h.

    One of: "1h" "3h" "6h" "12h" "24h" "48h" "7d" "30d"
    Default: "24h"
  • hostnamestringquery

    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.

  • pathstringquery

    Narrow to a URL path prefix.

Responses

200Crawler cache counters.

Content type: application/json

  • requestsinteger

    Requests from verified search-engine crawlers.

  • hitsinteger

    Crawler requests answered from the bot cache.

  • missesinteger

    Crawler requests that missed it.

  • bypassinteger

    Crawler requests that bypassed it.

  • hit_ratenumber

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

  • by_kindarray of object

    The same counters per crawler, busiest first.

    Item fields
    • kindstring
    • requestsinteger
    • hitsinteger
    • missesinteger
    • bypassinteger
    • hit_ratenumber
json
{
  "requests": 0,
  "hits": 0,
  "misses": 0,
  "bypass": 0,
  "hit_rate": 0,
  "by_kind": [
    {
      "kind": "googlebot",
      "requests": 0,
      "hits": 0,
      "misses": 0,
      "bypass": 0,
      "hit_rate": 0
    }
  ]
}
400The domain query parameter is missing.

Content type: application/json

  • errorstringrequired

    Human-readable description of what went wrong.

json
{
  "error": "domain is required"
}
401Missing, malformed, revoked or expired API key. (A valid key whose account has been deactivated gets 403 account is inactive instead.)

Content type: application/json

  • errorstringrequired

    Human-readable description of what went wrong.

json
{
  "error": "invalid API key"
}
402The domain has no active plan at all, so no plan feature is available on it. Buy or renew a plan for the domain. (A plan that is active but does not include the feature answers 403 instead.)

Content type: application/json

  • errorstringrequired

    Human-readable description of what went wrong.

json
{
  "error": "This domain does not have an active plan."
}
403The domain's plan does not include the feature this endpoint needs (monitoring for most sections, logs for raw and top-N request data).

Content type: application/json

  • errorstringrequired

    Human-readable description of what went wrong.

json
{
  "error": "read-only API key"
}
404No such domain, or it is not visible to this account. Domains you cannot access are reported as not found rather than forbidden.

Content type: application/json

  • errorstringrequired

    Human-readable description of what went wrong.

json
{
  "error": "read-only API key"
}
429The key exceeded its request budget (300 requests per minute by default).

Content type: application/json

  • errorstringrequired

    Human-readable description of what went wrong.

json
{
  "error": "rate limit exceeded"
}
503Either the analytics backend is temporarily unreachable (retry; no data is lost), or the answer is still being computed. The per-domain sections and the cached account-wide views (domains-overview, global-summary, global-summary/peak, requests-compare, bandwidth-overview, nodes-overview) wait at most about 25 seconds for their query; past that they answer 503 with pending: true and a Retry-After header, while the query keeps running and caches its result, so the retry is served from that cache instead of starting the same scan again. Identical concurrent requests share one computation.

Content type: application/json

  • errorstringrequired

    Human-readable description of what went wrong.

  • pendingboolean

    true when the query is still running rather than failing. Retry after Retry-After seconds.

json
{
  "error": "analytics unavailable"
}

Example request

bash
curl -X GET "https://api.nsin.ir/analytics/bot-cache?domain=example.com" \
  -H "Authorization: Bearer $NSIN_API_KEY"
esc