Agent Tracking: See Which AI Agents Visit Your Docs

Agent Tracking is a lightweight middleware layer that detects when AI coding agents visit your website or documentation. When Claude Code, OpenCode, ChatGPT, or any of the other supported agents reads your docs pages, Lightsage records the visit — giving you real data on which agents are actively researching your API.

Why this matters

You can optimize your documentation for AI agents without knowing which ones are actually visiting. But with Agent Tracking, you see the real picture: Claude Code visits your quick start 40 times a day, while Codex primarily reads your API reference. That’s not a guess — it’s a signal you can act on. Understanding agent visit patterns helps you:

Prioritize which agents to run API Performance evaluations against
Identify which documentation pages agents read most (and which they skip)
Detect when a new agent starts using your docs after you publish or update content
Correlate documentation changes with changes in agent visit frequency

How it works

The middleware inspects incoming HTTP requests for agent-specific user agent strings. When it detects a known AI coding agent or answer engine, it logs the visit — including which page was accessed and a timestamp — and forwards the data to Lightsage. The middleware adds no detectable latency to normal user traffic.

Installation

Next.js
Vercel
Cloudflare Workers
Express
Netlify

Create or update your middleware.ts file at the root of your project:

middleware.ts

import { withAgentTracking } from '@lightsage/agent-tracker/next';

export default withAgentTracking({
  apiKey: process.env.LIGHTSAGE_API_KEY
});

export const config = {
  matcher: ['/((?!api|_next|admin).*)'],
};

Install the package:

npm install @lightsage/agent-tracker

Then add your API key to .env.local:

LIGHTSAGE_API_KEY=your_api_key_here

The matcher config applies the middleware to all routes except api, _next, and admin. This ensures you’re tracking documentation and marketing page visits without adding overhead to your own API routes or Next.js internals.

If you’re deploying to Vercel without Next.js, add the middleware directly to your Vercel project. Create middleware.ts at the project root:

middleware.ts

import { withAgentTracking } from '@lightsage/agent-tracker/vercel';
import { NextRequest } from 'next/server';

export default withAgentTracking({
  apiKey: process.env.LIGHTSAGE_API_KEY
});

export const config = {
  matcher: ['/((?!api|_next|admin).*)'],
};

Set the environment variable in your Vercel project settings under Settings → Environment Variables:

LIGHTSAGE_API_KEY = your_api_key_here

Add the Lightsage tracker to your Cloudflare Worker:

worker.ts

import { createAgentTracker } from '@lightsage/agent-tracker/cloudflare';

const tracker = createAgentTracker({
  apiKey: env.LIGHTSAGE_API_KEY
});

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    await tracker.track(request);
    return fetch(request);
  }
};

Add the secret to your Worker via Wrangler:

wrangler secret put LIGHTSAGE_API_KEY

Add the middleware to your Express app before your route handlers:

server.ts

import express from 'express';
import { agentTracker } from '@lightsage/agent-tracker/express';

const app = express();

app.use(agentTracker({
  apiKey: process.env.LIGHTSAGE_API_KEY
}));

// Your routes below
app.get('/', (req, res) => {
  res.send('Hello world');
});

Set the environment variable before starting your server:

LIGHTSAGE_API_KEY=your_api_key_here node server.js

Add an edge function to your Netlify project. Create netlify/edge-functions/agent-tracker.ts:

netlify/edge-functions/agent-tracker.ts

import { createAgentTracker } from '@lightsage/agent-tracker/netlify';

const tracker = createAgentTracker({
  apiKey: Deno.env.get('LIGHTSAGE_API_KEY')
});

export default tracker.handler;

export const config = {
  path: '/*'
};

Add the environment variable in the Netlify dashboard under Site configuration → Environment variables.

The LIGHTSAGE_API_KEY

Your API key connects the middleware to your Lightsage account. Find it in your Lightsage dashboard under Settings → API Keys.

Never commit your LIGHTSAGE_API_KEY to version control. Use environment variables in your deployment platform — .env.local for local development (already excluded by .gitignore in most frameworks), and the platform’s secret management for production.

The matcher config (Next.js and Vercel)

The matcher pattern controls which routes the middleware runs on:

export const config = {
  matcher: ['/((?!api|_next|admin).*)'],
};

This regex matches every path except:

/api/* — your own API routes (no need to track these)
/_next/* — Next.js internal assets and static files
/admin/* — your admin panel (if one exists)

If your documentation lives on a subdirectory like /docs, you can narrow the matcher to only track those pages:

export const config = {
  matcher: ['/docs/:path*'],
};

What you see in the dashboard

After installing the middleware, the Agent Analytics section of your dashboard shows:

Data point	Description
Agent name	Which AI agent made the visit (e.g., Claude Code, Cursor, ChatGPT)
Visit count	Total visits from that agent over your selected time range
Pages visited	Which specific pages the agent accessed, ranked by visit count
Timestamps	When each visit occurred, shown in your local timezone
Visit trends	Day-over-day and week-over-week visit volume per agent

You can filter by agent, date range, and page path to drill into specific patterns.

Agents detected

Lightsage’s middleware detects all 17 tracked AI platforms:

Coding agents (10)

Claude Code, OpenAI Codex, Cursor, GitHub Copilot, Gemini CLI, OpenClaw, OpenCode, Hermes, Pi, Kilo

Answer engines (7)

ChatGPT, Google AI Overviews, Google AI Mode, Gemini Search, Perplexity, Claude, Microsoft Copilot

The middleware tracks visits from AI agent user agents, not human developer visits. Your existing analytics tools continue to capture human traffic normally. Agent Tracking adds a parallel view of your AI audience without replacing or interfering with any existing analytics setup.

Performance impact

The middleware operates asynchronously — it sends tracking data to Lightsage without blocking the request. For your human users, response times are unaffected. For AI agent visits, tracking adds no perceptible delay because agents are making HTTP requests regardless and aren’t sensitive to single-digit millisecond differences. Lightsage does not proxy your traffic. Requests go directly from the agent to your server; the middleware reads the request headers and fires a non-blocking event to Lightsage in the background.

Quickstart

Workflows

Agent Analytics

Integrations

Lightsage Docs Agent

Agent Tracking: See Which AI Agents Visit Your Docs

Why this matters

How it works

Installation

The LIGHTSAGE_API_KEY

The matcher config (Next.js and Vercel)

What you see in the dashboard

Agents detected

Coding agents (10)

Answer engines (7)

Performance impact

​Why this matters

​How it works

​Installation

​The LIGHTSAGE_API_KEY

​The matcher config (Next.js and Vercel)

​What you see in the dashboard

​Agents detected

Coding agents (10)

Answer engines (7)

​Performance impact

Why this matters

How it works

Installation

The LIGHTSAGE_API_KEY

The matcher config (Next.js and Vercel)

What you see in the dashboard

Agents detected

Performance impact