Server SDK
GPTBot, ClaudeBot, PerplexityBot, Google-Extended and most AI agents never run JavaScript, so the browser SDK can't see them. The server integration looks at every request your server handles and reports the ones that come from bots.
Get the server key
Copy the secret server key (al_srv_…) from Project settings → Setup → AI agents and crawlers (also under Project settings → General). Unlike the public key, it must stay on the server.
AGENTSTATS_SERVER_KEY=al_srv_…
Install
npm i @agentstats/sdk
Add the middleware
import { createAgentStats } from '@agentstats/sdk/server'
const lens = createAgentStats({ serverKey: process.env.AGENTSTATS_SERVER_KEY })
Then hook it into your framework:
// proxy.ts (Next 16; on Next 15, middleware.ts exporting `middleware`)
import { NextResponse } from 'next/server'
export function proxy(request, event) {
const response = NextResponse.next()
lens.track(request, { response, waitUntil: p => event.waitUntil(p) })
return response
}
// server/plugins/agentstats.ts — works on every Nitro preset
export default defineNitroPlugin(lens.nitro())
// src/hooks.server.ts — or sequence(lens.sveltekit(), yourHandle)
export const handle = lens.sveltekit()
// src/middleware.ts — pages must render on demand
export const onRequest = lens.astro()
app.use(lens.express())
app.use(lens.hono())
export default { fetch: lens.wrapFetch(handler) }
::
Detect bots in your code
Every adapter also tells your app who's asking, so you can treat AI agents differently (serve Markdown, skip a cookie banner, log them):
| Framework | Where |
|---|---|
| Next.js | detectBot(await headers()) in server components, lens.track() returns it in proxy.ts |
| Nuxt | event.context.bot in server routes, useRequestEvent()?.context.bot in pages |
| SvelteKit | event.locals.bot |
| Astro | Astro.locals.bot |
| Express | res.locals.bot |
| Hono | c.get('bot') |
detectBot() also works on its own, with no key: pass it a Request, a Headers object or a Node request.
import { detectBot } from '@agentstats/sdk/server'
const bot = detectBot(request)
// { isBot: true, isAI: true, id: 'gptbot', name: 'GPTBot', category: 'training',
// product: 'ChatGPT', operator: 'OpenAI', browser: false, signed: false, referral: null }
training, search, assistant, agent).claude-user / Claude-User / Claude / Anthropic.training, search (AI search indexers), assistant (fetched because someone asked an assistant), agent (browses and acts for a user), search_engine or other.ChatGPT, from the referrer or utm_source.This is the same bot list the dashboard uses, so your app and your dashboard always agree.
Options
al_srv_…. Never expose it to browsers. Without it (say, locally without the env var), the adapters still detect bots but nothing is sent.al_api_…, to also track the calls agents make to your API. See API tracking.true. Counts human page views as one number per day, nothing else, so the dashboard can show the AI share of your traffic.true. Links visits from agents that browse with a real browser to their WebMCP tool calls. See Verification.cf-connecting-ip behind Cloudflare. See below.Behind a proxy or load balancer
Behind nginx, Render, Railway, Fly or a cloud load balancer, the client IP comes from forwarding headers (CF-Connecting-IP, X-Real-IP, X-Forwarded-For).
The Node / Express adapter trusts those headers automatically when the connection comes from a private or loopback address, and ignores them on direct public connections so they can't be spoofed. Force either behaviour with trustProxy: true or false.
On Vercel, Netlify, Fly and Cloudflare Workers the SDK reads only the header that platform sets (X-Real-IP, X-Nf-Client-Connection-IP, Fly-Client-IP, CF-Connecting-IP), because the platform overwrites it and clients can't forge it. SvelteKit and Astro use the address the framework's adapter reports.
Anywhere else, if you're behind a CDN or proxy that always sets one header, name it with ipHeader (e.g. ipHeader: 'cf-connecting-ip' behind Cloudflare). Otherwise a client could send a vendor's IP in a forwarding header and pass as a verified crawler.
A hit that still arrives with an internal IP is shown as unverified, never as spoofed.