Skip to main content
Any server can post AI traffic events to Aranx. Use this for PHP, Python, Ruby, Go, or a JavaScript framework without an adapter.

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_KEY environment variable. Do not commit it.

JavaScript frameworks with a standard Request

React Router, Remix, SvelteKit, Astro, Deno, and Bun can use the npm package. Call trackAi after your framework builds the response:
track-ai.ts
Pass the client IP that your framework gives: 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:
Send only AI requests, with the same rules as the npm package:
  1. Count only GET and HEAD requests.
  2. Send at most one event per request. Check for a bot first.
  3. A bot_visit is a request whose user agent contains one of OAI-SearchBot, ChatGPT-User, Claude-SearchBot, Claude-User, PerplexityBot, or Perplexity-User as a whole word. Send the client IP as ip: the address of the connection, or the X-Forwarded-For value that your own proxy sets. Do not read a header that a client can set.
  4. Otherwise, skip the request if its Sec-Fetch-Dest header is set to a value other than document. Images, scripts, and API calls of a page carry the page as referrer, and only the page itself counts.
  5. An ai_referral is a request with utm_source=chatgpt.com, or a referrer on chatgpt.com, chat.openai.com, perplexity.ai, gemini.google.com, bard.google.com, claude.ai, copilot.microsoft.com, or copilot.cloud.microsoft (subdomains count too).
Send the events after the response, so tracking does not slow the page down. Batch them if the server keeps a process between requests.

Limits

  • status and occurred_at are optional. Aranx uses the time it receives an event when occurred_at is missing, and ignores events older than 3 days.
  • Each request takes 1 to 500 events and at most 512 KiB. url and referrer take at most 2,048 characters.
  • A bot visit counts only when ip is 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 one bot_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.