Reconciles a claimed bot User-Agent against the operator's OWN published
IP-range feed (Googlebot, GPTBot, OAI-SearchBot, ChatGPT-User,
PerplexityBot, Perplexity-User, Bingbot). A User-Agent is trivial to
forge; membership in the operator's published CIDR ranges is not. This
exposes the common attack: a scraper sending `User-Agent: Googlebot` from
an IP in none of Google's ranges.
Use this tool when:
- A request claims to be a search/AI crawler and you must decide whether
to trust that claim before serving, allowing, or logging it.
- You are separating genuine declared agents from impersonators.
Inputs:
- `ip` (path, required): the IPv4 or IPv6 address to check.
- `ua` (query, optional): the claimed User-Agent string. Omit to ask only
"is this IP a known published bot range?".
Returns:
- `verdict`: one of
- `verified` — the IP is inside the agent's published range (UA, if
given, agrees). It genuinely is that bot.
- `spoofed` — the UA claims a verifiable bot but the IP is in none of
its published ranges. Impersonation.
- `mismatch` — the IP is a real bot's range, but the UA names a
different bot.
- `unverifiable` — the UA names a real agent whose operator publishes
no authoritative IP feed (e.g. Anthropic's ClaudeBot). Neither
confirmed nor denied — never reported as spoofed.
- `unknown` — no recognized bot UA and the IP is in no known range.
- `is_verified_agent`, `is_spoofed`: booleans for the two actionable cases.
- `agent`, `agent_label`, `matched_agent`, `claimed_agent`: the resolved
identities.
- `reason`: one-line explanation of the verdict.
- `feeds_as_of_ms`: when the published ranges were last refreshed.
Cost:
- Counts as one request against the daily rate limit.
Latency:
- Typical: <50ms (one KV read + CIDR match). First call after a deploy may
take ~1s if it has to warm the range cache.