Collect from any server

Add the code

Send each request to the HTTP API from your server, edge function or log pipeline.

Set the server key

The code reads your project's server key from the ETHOGRAM_KEY environment variable. Create the key on your project's setup page in the dashboard (or under Settings, Server keys), and set it where your server runs. It's shown once, so save it straight away. Keep it secret, like a password: it lets whoever holds it report events for your site.

The example sends one event. Every field, limit and response is in the HTTP API reference.

What to send

• One event per request your server handled, after the response has gone out, ignoring any error, so visitors never wait or fail on Ethogram.
• url: the full URL as requested, with scheme and host. method, time, status, duration and ip when you have them, and response (your answer's content-type, content-length and cf-mitigated) to see why agents get stuck.
• ip: the visitor's address as your host reports it, such as cf-connecting-ip, x-real-ip or the last x-forwarded-for entry. The first entry is only the client's word.

Forwarded headers

Send every request header as received, except cookie, authorization and proxy-authorization. Keep signature, signature-input and signature-agent exactly as they came: signed agents (Web Bot Auth) are verified against them, together with the URL and method, so those must be the request's own.

Skip static assets (CSS, images, fonts, video): they aren't visits. Do send requests for JavaScript files (.js, .mjs): Ethogram counts the scripts each agent fetches, adds them to no request count, and drops people's on arrival.

Named actions

Add "action": { "name": "Added to cart", "target": "Blue T-shirt" } to an event to report a named action. See Named actions with track().

Optional: the browser check

Some AI agents drive a real browser, like Claude in Chrome or Comet. To your server, their requests look like a person's. The browser check is a small script that tells them apart by how each page is used: whether the pointer moved before a click, whether typed text came with key presses, whether the browser says automation controls it. Serve https://ethogram.si/ethogram.js at /_ethogram/check.js on your own domain and add this tag to your pages. Forward each POST to /_ethogram/report as an event with a browser field, as at the end of the example above.

Your server answers two paths of its own: /_ethogram/check.js, the script, fetched from https://ethogram.si/ethogram.js and cached for an hour, and /_ethogram/report, where the script sends its counts once when the page loads and again when it's hidden or closed. Each report is forwarded to Ethogram with the request's IP and headers, so it joins the visit it belongs to. Neither path is reported as a page.

It sets no cookie, stores nothing in the browser, and sends only counts and yes-or-no answers: never where the pointer was, what was typed or anything that identifies the person. See Data we keep. Without it, everything else works the same, and most of those agents count as people.

Check it

Deploy, then visit your site the way an AI agent would, with your own domain in place of example.com:

The setup page turns live when the first event arrives. Your test shows up as a spoofed GPTBot, since it doesn't come from OpenAI. That's detection working. Nothing showing up? See the FAQ.