@foglift/tracker

Track AI crawler visits and AI engine referrals to your website. See which AI engines (ChatGPT, Claude, Perplexity, Gemini, Copilot) are crawling your content and sending you human visitors.

• Two signals, one install. UA-detected bot visits + Referer-detected human visits from AI engines.
• Zero customer install friction. One-line middleware in Next.js, Express, or plain Node.
• Cookieless. No fingerprinting. Only the visit's path, the matched UA category, and the matched referrer host are sent to Foglift.
• Fire-and-forget. Reporting never blocks your request lifecycle.

Install

npm install @foglift/tracker

You'll need a Foglift API key (sk_fog_…). Generate one at https://foglift.io/dashboard/settings → Developer.

Quickstart — Next.js

// middleware.ts
import { trackAITraffic } from "@foglift/tracker/nextjs";

export const middleware = trackAITraffic({
  apiKey: process.env.FOGLIFT_API_KEY!,
});

export const config = {
  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
};

That's it. Within ~5 seconds of a real ChatGPT/Claude/Perplexity user clicking through to your site, a row lands in your dashboard at https://foglift.io/dashboard/crawlers.

Composing with an existing middleware

import { trackAITraffic } from "@foglift/tracker/nextjs";
import { auth } from "./auth-middleware";

export const middleware = trackAITraffic({
  apiKey: process.env.FOGLIFT_API_KEY!,
  next: auth,
});

Quickstart — Express

import express from "express";
import { trackAITraffic } from "@foglift/tracker/express";

const app = express();
app.use(trackAITraffic({ apiKey: process.env.FOGLIFT_API_KEY! }));

Quickstart — plain Node (any framework)

import http from "node:http";
import { createAITrafficTracker } from "@foglift/tracker/node";

const tracker = createAITrafficTracker({ apiKey: process.env.FOGLIFT_API_KEY! });

http
  .createServer((req, res) => {
    tracker.track(req);
    res.end("ok");
  })
  .listen(3000);

What gets reported

trackAITraffic emits one of two visit shapes per matching request, then drops the call. Nothing is reported if neither the UA nor the Referer matches — the vast majority of your traffic is invisible to Foglift.

Crawler visits (UA wins over Referer)

When the User-Agent matches a known AI crawler — GPTBot, ClaudeBot, PerplexityBot, Google-Extended, Amazonbot, etc. — the visit is reported as source: "crawler" with the matched bot name and engine.

Referrer visits (human users from AI search)

When the User-Agent looks human but the Referer header points at one of the canonical AI search hostnames, the visit is reported as source: "referrer".

| Engine | Hostname(s) tracked | |---------------|--------------------------------------------------| | ChatGPT | chatgpt.com, chat.openai.com | | Claude | claude.ai | | Perplexity | perplexity.ai, www.perplexity.ai | | Gemini | gemini.google.com | | Copilot | copilot.microsoft.com | | NotebookLM | notebooklm.google.com |

Google AI Overview disambiguation (parsing udm=/ved= on google.com referrers) is intentionally out of scope for v1.2.0 — google.com referrers stay classified as organic search by your host application. Tracked for v1.3.

Privacy

• No cookies, no fingerprinting. The tracker reads the request's User-Agent, Referer header, and path — nothing else.
• No PII. The Referer is parsed for hostname only; query parameters are discarded before reporting.
• Cross-origin POST. Visits are POSTed to https://foglift.io/api/v1/crawler-analytics over HTTPS, authenticated by your X-API-Key header.
• Fire-and-forget. A failed report logs (only when debug: true) and never throws.

Migrating from v1.1.0

If you're upgrading from @foglift/[email protected], the trackAICrawlers export still works and now additionally reports referrer visits — no code change required, you get the new signal for free. The export will warn in v1.3 and be removed in v2.0; switch to trackAITraffic at your convenience.

// v1.1.0 (still works, additive in v1.2.0)
import { trackAICrawlers } from "@foglift/tracker/nextjs";

// v1.2.0 — preferred
import { trackAITraffic } from "@foglift/tracker/nextjs";

The crawler-visit payload shape is byte-identical to v1.1.0 (with one additive source: "crawler" field) — receiver-side aggregation is unchanged for existing crawler customers.

Debugging

trackAITraffic({
  apiKey: process.env.FOGLIFT_API_KEY!,
  debug: true,
});

In debug mode, failed reports log to console.warn with the HTTP status and error message. Disable in production.

Manual classification helpers

If you'd rather drive the classification yourself (e.g. you already have a custom analytics pipeline), the detectors are exported as pure functions:

import { detectAICrawler, detectAIReferrer } from "@foglift/tracker";

detectAICrawler("Mozilla/5.0 (compatible; PerplexityBot/1.0)");
//=> { crawler: "PerplexityBot", engine: "Perplexity" }

detectAIReferrer("https://chatgpt.com/c/abc123");
//=> { source: "chatgpt.com", engine: "ChatGPT" }

Both return null on no-match.

Links

• Dashboard: https://foglift.io/dashboard/crawlers
• Foglift docs: https://foglift.io/docs/tracker
• Issue tracker: https://github.com/foglift/tracker/issues
• License: MIT