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

# Other servers

> Send AI bot visits and visitors from AI apps to Aranx over HTTP

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:

```ts track-ai.ts theme={null}
import { createAiTraffic } from '@aranx/ai-analytics';
import { trackRequest } from '@aranx/ai-analytics/fetch';

// The key comes from process.env.ARANX_TRAFFIC_KEY. If your framework
// keeps .env values elsewhere, pass the key:
// createAiTraffic({ key: import.meta.env.ARANX_TRAFFIC_KEY }) in Astro.
const tracker = createAiTraffic();

/** Call it after your framework builds the response. */
export function trackAi(
  request: Request,
  response: Response,
  clientIp: string | null,
  waitUntil?: (promise: Promise<unknown>) => void
): Promise<void> | undefined {
  const pending = trackRequest(tracker, request, response, { ip: clientIp });
  if (waitUntil) {
    waitUntil(pending);
    return undefined;
  }
  return pending;
}
```

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:

```http theme={null}
POST https://aranx.com/api/v1/ai-traffic/events
Authorization: Bearer arx_tk_...
Content-Type: application/json

{
  "events": [
    {
      "type": "bot_visit",
      "url": "https://example.com/pricing",
      "user_agent": "Mozilla/5.0 (compatible; ChatGPT-User/1.0)",
      "status": 200,
      "ip": "104.208.184.200"
    },
    {
      "type": "ai_referral",
      "url": "https://example.com/blog/post?utm_source=chatgpt.com",
      "referrer": "https://chatgpt.com/"
    }
  ]
}
```

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

| Status | Meaning |
| - | - |
| `202` | `{ "accepted": n, "ignored": n, "unverified": n }`. `unverified` counts the bot visits ignored for their IP. |
| `400` | The body is not valid |
| `401` | The key is not valid |
| `403` | The subscription is not active |
| `413` | The body is larger than 512 KiB |
| `429` | More than 1,200 requests per minute. Retry after 60 seconds. |

## 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.


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