Skip to main content
When a coding agent reads your documentation, it leaves no trace in a standard analytics tool. Google Analytics records human sessions. Your CDN logs record IP addresses. Neither tells you that Claude Code spent the last hour reading your authentication reference — or that Cursor crawled your quick start but never reached your error handling guide. Lightsage’s agent tracking middleware sits in front of your application and identifies AI agent traffic by user agent signature. It adds zero latency to user-facing requests and sends agent visit events to your Lightsage dashboard in real time. The following agents are detected:
  • Coding agents: Claude Code, OpenCode, Cursor, GitHub Copilot, OpenAI Codex, Gemini CLI, OpenClaw, Hermes, Pi, Kilo
  • Answer engines and crawlers: ChatGPT, Google AI, Perplexity, and their associated crawlers

Getting your API key

Find your LIGHTSAGE_API_KEY in your Lightsage account settings. Store it as an environment variable — never commit it to source control.

Installation

Installing the package

The matcher config

For Next.js and Vercel, the matcher config controls which routes the middleware runs on. The pattern /((?!api|_next|admin).*) means: run on all routes except those starting with api/, _next/, or admin/. You should exclude:
  • api/ — your own API routes (you don’t need to track server-to-server calls as agent visits)
  • _next/ — Next.js static assets and build artifacts
  • admin/ — internal tooling that agents shouldn’t be visiting anyway
If you have additional paths to exclude — for example, a staging environment path or internal health check endpoint — add them to the exclusion list:

What you see in the dashboard

Once the middleware is deployed and agents begin visiting your site, the Lightsage dashboard shows:
  • Agent identity — which coding agent made the visit (Claude Code, Cursor, etc.)
  • Pages visited — which documentation pages the agent read, in order
  • Visit frequency — how often each agent crawls your docs
  • First seen / last seen — when an agent first discovered your docs and when it most recently visited
  • Correlation with recommendations — Lightsage links agent visit patterns to your prompt tracking data so you can see whether agents that crawl your docs more frequently also recommend you more often
The first agent visits may appear in your dashboard within minutes of deploying the middleware, depending on how actively the agents currently crawl your domain. If you see no visits within 48 hours, verify that your robots.txt is not blocking AI crawlers. See Optimize your API for AI coding agent discovery for the robots.txt configuration.

Performance impact

The middleware runs on your edge infrastructure and uses a fire-and-forget pattern for the tracking event — it does not add latency to the response path for any visitor, human or agent. The identification logic is a user-agent string lookup, which completes in microseconds.
For Cloudflare Workers and Netlify Edge Functions, use event.waitUntil() or the equivalent platform primitive to ensure the tracking event completes even after the response is returned, without blocking the response itself.

Next steps

Agent visit tracking gives you the web-crawl half of the picture. To track what agents recommend when developers ask implementation questions, see How to track coding agent recommendations for your API. To connect recognized AI acquisition sources to sign-up, demo, checkout, and activation events, see Measure agent-attributed growth. To improve the quality of what agents find when they visit your docs, see Optimize your API for AI coding agent discovery.