ethogram
DocsQuick start

Docs · Get started

Quick start

Create a project, get its server key, add a collector to your server and check it with one curl request.

Ethogram runs on your server. After each response goes out, your server reports the request to Ethogram. That's how it sees every agent, including crawlers that never run JavaScript. An optional browser check on your pages catches the agents that drive a real browser. Setting it up takes four steps.

1. Create a project

Sign up, then enter the website you want to watch. Each project is one website. Recording starts once an owner of the project has a plan; you can install first and pick a plan later.

2. Get the server key

On the project's setup page, choose Create server key. Save it in your server's environment as ETHOGRAM_KEY (in a .env file: ETHOGRAM_KEY=your key). It's shown only once. Lost it, or want a new one? Under Settings, Server keys, add a second key, switch your collector, then revoke the old one; a revoked key stops within a minute.

3. Install a collector

Pick the one that matches how your site runs:

  • Next.js: Create proxy.ts next to your app folder. Already have one? Add report() and move the body of this proxy function to the top of yours.
  • Cloudflare: A Worker in front of your site. Works for WordPress, Webflow and anything else Cloudflare proxies.
  • Express: Add this before your routes and express.static, so it also sees the JavaScript files agents fetch.
  • Any server: Send each request to the HTTP API from your server, edge function or log pipeline.

The setup page also has a prompt you can paste into a coding agent (Claude Code, Codex or Cursor), which adds the collector for you.

Optionally, add the browser check: one script tag your collector serves from your own domain. It tells people from AI agents that drive a real browser, sets no cookie and stores nothing. Each collector page shows where it goes; the Cloudflare Worker adds it by itself.

4. Test it

Deploy, then send a request that claims to be GPTBot, with your own domain in place of example.com:

Terminal
curl -A "GPTBot/1.2" https://example.com/

The setup page turns live when the first event arrives. The test shows up as a spoofed GPTBot, since it doesn't come from OpenAI's addresses. That's detection working: see verdicts.

Next