FAQ

I installed a collector, but there's no data yet

Work through these in order:

1. Is the new code deployed? The collector only runs once your server is serving it.
2. Is ETHOGRAM_KEY set where the server runs? Without it, or with a revoked key, every event is refused with 401. Check it's one of the keys listed under Settings, Server keys, and deploy it again if you changed it.
3. Does the project have a plan? Events are only recorded while an owner of the project has a plan. Without one they're refused with 402 (see below).
4. Did a request reach it? Send one yourself: curl -A "GPTBot/1.2" https://example.com/, with your domain. Static files and Next.js link prefetches are skipped on purpose, so request a page.
5. Has an agent visited? Once events arrive, the setup page turns live. The dashboard lists agent visits, so if only people have come so far it says so and waits for the first agent.

The collectors ignore every answer from Ethogram, so your site keeps working whatever goes wrong. To see the answer, send an event to the HTTP API with curl and read the status.

Why do I get 402?

402 means the project has no active plan, so events aren't recorded: no owner of the project has a live plan, for example because a trial ended, a plan was cancelled or a payment failed. The collectors keep running and nothing breaks on your site; events are simply not kept. Recording starts again once an owner has a plan, which can take up to a minute to reach the API. Plans are managed under your account in the dashboard. Events sent while the plan was off aren't recorded later.

Why is an agent shown as Unverified?

Its user agent names a known agent, but there was nothing to check that against: no IP was reported, its operator publishes no IP ranges or hostnames, or the list or DNS couldn't be reached at the time. It may well be the real agent, and it still counts as that agent's visit.

The most common fix is on your side: make sure your collector sends the visitor's real IP, not your load balancer's or proxy's. See the ip notes on each collector page, and verdicts for the full rules.

Why is an agent marked as ignoring robots.txt?

This week it requested paths your robots.txt disallows for it, judged by the same rules crawlers follow (RFC 9309). The finding says how many paths, gives examples, and says how many of those visits were verified as the real agent; spoofed visits never count. Open a visit to see the exact requests.

A few things to check first. Requests are judged against your current robots.txt, so if you added the rule this week, earlier requests may have been allowed at the time. Agents that fetch a page because a person asked (ChatGPT-User, Claude-User and the like) are reported apart: their operators say user-triggered fetches may not follow robots.txt. And if your robots.txt couldn't be fetched, nothing is marked either way. See robots.txt for the rules.

Why does my test show up as spoofed?

Because it is: your curl request claims to be GPTBot but doesn't come from OpenAI's addresses. That's detection working.

What are the findings alert emails, and how do I turn them off?

When the analysis turns up a high or medium insight that wasn't in the last alert, Ethogram emails the project's owners and admins the top five, linked to the project's insights. Each project sends at most one a day, and while its owners have no plan it sends none. The first analysis of a project only sets the starting point, so you aren't emailed about what was already there.

To stop them for a project, use the unsubscribe link at the bottom of any alert, or switch the project off under Findings alerts on your account page. Members aren't emailed unless they switch it on there. The choice is yours alone: it doesn't change anyone else on the project. A project that requires two-factor sign-in doesn't send alerts or the daily brief to members who haven't turned it on, until they do.

What is the daily brief email?

Once a day, Ethogram can email you what AI agents did on a project's site in the last 24 hours, set against the last 7 days: how many agent visits there were against a usual day, which agents were busiest, how many were blocked, and any insight that's new. Claude writes it from the same aggregates and insights the dashboard shows, never from anything about people; when Claude isn't available, the email lists those numbers and insights as they are. Days with no agent visits and nothing new send nothing.

It's off for everyone, owners included, until you switch a project on under Daily brief on your account page. Stop it with the unsubscribe link in any brief, or switch it off there again. Like alerts, it isn't sent while the project's owners have no plan.

How do I look at a different period?

The overview, Agents, an agent's page and Pages share a period picker at the top: the last 7, 14, 30 or 90 days, or custom dates up to a year (whole days in your own time zone). Headline numbers compare with the period of the same length just before, as “↑ 12% vs previous 30 days”, or say “New” when there was nothing before. Charts show both periods, the earlier one dimmed, by week once the period is longer than 30 days. Insights and alert emails always use the last 14 days.

What happens if I go over my plan?

Only views from AI agents and other bots count toward a plan; people are free. Recording continues: nothing is dropped or paused for going over. Plan owners see a usage meter in the sidebar and on each project's Plan tab, counting every project they own together. We email the owner twice at most each billing period: once at 80% of the allowance, and once past 100%. If both are crossed at once, only the second is sent. Unlimited plans have no meter and no emails.

How do I turn on two-factor sign-in?

On your account page, under Two-factor sign-in, enter your password and add Ethogram to an authenticator app such as 1Password, Google Authenticator or Authy: scan the QR code, or enter the setup key shown. Your email needs to be confirmed first. Enter the 6-digit code the app shows to turn it on. That signs you out on every other device, so each one signs in again with a code. You then get 10 backup codes, shown once: copy or download them and keep them somewhere safe. From then on, signing in asks for a code from the app after your password, or one backup code, each of which works once, whether you sign in with your password, with Google or from an email confirmation link. With your password you can make a new set of backup codes, which replaces the old ones, or turn two-factor sign-in off.

If you sign in with Google, add a password first: the account page emails you a link to choose one. After that, signing in with Google asks for your code too.

An owner can require two-factor sign-in for everyone on a project under Settings, Team, once they have it on themselves. Members who don't have it on are sent to set it up before they can open that project, its pages or its settings, and its alert and daily brief emails to them are paused until they do. If they'd rather not, they can leave the project from the same page; the only owner of a project can't leave it. Members who have it notice nothing, and the setting doesn't change access to any other project. Server keys and the collectors aren't affected, so events keep arriving.

If a member loses their phone and their backup codes, an owner of the project who has it on themselves can reset their two-factor sign-in from the member's menu under Settings, Team. That turns it off for their whole account and signs them out everywhere; they set it up again the next time they open a project that requires it. Owners can't reset another owner, themselves, someone who owns a project, or someone who's also in a project that requires it and that the owner doesn't own. In those cases, write to support@ethogram.si from your account's address.

How do I contact support?

Write to support@ethogram.si. Tell us your project's website and, if events aren't arriving, which collector you use and the status the API answers with.