Before you start
- In Aranx, open AI Visibility for the website and create a server key. Aranx shows the key once.
- Store the key on the server, for example as the
ARANX_TRAFFIC_KEYenvironment variable. Do not commit it.
JavaScript frameworks with a standard Request
React Router, Remix, SvelteKit, Astro, Deno, and Bun can use the npm package. CalltrackAi after your framework builds the response:
track-ai.ts
event.getClientAddress() in
SvelteKit, Astro.clientAddress or context.clientAddress in Astro,
server.requestIP(req)?.address in Bun, info.remoteAddr.hostname in Deno. Aranx
counts a bot visit only when its IP is in the bot’s published IP ranges, so a
bot visit without an IP is not counted.
A serverless host can stop the function when it returns the response, and
the event is then lost. On Cloudflare, Vercel, or Netlify, pass the
waitUntil of the host. Write it as (p) => ctx.waitUntil(p) so the method
keeps its receiver. If the host has no waitUntil, await the returned
promise before you return the response. The promise never throws and gives
up after 5 seconds. On a long-running server, you do not need to await it.
Send events over HTTP
Post events to the endpoint with the key as a bearer token:- Count only
GETandHEADrequests. - Send at most one event per request. Check for a bot first.
- A
bot_visitis a request whose user agent contains one ofOAI-SearchBot,ChatGPT-User,Claude-SearchBot,Claude-User,PerplexityBot, orPerplexity-Useras a whole word. Send the client IP asip: the address of the connection, or theX-Forwarded-Forvalue that your own proxy sets. Do not read a header that a client can set. - Otherwise, skip the request if its
Sec-Fetch-Destheader is set to a value other thandocument. Images, scripts, and API calls of a page carry the page as referrer, and only the page itself counts. - An
ai_referralis a request withutm_source=chatgpt.com, or a referrer onchatgpt.com,chat.openai.com,perplexity.ai,gemini.google.com,bard.google.com,claude.ai,copilot.microsoft.com, orcopilot.cloud.microsoft(subdomains count too).
Limits
statusandoccurred_atare optional. Aranx uses the time it receives an event whenoccurred_atis missing, and ignores events older than 3 days.- Each request takes 1 to 500 events and at most 512 KiB.
urlandreferrertake at most 2,048 characters. - A bot visit counts only when
ipis in the IP ranges that OpenAI, Anthropic, and Perplexity publish for the bot. Aranx does not store the IP. - Aranx classifies each event again. It ignores events it cannot place, such as an unknown user agent or a host the website does not own.
Responses
Check the setup
Post onebot_visit event for a page on your site, with your own IP. The
response is 202 with "unverified": 1: the endpoint took the key and the
event, and ignored the visit because the IP is not a bot’s. Settings > Sources on the AI
visibility page shows when the key was last used.
