@befound/track

Server-side AI crawler tracking for BeFound.dev. See when GPTBot, ChatGPT-User, OAI-SearchBot, Googlebot, ClaudeBot, PerplexityBot and the rest read each page of your site, and when people click through to you from an AI answer.

AI crawlers do not run JavaScript, so a browser pixel never sees them. This package runs on your server, looks at the request headers, and reports only bot and AI-referral traffic. Regular visitors are never sent. Zero dependencies.

Install

npm install @befound/track

Get your site key from the Crawlers tab of your business in BeFound.

Next.js

Works in proxy.ts (Next.js 16+) and middleware.ts (Next.js 12–15). Fine on Vercel, Netlify, and self-hosted, including sites built with Lovable, v0, or Bolt.

// proxy.ts
import { withBeFound } from "@befound/track/next";

export const proxy = withBeFound({ token: "bf_your_site_key" });

Already have a proxy? Wrap it:

export const proxy = withBeFound({ token: "bf_your_site_key" }, existingProxy);

The beacon is sent with event.waitUntil, so it never delays your response.

Express / Node

import express from "express";
import { befoundTrack } from "@befound/track/node";

const app = express();
app.use(befoundTrack({ token: "bf_your_site_key" }));

Captures the response status code too.

Anything else

import { createTracker } from "@befound/track";

const tracker = createTracker({ token: "bf_your_site_key" });
tracker.track({ url, ua, ip, referer, status });

Options

| Option | Default | Notes | | --- | --- | --- | | token | required | Your BeFound site key | | endpoint | https://befound.dev/api/track | Override for self-hosted BeFound | | reportAll | false | Send every request instead of pre-filtering to bots | | ignorePaths | static/asset prefixes | Path prefixes never reported | | batchSize / flushMs | 20 / 2000 | Batching for the Node middleware | | onError | no-op | Delivery error callback |

Privacy

Only requests whose User-Agent looks like a crawler, or whose Referer is an AI assistant, are reported. Human visitors coming from AI answers are recorded as a click on a page; their IP address is never stored.