> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openrevenue.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bot traffic tracking

> See when AI assistants, search engines, and model-training crawlers request your pages by adding server-side bot tracking.

## Why server-side

The OpenRevenue `tracker.js` runs in the browser, but bots like ChatGPT, Perplexity, Googlebot, and GPTBot don't execute JavaScript — they just fetch your HTML. To see them you forward each request's User-Agent to OpenRevenue from your server. OpenRevenue classifies it and records the crawl if it's a known bot.

> [!NOTE]
>
> Forwarding is fire-and-forget. Non-bot requests are ignored, so it's safe to call on every request.

## Auth

Each project has its own bot ingest key. Copy it from the Bots tab empty state (or mint via `getBotIngestKeyForDomain` in the dashboard) and set `OPENREVENUE_BOT_INGEST_KEY` in your app env. Do not reuse a platform-wide secret — keys are bound to `projectId`.

Alternatively send a write-scoped OpenRevenue API key as `Authorization: Bearer openrevenue_…` (the key's owner must be able to access the project).

## Next.js middleware

Add a `middleware.ts` at your project root. It runs on every request and reports the User-Agent without blocking the response.

```ts theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
// middleware.ts
import { NextResponse, type NextRequest } from "next/server"

export function middleware(req: NextRequest) {
  // Fire-and-forget; never block the response.
  fetch("https://api.openrevenue.com/api/track/bot", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      // Per-project key from the OpenRevenue Bots tab (not a shared platform secret).
      "x-openrevenue-bot-key": process.env.OPENREVENUE_BOT_INGEST_KEY!,
    },
    body: JSON.stringify({
      projectId: "your-project-id",
      path: req.nextUrl.pathname,
      userAgent: req.headers.get("user-agent") ?? "",
      ip: req.headers.get("x-forwarded-for") ?? "",
    }),
  }).catch(() => {})

  return NextResponse.next()
}

// Skip static assets so you only report real page requests.
export const config = {
  matcher: ["/((?!_next/|favicon.ico|.*\\..*).*)"],
}
```

## Node / any backend

Any server can report a hit with a single `POST`. Express example:

```js theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
app.use((req, res, next) => {
  fetch("https://api.openrevenue.com/api/track/bot", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-openrevenue-bot-key": process.env.OPENREVENUE_BOT_INGEST_KEY,
    },
    body: JSON.stringify({
      projectId: "your-project-id",
      path: req.path,
      userAgent: req.headers["user-agent"] || "",
      ip: req.headers["x-forwarded-for"] || req.socket.remoteAddress || "",
    }),
  }).catch(() => {})
  next()
})
```

## Payload

`POST https://api.openrevenue.com/api/track/bot` with header `x-openrevenue-bot-key` set to your per-project bot ingest key (required in production), or a write-scoped `Authorization: Bearer` API key, and a JSON body:

| Name | Type | Description |
| - | - | - |
| `projectId` | string (required) | Your project ID (the tracker data-site value). |
| `userAgent` | string (required) | The incoming request's User-Agent header. |
| `path` | string | The requested path, e.g. /pricing. Defaults to /. |
| `ip` | string | The client IP (for verification + geography). Optional. |
| `countryCode` | string | ISO country when forwarding from middleware (e.g. US). Used when the bot IP differs from this request's IP. |

## What gets detected

Recognised bots are grouped into three categories:

| Name | Type | Description |
| - | - | - |
| AI answers | category | Assistants fetching live to answer a prompt: ChatGPT, Claude, Perplexity, Gemini, Copilot. |
| Indexing | category | Search-engine crawlers: Googlebot, Bingbot, DuckDuckBot, YandexBot, Baiduspider, meta-webindexer. |
| Training | category | Model-training scrapers: GPTBot, ClaudeBot, Google-Extended, GoogleOther, Applebot, CCBot, Bytespider, Amazonbot. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.