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

# Express

> Track AI bot visits and visitors from AI apps on an Express server

The `@aranx/ai-analytics` package adds an Express middleware. It records
requests from AI bots such as `ChatGPT-User` and `PerplexityBot`, and visits
from people who open your site from a link in an AI app. It sends events in
batches every 10 seconds.

## Before you start

* In Aranx, open **AI Visibility** for the website and create a server
  key. Aranx shows the key once.

## Setup

**1. Install the package**

```sh theme={null}
npm install @aranx/ai-analytics
```

**2. Set the key**

Set the `ARANX_TRAFFIC_KEY` environment variable on the server. For local
development, add it to `.env`:

```sh .env theme={null}
ARANX_TRAFFIC_KEY=arx_tk_...
```

Do not commit the key. The package reads only `process.env`, so the server
must load `.env` before it creates the middleware. Use
`node --env-file=.env server.js` (Node.js 20.6 or later) or the dotenv
loader of the project. Bun loads `.env` by itself.

**3. Add the middleware**

Register it before your routes:

```ts server.ts theme={null}
import express from 'express';
import { aiTraffic } from '@aranx/ai-analytics/express';

const app = express();

app.use(aiTraffic());

// Your routes
```

The client IP is Express's `req.ip`. Aranx counts a bot visit only when
its IP is in the bot's published IP ranges. Behind a load balancer,
`req.ip` is the balancer, so set `trust proxy` for your proxy as the
[Express guide](https://expressjs.com/en/guide/behind-proxies.html) shows,
for example `app.set('trust proxy', 1)` for one proxy hop. Do not set it
to `true` unless the proxy is the only way to reach the server.

**4. Deploy**

Deploy the server. Aranx shows the first bot visits on the AI visibility
page.

## Other Node.js frameworks

Fastify and Koa can pass the Node request to `nodeRequestInfo` from
`@aranx/ai-analytics/express` with the client IP the framework computed
(`{ ip: request.ip }`, or `ctx.ip` in Koa), then call `tracker.track(info)`
on a tracker from `createAiTraffic()`.

## Check the setup

Send a request with an AI user agent:

```sh theme={null}
curl -A "Mozilla/5.0 (compatible; ChatGPT-User/1.0)" https://example.com/
```

Aranx does not count this visit. It counts a bot visit only from an IP in the
ranges that OpenAI, Anthropic, and Perplexity publish for their bots, and
scanners often fake these user agents. The request still marks the key as
used.

Wait 10 seconds for the batch. In Aranx, **Settings > Sources** on the AI
visibility page shows when the key was last used.

## What the package sends

For each AI request: the page URL without its query (it keeps `utm_source`),
the user agent, the response status, and the time. Bot visits also carry the
client IP, which Aranx checks against the bot's published IP ranges and does
not store. Tracking never throws and never delays the response.


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