# Track reference and guides

This is the reference and task guide for the developer who connects servers to Track during the pilot. It covers the key, sending events, the dashboard, every field, the response contract, retention, limits and what is not built yet. If you have not installed Track yet, start with the five-minute [getting started guide](/start).

Every request goes to `https://alg.katrinalaszlo.com`.

Part of agent-led-growth. Test it first: `npx agent-led-growth check <url>` audits your public pages for the seven onboarding steps (free, GET only); `npx agent-led-growth test <url>` runs a real agent through signup, key and first call, before you ship; Track measures which agents become customers after.


## Start here: the words Track uses

Track joins two vocabularies: the HTTP request your server handled, and the product analytics funnel. These words mean the following throughout this guide.

| Word | What it means here |
|---|---|
| `event` | One request your server handled and sent to Track. Section 5 lists its 23 fields. |
| `session` | The grouping unit Track builds. The API calls it a session; the dashboard calls the same object a journey. |
| `journey` | The dashboard's name for a session: a chain of requests linked by a cookie, a header, an issued key, an account id, a session hint, or the IP + User-Agent visit heuristic. The Journeys page lists one row per journey. |
| `visit` | A journey for an agent that keeps no cookie: requests sharing the same IP hash and exact User-Agent, split after 30 minutes of idle time, 2 hours from the first request, or at midnight UTC. Its journey says it was linked by "Same IP and user agent". |
| `outcome` | What your server records: signup, key created, activation, paid, or custom. A report calls a journey converted when it is credited a **paid** outcome. |
| conversion | A journey credited at least one paid outcome. Agent conversion is the number of paid agent journeys divided by the number of agent journeys. |
| `agent` | The program behind an inbound request: an LLM assistant, a crawler, a browser agent or an HTTP client. Track names it from the User-Agent or Signature-Agent header. |
| agent class | Known agent (`known_agent`: a shipped vendor User-Agent or a checked signature), declared agent (`declared_agent_assisted`: the agent named itself in Signature-Agent or in `properties.mcp_client` and nobody checked), automation (`suspected_automation`), human (`human`) or unknown (`unknown`). A known agent is not automatically verified. This is the traffic type filter. |
| `agent_type` | Crawler, assistant, browser agent or other. It is worked out when a report is read. |
| operator | The company behind the agent, such as OpenAI, Anthropic or Google. Also read-time, and shown on the Journeys page. |
| surface | The channel the agent arrived through: `chatgpt`, `claude`, `gemini`, `copilot`, `perplexity`, `browser_agent`, `crawler`, `other` or `none`. Read-time. `properties.surface` declares it; otherwise it is derived from the User-Agent token and the Signature-Agent host, or from `properties.mcp_client`. It cannot tell one ChatGPT surface from another by itself: a business listing and ordinary chat both arrive as ChatGPT-User or a `chatgpt.com` signature, so declare it. |
| `identity_tier` | Verified (`verified`: a signature was checked), declared (`declared`: the agent named itself), anonymous (`anonymous`: no claim), rejected (`rejected`: a signature failed) or not assessed (`not_assessed`: tiering could not run). Verified is only possible when signature checking is on for the project; older projects show "Not checked yet". |
| `handoff` | A person opens a link the agent sent, and their request joins the same journey. |
| attribution | The rule that credits a payment to the session that led to it. Section 5 has the exact rule. |
| forward | Send an accepted event to PostHog or GA4. Track is the source; those are destinations. |
| `workspace` | The account container. It holds projects, keys and every event. Signup creates one. |
| `project` | One traffic target inside a workspace. Every event carries its `project_id`. |
| workspace key | The key signup returns. It works across every project in the workspace, can sign in at `/login`, make claim links, and create, rename or delete projects. |
| project key | A key bound to one project. One made on the Install page or in Settings can send events and read that project; one from `alg connect` can send events and run install-check only. Neither can sign in, create projects or use MCP. |
| `scope` | What a key may do: read, write or run. Sending events needs write; reading reports needs read. |
| signup | The context names which one: a customer signup outcome, the Track account page at `/sign-up`, or `POST /v1/signup`, which creates a workspace for an agent. |
| claim link | The URL from signup that lets a person add the workspace to their Track account. It works for 7 days, and claiming does not change the key. |

"Session" and "journey" are the same object in this guide. The database and API call it a session; the dashboard calls it a journey. A visit is one way a journey can be built.

## Where Track fits

Track is not an edge firewall, a product analytics suite or a tracing tool. It is the layer that starts with the requests your API server handled and joins them to an account, a key and a payment.

- **Cloudflare and other edge tools.** They see requests at the edge. Their bot analytics are aggregated and often sampled. Track counts the requests your server handled and follows them into your product.
- **PostHog and GA4.** They are destinations. Once you turn forwarding on for a project, Track forwards every accepted event to them with the agent class, identity tier and journey id, but Track is the agent-aware source and the place that joins a request to a paying account. GA4 removes known bot traffic, so it cannot show this on its own.
- **LangSmith, Langfuse and Datadog.** Those trace the agent you build: prompts, spans and evaluations. Track measures the agents that call you.
- **AEO and GEO tools.** Those measure what models say about you. Track measures what agents did on your API.

## Quickstart

Two ways in. The first is the one we recommend: your coding agent does the whole install. Free during the pilot. No card, nothing to buy.

### With a coding agent

A coding agent (Claude Code, Cursor, Codex) can do the whole install, signup included. The install skill has a part for Express, for Fastify, and for FastAPI or Starlette, each with the same event names, redacted paths and hashes; for any other framework it tells the agent to send the same event from the hook that runs after the response (section 5), and the signup, check, results and hand-off steps are the same. Give it this prompt:

**Paste this into Cursor or Claude Code, not your terminal:**

```prompt
Read https://alg.katrinalaszlo.com/SKILL.md and follow it to install Track in this API.

Find the field in this codebase that identifies the customer (the user, org, or key id your auth resolves) and use it as the account id. Ask me only if it is genuinely ambiguous.

Add Track the way the skill says for this framework, send a few test requests, and run the install check until it says RESULT: PASS. Do not print or commit the key or salt. Finish by showing me the claim link.
```

What the agent does, and what you see at each step:

- **Step 1, signup.** It calls `POST /v1/signup?format=env` and appends `AGENT_TRAFFIC_KEY` to `.env` without printing it. It also writes a random `AGENT_TRAFFIC_ACCOUNT_SALT` for hashing customer ids; signup does not return a salt. You see no form, no email and no card: two new lines in `.env`, which it keeps out of git.
- **Step 2, install.** It adds the `@katrinalaszlo/track` npm package and two lines after `const app = express()`, and reads your auth code to find which field identifies your customer (see "Where sessions come from" in section 5). You see a small diff. If it can't tell which field to use, it asks you.
- **Step 3, check.** It sends a few test requests and runs `POST /v1/install-check`, which fails unless sessions, status codes and account ids arrive and the last 24 hours hold more than one distinct event name. The account-id line is the proof that `accountIdOf` returns your customer's id: an install that returns `undefined` passes nothing. You see PASS lines ending in `RESULT: PASS`; a FAIL line says what to fix, and the agent fixes it.
- **Step 4, hand-off.** It tells you which field it used and what production needs, and gives you a claim link. You open it, sign in or create an account, and choose "Add to my account": the workspace, its projects and everything the agent did are then in your account. The key keeps working. The link lasts 7 days; the agent can make a new one ("Claiming a workspace" in section 1). Rather not make an account? Open `https://alg.katrinalaszlo.com/login`, choose "Sign in with an API key instead" and paste the workspace key from `.env`. A project key from `alg connect` cannot sign in.

The skill is plain shell and one code edit, with nothing downloaded and run.

### Without an agent

- **Create an account** at `https://alg.katrinalaszlo.com/sign-up` with your email. Track makes your workspace and first project, shows your API key once, then opens the Install page with the snippet and a live check that turns green when your first event arrives.
- **Connect a terminal** once you have an account: `npx agent-led-growth connect` in your API's folder. You type the code it shows into the browser, approve, and a project key that can send events is written to `.env` ("Connect from a terminal" below).
- **Call the API yourself**: sections 1 and 2 below, with `curl`.

For agents and scripts, this guide is also served as markdown at `https://alg.katrinalaszlo.com/docs.md`, and `/docs` answers `Accept: text/markdown` with the same file. Every route is listed at `https://alg.katrinalaszlo.com/openapi.json` (OpenAPI 3.1) and `/v1/routes`. The rest of this guide is the manual path and the full reference.

### Pricing and managing your account

Free during the pilot. No card, nothing to buy; `https://alg.katrinalaszlo.com/pricing.json` says the same for agents. The limits are in section 9: up to 25 projects per workspace, up to 100 events in one `POST /v1/events`, raw events kept 14 days, and request limits per key and per project. A claim link works for 7 days; the workspace and its key do not expire.

An agent can manage the account with the same key: rotate it with `POST /v1/keys/rotate` ("Rotating a key" in section 3), create projects with `POST /v1/projects`, rename one with `PATCH /v1/projects/:id` and delete one, with everything stored for it, with `DELETE /v1/projects/:id` (not the workspace's only project). Revoking a key is in the dashboard, under Settings, Project and keys: project keys under Project keys, and the workspace's own keys under Workspace keys. Events are removed by a filter with `DELETE /v1/events` and a JSON body: at least one of `name` (exact), `name_prefix`, `path_prefix` and `before` (an ISO time), plus `after` if wanted; they combine with AND. Sent without `confirm` it deletes nothing and answers `400 confirmation_required` with `matched`, the number of events the filter matches, and the exact body to send. Sent again with `"confirm": <that number>` it deletes them and the sessions left empty (`409 count_changed` if the number changed meanwhile), at most 100,000 per request, and answers `{ project_id, matched, deleted, remaining, sessions_removed }`. It needs the `write` scope, so a key from `alg connect` cannot delete, and it cannot be undone. An agent that is done with a workspace it made (a test run, a wrong install) deletes it with `DELETE /v1/workspace`, the workspace key and the body `{"workspace":"<id>"}`: the projects, every event and the key go, and it cannot be undone. Sent without the body it deletes nothing and answers `400 confirmation_required` with the id and the exact body to send. Once a person has claimed the workspace a key can no longer delete it (`409 workspace_claimed`), and a workspace holding Score purchases or credits is kept (`409 workspace_has_purchases`).

## 1. Get your key and project

One call creates everything you need: a workspace, an API key for it, and a traffic project in it.

```sh
curl -sS -X POST https://alg.katrinalaszlo.com/v1/signup \
  -H "Content-Type: application/json" \
  -d '{ "label": "traffic pilot", "scopes": ["read", "write"] }'
```

The answer is `201` with:

```json
{
  "workspace": "ws550ebb4f031daf0b495b664b",
  "key": "ark_ws550ebb4f031daf0b495b664b_<64 hex characters>",
  "project_id": "485f7b24-5fa5-40fc-ad0b-136550b78db4",
  "claimed": false,
  "scopes": ["read", "write"],
  "message": "Send this key as Authorization: Bearer. It is shown once and cannot be recovered. Send events to POST /v1/events?project_id=<project_id>. Give claim_url to the person you work for: opening it signed in adds this workspace to their Track account, and the key keeps working.",
  "claim_url": "https://alg.katrinalaszlo.com/claim/<64 hex characters>",
  "claim_expires_at": "2026-10-30T18:04:11.000Z",
  "claim": {
    "status": "unclaimed",
    "url": "https://alg.katrinalaszlo.com/claim/<64 hex characters>",
    "expires_at": "2026-10-30T18:04:11.000Z",
    "window_days": 7,
    "check": "GET /v1/claim",
    "reissue": "POST /v1/claim-link",
    "key_changes_on_claim": false,
    "tell_the_person": "Open https://alg.katrinalaszlo.com/claim/<…> to add this workspace to your Track account. The link works until 2026-10-30 18:04 UTC.",
    "after_the_person_claims": "Call GET /v1/claim: claimed turns true. Your key keeps working, so carry on with it.",
    "what_the_person_gets": "The workspace joins their Track account: every project in it, the events stored so far, the agent log and the keys. They can make, rotate and revoke keys under Settings.",
    "key_after_claim": "The key keeps working after the claim. It does not change, and nothing the agent set up stops.",
    "cost_and_limits": "Free during the pilot, no card. Raw events are kept 14 days, a workspace holds up to 25 projects, and request limits apply: https://alg.katrinalaszlo.com/docs#request-limits",
    "if_unclaimed": "Nothing is deleted. The workspace keeps working with the key, and only someone holding the key can see it (sign in at /login with the key). The link stops working after 7 days. Make a new one yourself: POST /v1/claim-link with this key returns a new claim_url. Earlier links keep working until they expire."
  },
  "claimCode": "clm_ws550ebb4f031daf0b495b664b_<64 hex characters>"
}
```

`POST /v1/signup?format=env` answers `text/plain` with one `AGENT_TRAFFIC_KEY=` line and a claim-link comment, so an agent can append it to `.env` without printing the key. It does not include a `project_id` line (the key already names the workspace's only project) and it does not include a salt.

- **`key`** is shown once and only its hash is stored, so save it in your secret store right away. Send it as `Authorization: Bearer <key>`. The `ws…` part between `ark_` and the next underscore is your workspace id.
- **`project_id`** names the traffic project signup created for you, named after your `label` (or `default` without one). Every event goes to this project.
- **`scopes`**: sending events needs `write`, and reading your data needs `read`, so ask for both. If you leave `scopes` out, the key gets all three (`read`, `write` and `run`; nothing in this guide uses `run`). A key cannot be widened later, so a key created with only `read` will never be able to send events, Signup still returns a claim link for it, because you just made the workspace, but only a workspace key with `write` can make another one later.
- **`claim_url`**, **`claim_expires_at`** and **`claim`**: the link that hands the workspace to a person, when it stops working, and the same facts as fields an agent can read. Give the link to the person you work for. See "Claiming a workspace" below.
- **`claimCode`**: Track does not use it. It is there because Track shares workspaces with Score, Tanso's agent testing product, where a signed-in person redeems it to own the workspace there. Claiming in either place spends it, so a workspace has one owner. If you do not use Score, ignore it.
- **Expiry**: a workspace and its key do not expire, claimed or not. A key stops working only when it is revoked, or when it is rotated and its grace window ends. Only the claim link expires.
- **Account status**: `GET /v1/claim` says whether a person has claimed the workspace. To check that a key works and what it can reach, call `GET /v1/traffic/agent-log` (the signup, keys and projects, newest first; `read` scope) or `POST /v1/install-check` (each project the key reaches, and whether its events arrive).
- **Limits**: signup allows 20 workspaces an hour per address and 300 an hour in all; every request limit is in [section 9, Request limits](/docs#request-limits). A limit answers `429` with `Retry-After`.

### Claiming a workspace

An agent can set Track up with no person: signup needs no account, email or card. The person it works for takes the workspace over later with the claim link.

- **Who can make one**: only a workspace key with the `write` scope, the key signup returns. A link hands over the whole workspace, so a read-only key or a key made for one project never gets one, from any route.
- **The link**: `claim_url` from signup, `https://alg.katrinalaszlo.com/claim/<token>`. The install check, run with the workspace key, prints a fresh one as its last line, and `?format=env` signup writes one as a comment after the key (`# Claim this workspace: <url> (link valid until 2026-10-31 05:48 UTC)`). Run with another key, the install check's last line says which key makes the link. Each link made is in the agent log as "Made a claim link", with what made it and when it stops working, never the link itself. The person opens it, signs in or creates an account, sees the workspace (its name, when and by what it was made, its projects, its events so far and what the agent did) and chooses "Add to my account". Track then opens the agent log, which starts with everything the agent did.
- **The window**: a link works for 7 days, or until it is used. After that the workspace and its key keep working exactly as before; only the link stops. Nothing is deleted.
- **Re-issuing**: `POST /v1/claim-link` with the workspace key (`write` scope) answers `201` with a new `claim_url`, `claim_expires_at` and `claim`. Earlier links keep working until they expire. A project key cannot make one (`403 project_key`), nor can a key without `write` (`403 insufficient_scope`); their `next_step` names the workspace key from signup, and if that key is lost, start a new workspace: only whoever holds it can hand this one over.
- **Checking**: `GET /v1/claim` (any key of the workspace) answers `claimed`, `claimed_at`, `status` (`claimed`, `unclaimed` or `unclaimed_link_expired`), `claim_expires_at` of the newest unused link, `live_claim_links` (unused links that still work), `key_changes_on_claim` (`false`), `can_make_claim_links` (whether this key can make one), `how_to_reissue` and `next_step`. It never makes a link. `claim_url` is always `null` there: Track keeps only a hash of each link, so it cannot show one again. After the person says they claimed it, call `GET /v1/claim`, see `claimed: true`, and carry on.
- **What the person gets**: every project in the workspace, the events stored so far, the agent log and the keys. They can make, rotate and revoke keys under Settings. A person who already has a workspace gets this one beside it and switches between them under Workspaces in the project menu.
- **Credentials**: the key does not change on a claim. It keeps working, with the same scopes, until someone rotates or revokes it.
- **Cost and limits**: free during the pilot, no card. Raw events are kept 14 days, a workspace holds up to 25 projects, and the request limits in section 9 apply, claimed or not.
- **Left unclaimed**: nothing is deleted. The workspace keeps working with the key, and only someone holding the workspace key can see it, by signing in at `/login` with that key. A project key cannot sign in.
- **One owner**: once claimed, another person's link answers "Already claimed", and `POST /v1/claim-link` answers `409 already_claimed`: there is nothing to claim, so carry on with the key.

Three things that can look alike, and which Track needs:

- **Claiming** is a person taking ownership of what an agent made. Track needs it only for the workspace to show up in a person's account; the agent's key works without it.
- **Approving** is a person allowing a key for a terminal (`alg connect`, "Connect from a terminal" below). Track needs it only when a CLI asks for a key that way.
- **Inbox verification** (a code or link sent to an email address) proves someone reads that inbox. Track has none and needs none: signup takes no email, and the claim link is shown to the agent, which hands it to the person.

You do not need to ask us to create a project. For a second one, use the "New project" button in the dashboard, `POST /v1/projects`, or the "New project" option when you connect a terminal. A workspace holds up to 25 projects. `GET /v1/projects` (`read` scope) lists them with their `project_id`; a key made for one project sees only its own.

### One value is enough

Your server needs one variable: `AGENT_TRAFFIC_KEY`. `AGENT_TRAFFIC_PROJECT_ID` is optional.

- **A project key** is made for one project and works on that project only. Every route that takes `project_id` uses the key's project when you leave it out, and answers `404 not_found` for any other project. Make one in the dashboard under Settings, Project and keys, or on the Install page, "Create a new key" (shown once, with a list of the project's keys and a Revoke button for each): it can send events and handoffs to the project and read it (reports, rejections, forwarding status and `POST /v1/install-check`). A key from `alg connect` below can only send events and handoffs and run `POST /v1/install-check` for its project: it cannot read reports, change forwarding or the funnel, or rename the project (`403 insufficient_scope`). No project key can sign in to the dashboard, create or delete projects, or use MCP.
- **A workspace key** (the one signup returns) works for every project. With `project_id` left out it uses the workspace's only project; once the workspace has more than one, it answers `400 project_id_required`, so pass `project_id` or switch the server to a project key.

### Connect from a terminal

`alg connect` (printed as `npx agent-led-growth connect` in the quickstart) gets a project key without copying a key. It prints a code and opens `/connect`; signed in, you type the code from your terminal. The page then shows when and from where the login was started (city and country, and the address cut to its network), the user agent, the name the program gave (which nothing checks) and your workspace. Only approve a login you started yourself in the last few minutes. Pick a project (or make a new one) and approve; the CLI then receives a new key bound to that project that can send events and handoffs and nothing else. A link that carries a code does not skip typing it, so nobody can send you a link that approves their login. After 10 wrong codes in 15 minutes, from one workspace or one address, codes are refused until the 15 minutes end. The flow it uses:

- `POST /v1/connect/start` with `{ "client": "agent-led-growth" }` answers `201` with `device_code` (the CLI's secret), `user_code` (`XXXX-XXXX`, for the person to type), `verification_url` (`/connect`, with no code), `expires_in` (600 seconds) and `interval` (3 seconds).
- `POST /v1/connect/poll` with `{ "device_code": "…" }`, every `interval` seconds, answers `202 { "status": "pending" }` until you decide, `429 { "error": "slow_down" }` when polled faster, `200 { "key", "project_id", "project_name", "endpoint" }` once after approval, `403 { "error": "denied" }` after Deny, and `410 { "error": "expired" }` after 10 minutes or once the key was collected.

An agent uses the same two requests to read a project its person already has, without anyone pasting a key: send `"scopes": ["read"]` with the start (`{ "client": "claude-code", "scopes": ["read"] }`), show the person `verification_url` and `user_code`, and poll. The approve page then says, first and in bold, that the key can read the reports of the project they pick. `scopes` is optional and drawn from `events` (send events) and `read` (read that project's reports); left out it is `["events"]`, and both answers are exactly as above. When it is sent, both answers also carry `scopes`. `write` cannot be asked for: a device login can never delete data, change forwarding or manage projects.

Track stores only hashes of both codes, with the coarse place and the user agent of the start request, and deletes the login a day after it expires. It makes the key at the moment the CLI collects it, so the key is never stored anywhere waiting to be picked up. The key is labelled `alg connect: <client>` in Settings.

## 2. Send your first events

Events go to `POST /v1/events`, with your `project_id` in the query string and a JSON array of events as the body. This call sends two events of one session: an agent reads your docs, then gets a 401 from your API.

```sh
AGENT_TRAFFIC_KEY="ark_ws..."         # from signup
PROJECT_ID="..."               # from signup
DOCS_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
sleep 1
CALL_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)

curl -sS -X POST "https://alg.katrinalaszlo.com/v1/events?project_id=$PROJECT_ID" \
  -H "Authorization: Bearer $AGENT_TRAFFIC_KEY" \
  -H "Content-Type: application/json" \
  -d "[
    { \"idempotency_key\": \"first-1\", \"name\": \"docs_view\", \"occurred_at\": \"$DOCS_AT\", \"source\": \"sdk\",
      \"session_hint\": \"first-run\", \"user_agent\": \"Claude-User (claude-code/2.1)\" },
    { \"idempotency_key\": \"first-2\", \"name\": \"api_call\", \"occurred_at\": \"$CALL_AT\", \"source\": \"sdk\",
      \"session_hint\": \"first-run\", \"user_agent\": \"Claude-User (claude-code/2.1)\",
      \"properties\": { \"status_code\": 401, \"error\": \"Unauthorized: invalid API key\" } }
  ]"
```

The answer is `202` with:

```json
{
  "accepted": 2,
  "rejected": []
}
```

Always check `accepted` and `rejected`, not only the status: a `202` means Track read the batch, not that it wrote every event (section 6).

Two mistakes look like success or like a missing project:

- **Wrapping the array.** A body of `{ "events": [ ... ] }` is read as one event with an unknown field. The answer is `202` with `"accepted": 0` and a rejected entry with reason `unknown_field`. Send the array itself.
- **Leaving out `?project_id=` with a workspace key in a workspace with several projects.** The answer is `400 project_id_required`. With a project key, or a workspace that has one project, `project_id` can be left out.

A single event without a `session_hint` or `account_id` is accepted and counted in your totals. If it comes from an agent and carries an `ip_hash` and a `user_agent`, it is grouped with that agent's other requests into one visit (section 5, "Where sessions come from"). Otherwise it is unattributed: it belongs to no session, so it appears in no path, in no Fix next entry and in no agent's row. In production, send a hashed `account_id` on every request that has a customer behind it (section 5, "Where sessions come from").

## 3. Viewing your dashboard

Open `https://alg.katrinalaszlo.com/login`, paste your API key and submit (the form's one field is named `key`). The key must have the `read` scope. Track checks it and keeps it in a cookie on that browser for 30 days, then sends you to your dashboard. The cookie is `HttpOnly` (page scripts cannot read it; the only page script is the install page's live check, which calls the API with the cookie but cannot read it), `Secure` and `SameSite=Lax`. The key never appears in a URL. The dashboard has pages for Overview, Funnel, Paths, Attribution, Friction, Journeys, Agent log, Install and Settings. The old Agents and Conversions addresses redirect to Overview and Attribution. "Sign out" in the top bar clears the cookie; it is a POST, so a link prefetch cannot sign you out.

Every report page has a date range (7, 30 or 90 days; 7 by default) and a traffic type filter (Known agent, Declared agent, Automation, Human, Unknown; all by default), as plain links, so a URL is a saved view (`?days=30&type=known_agent`). Journeys adds read-time facets to the same URL: `?operator=openai`, `?surface=chatgpt`, `?agent_type=assistant`, `?identity_tier=verified`, `?linked_by=cookie` and `?handoff=true`. The five traffic types keep their meaning; the facets are additive. Two counting rules apply, and each card says which one it uses:

- **Events in the last N days**: event counts (the events line under Journeys per day, how events identified themselves, and sources) count events by when they happened.
- **Sessions that started in the last N days**: everything built from sessions (journeys per day, failed sessions, agents, the funnel, paths, attribution, friction) counts sessions that started in the range, with all their events. An outcome credited to a session counts with that session; an outcome credited to none counts when it happened.

Raw events are kept for your raw retention (14 days by default). With a longer range, the cards built from raw events say what they actually cover; Journeys per day comes from the daily snapshots and covers the whole range, except days written before snapshots recorded journeys (before `coverage-4`): those show a dotted stub with their event count, never a zero. How events identified themselves and their sources are not split by traffic type, so those cards are hidden while a type is selected. An event or outcome in no session counts as Unknown.

The pages:

- **Overview**: agent journeys, agent conversion, agent revenue, human handoffs and agents against humans; journeys per day (for each UTC day and today so far, agent journeys stacked under other journeys, and agent conversion, the share of that day's agent journeys credited a payment, as a line on the right-hand axis; a hollow point means under 20 agent journeys that day, and the tooltip and the daily breakdown keep the day's events); every agent with its success and failure rates; journeys by traffic type; Fix next; the latest journeys; and, for your own projects, how events identified themselves, their sources and the daily breakdown.
- **Funnel**: how many sessions reach each step, the share of the start, the drop from the step before and the median time from it. The default steps are signup, key created and paid; a step is an event name your sessions send or an outcome credited to them. Steps under 20 sessions are marked too few to read.
- **Paths**: the most common event sequences, and which ones end in an error.
- **Attribution**: signups, keys, activations and payments your server reported with `recordOutcome` (section 5), with revenue per currency, by the class of agent whose session led to them, and the list of outcomes.
- **Friction**: Fix next, what each agent tried and where it failed (each cell lists its sessions), what sessions did first, and one failed session per error, event by event. Each session opens a page with every event and its properties as you sent them.
- **Journeys**: every journey that started in the range, with its entry, steps, duration, credited outcomes, identity evidence and how its events were linked. Filter by outcome, traffic type, **operator**, **surface**, agent type, identity evidence, linkage, or a person taking over. Every row shows its evidence tier; crawlers and automation are grouped below the counted agent journeys. Open one for its trust strip, timing strip, phases and per-event evidence.
- **Agent log**: what agents and people changed in the project and its keys, newest first, the same entries as the agent log API below.

**Day one.** When you open the dashboard and events have arrived since the last refresh, Track builds sessions before showing the page, at most once a minute. So the sessions from section 2 show up as soon as you load the page, not the next day. If that refresh takes more than 20 seconds, the page shows what it has, with a banner giving the time of the data.

Daily coverage is different: it counts complete UTC days only, and the snapshot job runs at 02:00 UTC. On your first day the top total is labeled "so far, not yet in a daily snapshot", and the coverage card says when the first snapshot will be ready, for example "First snapshot available after 02:00 UTC on 2026-10-21". The two agree from then on.

To refresh from your own code instead of by opening the page:

```sh
curl -sS -X POST https://alg.katrinalaszlo.com/api/refresh \
  -H "Authorization: Bearer $AGENT_TRAFFIC_KEY" \
  -H "Content-Type: application/json" \
  -d "{ \"project_id\": \"$PROJECT_ID\" }"
```

The answer is `200` with `{ "success": true }`. It needs a key with `read`, and answers `404` for a project outside your workspace.

### Rotating a key

If a key leaks, or on a schedule, rotate it. The key in `Authorization` mints its successor with the same scopes; the old key keeps working for a grace window (24 hours unless you say otherwise, up to 168) so you can switch every service that holds it and restart them, then it answers `401 key_rotated`. Any key can rotate itself, whatever its scopes. A key that has been rotated cannot rotate again; its successor can.

```sh
curl -sS -X POST https://alg.katrinalaszlo.com/v1/keys/rotate \
  -H "Authorization: Bearer $AGENT_TRAFFIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "grace_hours": 24 }'
```

The answer is `201` with `key` (shown once), `scopes`, `grace_until` and a `message` saying what to do. `?format=env` answers one `AGENT_TRAFFIC_KEY=` line instead, to replace the one in your `.env`. A project key rotates the same way and its successor keeps the project. The middleware reads the key when the process starts, so replacing the line is not enough: restart or redeploy every service before `grace_until`. While the old key is inside its grace window, every `202` it earns on `POST /v1/events` carries a `warnings` array saying when it stops working; the middleware logs that once per process.

If someone else rotated a leaked key, rotation alone does not get it back: they hold the successor. In the dashboard, under Settings, Workspace keys lists every workspace key that still works, with when it was made, its last four characters and which key it was rotated from. Signed in with your account, or with a key that has the write scope, you can Revoke any of them (it stops at once, even inside a grace window) except the key your browser signed in with, and Rotate now makes a new key with the same scopes and stops the old one at once, even one already inside a grace window.

### Forwarding events to PostHog

If your team already lives in PostHog, forward every accepted event there too and read agent traffic next to the rest. Events from the browser snippet are the exception: they go to PostHog and GA4 only after you turn that on for the project ("Browser snippet" in section 5). Send the project token (`phc_…`, the public write-only key from your PostHog project settings) and the region your project is in. A token that does not start with `phc_` is refused with `400 invalid_field`; a personal API key (`phx_…`) is a secret and is never stored. Changing forwarding, here or in Settings, needs a key with the `write` scope:

```sh
curl -sS -X PUT https://alg.katrinalaszlo.com/v1/traffic/sink \
  -H "Authorization: Bearer $AGENT_TRAFFIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "project_id": "'$PROJECT_ID'", "posthog": { "api_key": "phc_…", "region": "us" } }'
```

Each event arrives in PostHog under its own name, with the properties the event carried plus these, so you can filter by agent in PostHog:

| Property | Value |
|---|---|
| `agent` | the agent Track names for that request, as the journey pages show it: `ChatGPT-User`, `PerplexityBot`, `Chrome`, `curl`, or the host of its Signature-Agent |
| `agent_class` | the class Track gives that one request: `known_agent`, `declared_agent_assisted`, `suspected_automation`, `human` or `unknown`. Left out if classification failed for that batch |
| `agent_type` | what kind of agent sent it: `crawler`, `assistant`, `browser_agent` or `other` (Agent types, section 7), or `null` when `agent_class` is `human` or `unknown`. Left out if classification failed for that batch |
| `path` | the request path as stored, such as `/docs/quickstart`. Left out when none was stored, so a `path` the event's own properties carried stays |
| `journey_id`, `journey_source` | the journey key and where it came from (`cookie`, `header`, `query`, `issued`, `handoff`), or `null` |
| `identity_tier`, `identity_tier_confidence` | how sure Track is who sent it |
| `signature_agent` | the Signature-Agent header as sent, or `null` |
| `session_id`, `run_id`, `account_id` | the session hint, run hint and account id the event carried, or `null` |
| `name`, `source` | the event name and where it came from (`middleware`, `sdk`, `log`) |
| `agent_traffic_event_id`, `agent_traffic_project_id` | the event and project ids in Track |
| `outcome_name` | only on an event that recorded an outcome: `signup`, `key_created`, `activation`, `paid` or `custom` |
| `value`, `value_minor`, `currency` | only on an outcome with a value: `value` in major units (`49` for 4900 cents), `value_minor` as sent (`4900`), the ISO currency code |

The raw User-Agent is not sent: it is long, can identify a person's browser, and `agent` and `agent_class` already say what it means. `distinct_id` is the account id when the event has one, else the session hint, else the event id, and no person profile is created (`$process_person_profile` is `false`, and nothing is `$set`). GeoIP is off (`$geoip_disable`), because the request comes from Track's server and PostHog would otherwise place every event at the server's location. Events forwarded before 2026-10-24 lack `agent`, `agent_class`, `path`, `journey_id`, `journey_source` and the outcome fields, and `agent_type` was added on 2026-10-24 (UTC): events forwarded before then lack it, and so may events forwarded that day before about 03:30 UTC. Needs the `write` scope. `"posthog": null` turns it off. A PostHog failure never rejects an event; the event is stored here either way. Forwarding starts after `POST /v1/events` has answered, so it never slows the `202` down, and the `202` says nothing about it. To see whether it worked, read `GET /v1/traffic/sink` (`read` scope, `?project_id=` optional):

```sh
curl -sS https://alg.katrinalaszlo.com/v1/traffic/sink \
  -H "Authorization: Bearer $AGENT_TRAFFIC_KEY"
```

```json
{
  "project_id": "…",
  "posthog": { "api_key": "phc_oPy…", "region": "us", "last_sent_at": "2026-10-23T18:02:11.000Z", "last_failed_at": null, "last_error": null, "events_sent": 42, "events_failed": 0 },
  "ga4": null
}
```

Each destination is `null` when off. The token shows only its first 7 characters. `last_error` is a short message, such as `PostHog: 1 of 1 events failed: PostHog answered 401 for event …`, and never contains a token or secret. `events_sent` and `events_failed` are totals. The same status shows in Settings under the PostHog and GA4 cards ("Last sent …", or the last error), and `POST /v1/install-check` adds a forwarding line for each destination that is on.

### Forwarding events to GA4

To see agent traffic in Google Analytics 4 as well, open Settings, GA4, and enter the Measurement ID (`G-…`) and a Measurement Protocol API secret from the same web stream (GA4 Admin, Data streams, Measurement Protocol API secrets). The secret is stored encrypted and never shown again; to change only the Measurement ID, leave the secret blank. Events are sent through the Measurement Protocol, up to 25 to a request and grouped by client: `client_id` is the journey key, else the session hint, else a hash of the account id. Each event keeps its name (cut to 40 characters) and carries these parameters, each left out when it has no value:

| Parameter | Value |
|---|---|
| `agent` | the agent Track names for that request, as in PostHog |
| `agent_class` | `known_agent`, `declared_agent_assisted`, `suspected_automation`, `human` or `unknown`. Left out if classification failed for that batch |
| `agent_type` | `crawler`, `assistant`, `browser_agent` or `other`, as in PostHog. Left out for a human or unknown request, and if classification failed for that batch |
| `path` | the request path as stored |
| `journey_id`, `journey_source` | the journey key and where it came from |
| `identity_tier`, `source`, `occurred_at` | as in PostHog; `occurred_at` as an ISO timestamp |
| `track_session_id`, `track_event_id` | the session hint and the event id in Track |
| `outcome_name` | only on an event that recorded an outcome |
| `value`, `currency` | only on an outcome with a value: GA4's own `value` (a number, in major units: `49` for 4900 cents) and `currency` (the ISO code) |
| `value_minor` | the same value in minor units, as sent (`4900`) |

A `paid` outcome with a value is sent as GA4's recommended `purchase` event instead of under its own name, so it counts in GA4's revenue reports (Purchase revenue, Total revenue, Monetization). It carries everything above plus:

| Parameter | Value |
|---|---|
| `transaction_id` | the event id in Track. It stays the same if the event is sent again, so GA4 drops the repeat instead of counting the revenue twice |
| `track_event_name` | the event's own name in Track, such as `checkout_completed` |
| `items` | one item: `item_name` is the event's own name, `price` is the value, `quantity` is 1 |

The event is sent once, as `purchase`, not also under its own name, so no payment is counted twice in GA4. To report on the original name, register `track_event_name` as a custom dimension in GA4. A `paid` outcome without a value, and every other outcome, keeps its own name.

GA4 limits apply: text values, such as a long path, are cut to 100 characters, and an event takes at most 25 parameters. Track's take up to 15 (18 on a `purchase`, counting `items`), so at most 10 (7 on a `purchase`) of the event's own text, number and true/false properties are added, in the order the event sent them; the rest are not sent to GA4 (they are still stored here and forwarded to PostHog). The raw User-Agent is not sent. Events forwarded before 2026-10-24 lack `agent`, `agent_class`, `journey_id`, `journey_source` and the outcome parameters, and `agent_type` was added on 2026-10-24 (UTC): events forwarded before then lack it, and so may events forwarded that day before about 03:30 UTC. Events older than 72 hours, which GA4 will not backdate, are recorded at the time they are sent. Like PostHog, a GA4 failure never rejects an event, and its status is in `GET /v1/traffic/sink` under `ga4`, in Settings and in install-check.

### Setting the funnel

The funnel is the ordered list of event names the Paths funnel counts sessions through. Set it in Settings, Funnel, one step per line (the line format is below), or through the API:

```sh
curl -sS -X PUT https://alg.katrinalaszlo.com/v1/traffic/funnel \
  -H "Authorization: Bearer $AGENT_TRAFFIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "project_id": "'$PROJECT_ID'", "steps": ["signup", "key_created", "paid"] }'
```

A funnel has 2 to 12 steps, each with its own name. Every save is kept as a new version and the answer says which (`version`); reports use the newest. Needs the `write` scope.

A step can also be an object, when the event that reaches it has another name or must carry a path:

```json
{ "steps": ["signup", { "name": "create_key", "event": "keys_post", "path": "/v1/keys" }, "first_api_call"] }
```

`name` is the step. `event` is the event name that reaches it (default: `name`). `path` is optional: only that event on that path counts. It is stored the way ingest stores paths (query cut, tokens redacted). Two steps cannot be reached by the same event on the same path, and `onboarding_step` and `error` cannot be steps (they name their step in `properties.step`). `from_browser` is optional, default `false`: events from the browser snippet reach a step only when it is `true`, because anyone with the project's public key can send them ("Browser snippet" below). The answer lists the names in `steps` and the full steps in `step_details`, with `from_browser: true` on the steps that have it.

In Settings, Funnel, each line is one step: its name, then, if they differ, the event name that reaches it, then a path starting with `/` if only that path counts, then `+browser` if browser snippet events may reach it. `create_key keys_post /v1/keys` is the object above; `signup` alone is a step reached by `signup`; `pricing_cta cta_clicked /pricing +browser` is reached by the snippet's `track("cta_clicked")` on `/pricing`.

The funnel is the one list of steps in Track. The Funnel page counts sessions through it, and the Friction page and `GET /v1/traffic/onboarding` add errors and retries for the same steps (section 5, "Onboarding steps").

### Checking sessions through the API

The dashboard's session sections come from `GET /v1/traffic/paths`, which works on day one, unlike coverage. Refresh first, then read the last day:

```sh
curl -sS "https://alg.katrinalaszlo.com/v1/traffic/paths?project_id=$PROJECT_ID&days=1" \
  -H "Authorization: Bearer $AGENT_TRAFFIC_KEY"
```

The answer has `events`, `unattributed_events`, `sessions`, `terminal_counts` (how many sessions ended in `success`, `failure` or `unknown`), `terminal_rules` (how many endings came from a recorded `status_code` or a `name_heuristic`), the top `paths` with their `steps`, `sessions_by_agent_type` (sessions per agent type for known and declared agents, then `automation` for suspected automation and `not_agent` for human and unknown sessions; Agent types, section 7), and the `agents` (each with its `bucket` and `agent_type`), `intents`, `fix_next` (each error with `failed_at`, the event most of its sessions ended on, and `failed_at_steps`, every event it ended sessions on and how many) and `failure_timelines` the dashboard shows. Each path, the `conversion` total and the `pages` table also say how many of those sessions paid and for how much (Paths conversion, section 5); `sort=converting` orders the paths by conversion instead of by sessions. `days` follows the same rule as coverage (1 to 90). An install passes when events and sessions are present, at least one session ends with a recorded status code, and the last 24 hours hold more than one distinct event name (every name counts, outcomes included). A failure guessed from its name does not prove status instrumentation works. `POST /v1/install-check` runs these checks for every project in your workspace, after refreshing, and answers plain text with a PASS, FAIL or WARN line per check. It also warns about events rejected and requests refused in the last 24 hours (section 6), and adds a line per forwarding destination that is on: when it last sent, or its last error:

```sh
curl -sS -X POST https://alg.katrinalaszlo.com/v1/install-check \
  -H "Authorization: Bearer $AGENT_TRAFFIC_KEY"
```

### Agent log

When an agent sets Track up for you, the agent log says what it did: signups, claim links made, keys created, rotated and revoked, projects created, renamed and deleted, forwarding and funnel changes, and terminal logins approved or denied. People's changes in the dashboard are there too. Read it with a `read` key:

```sh
curl -sS "https://alg.katrinalaszlo.com/v1/traffic/agent-log?project_id=$PROJECT_ID" \
  -H "Authorization: Bearer $AGENT_TRAFFIC_KEY"
```

```json
{
  "project_id": "…",
  "entries": [
    {
      "audit_id": "…",
      "occurred_at": "2026-10-23T18:02:11.000Z",
      "action": "key.rotate",
      "action_text": "Rotated a key",
      "actor": { "type": "key", "label": "Key …a1b2", "key_last4": "a1b2", "agent": "alg connect: claude-code", "person_id": null },
      "target": { "type": "key", "id": "key_0123456789ab", "label": "Key …c3d4" },
      "project_id": "…",
      "details": { "replaced": "Key …a1b2", "scopes": ["write"], "grace_until": "2026-10-24T18:02:11.000Z", "via": null },
      "reason": null
    }
  ],
  "next_before": null
}
```

Entries are newest first, 50 a page (`?limit=` 1 to 100); pass `next_before` back as `?before=` for the next page, and it is `null` on the last one. An actor is a key, named by the last four characters of its secret and its label (for a workspace key, the label given at signup; for a key made by `alg connect`, the client that asked), or `person` for someone signed in to the dashboard. `details` holds a few fields picked per action, such as the new name of a renamed project or the steps of a funnel; the log never shows a key, a hash of one, a PostHog token or a GA4 secret. Without `project_id`, a workspace key reads every project. With it, you get that project's entries plus actions on workspace keys, which reach every project. A key made for one project reads only that project's entries, without the workspace-key actions, and `person_id` is always `null` for it. Entries start when the action shipped, on 2026-10-24 (UTC): signups before then have no entry.

## 3b. Ask your coding agent

The same reports are readable over the Model Context Protocol, so Claude Code, Cursor or Codex can answer "which agents paid this week" or "why did Cursor's sessions fail" from your terminal. The server is `POST https://alg.katrinalaszlo.com/mcp`: streamable HTTP, stateless (no session to open), read-only, and it takes the same key as the API in `Authorization: Bearer`. The key needs the `read` scope; a key without it gets a JSON-RPC error. The server is listed in the official MCP registry as `io.github.katrinalaszlo/track`.

Claude Code:

```sh
claude mcp add --transport http agent-traffic https://alg.katrinalaszlo.com/mcp --header "Authorization: Bearer $AGENT_TRAFFIC_KEY"
```

Cursor (`.cursor/mcp.json`) and Codex (`~/.codex/config.toml` uses the same fields under `[mcp_servers.agent-traffic]`):

```json
{ "mcpServers": { "agent-traffic": { "url": "https://alg.katrinalaszlo.com/mcp", "headers": { "Authorization": "Bearer <your AGENT_TRAFFIC_KEY>" } } } }
```

| Tool | Arguments | Answers |
|---|---|---|
| `list_projects` | none | your projects: `project_id`, `name`, `created_at`, `verified_tier_enabled` |
| `traffic_coverage` | `project_id`, `days` (1 to 90, default 30), `type` | the `GET /v1/traffic/coverage` body: events per complete UTC day by tier, class and source, journeys that started that day per class with paid journeys and revenue (`journeys`, `null` before `coverage-4`), and `today` with the same counts for today so far; with `type`, each day and `today` also have `type_requests` |
| `traffic_paths` | `project_id`, `days`, `type`, `sort` (common, converting) | the `GET /v1/traffic/paths` body for sessions that started in the range: paths with paid sessions, conversion and revenue, the pages and files table, agents with class and failure rates, intents, `fix_next`, timelines, the funnel |
| `onboarding_steps` | `project_id`, `days`, `type` | the `GET /v1/traffic/onboarding` body: your funnel's steps with reached, continued, dropped, median times, errors and retries per step, the worst step, splits by type and agent, and `seen_steps` (see "Onboarding steps" in section 5) |
| `conversions` | `project_id`, `days`, `type`, `kind` (signup, key_created, activation, paid, custom) | outcomes by agent class with paid revenue per currency; `kind` adds that kind's count |
| `journeys` | `project_id`, `days`, `type`, `outcome` (paid, signup, none), `surface`, `before` | sessions that started in the range, newest first, 50 at a time: agent, class, agent type, operator, surface, entry, steps, duration, credited outcomes, how their events were linked; `surfaces` counts what each arrival surface did (journeys, signups, paid, conversion, revenue); `tools` counts the MCP tool calls in those journeys (tool, calls, failed, journeys, median duration); `next_before` pages on |
| `attribution` | `project_id`, `days`, `type`, `model` (first_touch, last_touch, linear), `dimension` (path, agent, surface) | credit for paid outcomes per currency by page or file, by agent, or by arrival surface, under all three models, ordered by `model`, with Other and Unattributed rows, and how each payment was linked to a session (see Attribution in section 5) |
| `install_check` | `project_id` | refreshes the project, then `ok` and the PASS/FAIL/WARN lines of `POST /v1/install-check` for it |
| `agent_log` | `project_id` (optional), `before` | the `GET /v1/traffic/agent-log` body: what agents and people changed in the workspace, newest first, 50 at a time (see Agent log in section 3) |

`type` is one of `known_agent`, `declared_agent_assisted`, `suspected_automation`, `human`, `unknown`; an event or outcome in no session counts as `unknown`. A refused call (unknown project, bad `days` or `type`) comes back as a tool result with `isError: true` and the API's status, code and message, so the agent can correct its arguments. The server offers no write tool: nothing an agent does here changes your workspace.

## 4. What data goes where

| Field | What it drives | Without it |
| --- | --- | --- |
| `journey_id` | Sessions first. Every event with the same journey key is one session (a journey), with no idle timeout, whether the key came from the `track_j` cookie, the `Track-Journey` header or the `?track_j=` query parameter. The first account seen on a journey owns it: the journey's earlier anonymous events count for that account, and the account's later events without a journey key (a payment webhook) join it. When a different account appears on the same journey (someone else logs in on the same browser), it gets a session of its own, and its payments are never credited to the first account. Anonymous events go with the account seen most recently on the journey. A key your server issued on a request (`journey_source` `issued`) counts as a journey only once it comes back: until then a request on it that carries an `account_id` is grouped by that account, so an agent that keeps no cookies, and gets a new key on every request, is one session per account and not one per request. When the key comes back (cookie, header, query parameter or a handoff link), the journey continues in that first request's session. An event without a journey key that happened at the same moment as a journey event of the same account (an outcome recorded while the request was served) joins that journey too. | Grouped by `session_hint`, then by `account_id`. |
| `session_hint` | Sessions. Every event with the same hint is one session, with no idle timeout. Sessions feed Agent paths, Fix next, Agents, Intents, the heatmap and the session pages. | Grouped by `account_id` instead, if present. |
| `account_id` | Sessions when there is no hint: one account's events, split after 30 minutes without activity. | With neither field, the event is unattributed: counted in totals, in no session. |
| `properties.status_code` | How a session ended, from its last event: below 400 is OK, 400 and above is a failure. Failures drive Fix next, failure rates and the red cells. | Guessed from the event name if it contains `error`, `fail` or `unauthorized`, or ends in `_4xx`/`_5xx` (for example `api_call_401`). Guesses are marked "(guessed)". Otherwise "No status", never counted as OK. |
| `properties.error` | The error text in Fix next, timelines and session pages, after the status code: `401 Unauthorized: invalid API key`. | The standard text for the status code: `401 Unauthorized`. |
| `name` | The steps of a path. A session's intent is its first event whose name is not `docs` or `docs_…`. The heatmap groups intents by keywords in the name (signup, api_key, billing, metering, checkout, other). | Required. |
| `signature_agent` | How the event identified itself (`identity_tier` `declared` versus `anonymous`) and the agent's name: the host in it, such as `claude.ai`. | The agent is named from `user_agent`. |
| `user_agent` | The agent's name when there is no `signature_agent`. A known agent is named by the product it names, wherever it sits in the string: `ChatGPT-User`, `PerplexityBot`, `ClaudeBot`. Another string that starts with `Mozilla/` is named by its first product that is not a browser's (`FooBot` in `Mozilla/5.0 (compatible; FooBot/2.1)`), else by the browser: `Chrome`, `Safari`, `Firefox` or `Edge`. Anything else is named by its first word, such as `python-httpx`. | The agent shows as Unnamed. |
| `ip_hash` | Grouping an anonymous agent's requests into one visit (see "Where sessions come from" and "Hashed client IP" in section 8). Changes every UTC day, not stored on an event with an `account_id`, cleared at most 48 hours after it arrives, never shown or forwarded. | Each such request is a visit of its own. |
| `occurred_at` | The order of events in a session, and the UTC day coverage counts the event on. | Required. |
| `source` | The events-by-source chart. | Required. |

Agent names are what the request said about itself. Nothing checks them.

## 5. Sending events in production

```
POST https://alg.katrinalaszlo.com/v1/events
Authorization: Bearer <your key>
Content-Type: application/json
```

`?project_id=<uuid>` is optional (see "One value is enough" in section 1). The body is one event object, or an array of 1 to 100 events. The whole body must be 32 KB or less, so a full batch of 100 leaves about 327 bytes per event. If your events carry long user agents or large `properties`, send smaller batches.

Agent traffic checks each event on its own. A bad event is rejected and the rest of the batch is still written, and the response tells you which events were rejected and why (section 6).

### Event fields

Two keys inside `properties` are read by Track itself rather than kept as your data: **`properties.path`** (a page or file when you did not send `path`) and **`properties.surface`** (the arrival surface, below). Everything else in `properties` is yours and is stored and forwarded as sent.

**Declaring the surface.** When the shipped signals cannot tell which surface an arrival came from, send `properties.surface` on the request. It must be one of `chatgpt`, `claude`, `gemini`, `copilot`, `perplexity`, `mcp`, `browser_agent`, `crawler`, `other` or `none`; any other value is ignored and the surface is derived instead, so a customer cannot break a report with a typo. This is the only way to say "this arrived through our ChatGPT business listing" or "through our Claude connector": a listing and ordinary chat both send `ChatGPT-User`.

**Tool calls from an MCP server.** Your MCP server is a surface too. Send one event per tool call, named `tool_call`, with `properties` carrying `{ "tool": "search", "mcp_client": "claude", "status_code": 200, "duration_ms": 42 }`. Any event with a `mcp_client` string gets the surface `mcp` when nothing else declares one, and the call appears in the journey like any other step, so a connector install becomes a journey rather than an invisible install.

**Counting installs.** An install never reaches your server, so send it yourself from your release pipeline: one event per day per package, named `install`, `source` `log`, with `properties` like `{ "registry": "npm", "package": "your-package", "count": 128 }` and an `idempotency_key` of `install-<registry>-<package>-<date>` so a rerun does not double count. `bin/install-counts.js` in this repository does that against npm's public download API: `AGENT_TRAFFIC_KEY=… AGENT_TRAFFIC_PROJECT_ID=… node bin/install-counts.js your-package`. Add `install` as the first funnel step in Settings to see installs ahead of the first request.

These 23 fields are the only ones agent traffic accepts. Any other field, including fields agent traffic sets itself such as `event_id`, `received_at` or `identity_tier`, gets the event rejected with `unknown_field`. A required field sent as `null` counts as missing. Five of them (`signature`, `signature_input`, `method`, `url` and `covered_headers`) carry a Web Bot Auth signature for agent traffic to check; the `@katrinalaszlo/track` package from 0.3.0 sends them when the request was signed, and an older package or an older agent traffic host leaves them out without harm.

| Field | Required | Rule |
| --- | --- | --- |
| `idempotency_key` | yes | String, 1 to 200 characters. Unique per event within the project (see below). |
| `name` | yes | Lowercase letter first, then lowercase letters, digits or `_`, 64 characters at most: `^[a-z][a-z0-9_]{0,63}$`. For example `page_view` or `api_call`. |
| `occurred_at` | yes | ISO 8601 date and time with a timezone, `Z` or an offset such as `+02:00`. Seconds and fractions are optional. The date must exist on the calendar, so `2026-02-30` is rejected. |
| `source` | yes | One of `sdk`, `log`, `webhook`, `manual`. Stored events can also show `browser`, which only the browser snippet's endpoint sets (see "Browser snippet"); sending it here is rejected with `invalid_source`. |
| `account_id` | no | Your customer's account id, hashed. See below. |
| `properties` | no | A JSON object (not an array). Defaults to `{}`. |
| `session_hint` | no | String. One value per task. See below. |
| `journey_id` | no | The journey key: 8 to 128 characters of `A-Z`, `a-z`, `0-9`, `_` and `-`. Read it from the `Track-Journey` request header, then the `?track_j=` query parameter, then the `track_j` cookie. Needs `journey_source`. |
| `journey_source` | with `journey_id` | Where the key came from: `header`, `query` or `cookie`, or `issued` when your server minted the key on this request (and sets the `track_j` cookie in its response), so the first request joins its journey. Send it exactly when you send `journey_id`. Stored events can also show `handoff`, which only agent traffic sets (see "Handing off to a person"); sending it is rejected. |
| `handoff_token` | no | The `?track_h=` value of the request, when the person arrived through a handoff link: `h_` and 32 to 64 characters of `A-Z`, `a-z`, `0-9`, `_` and `-`. See "Handing off to a person" below. |
| `path` | no | The page or file the event was about, starting with `/` (`/llms.txt`, `/docs/install.md`, or a route pattern). At most 2048 characters. When it is left out, a `properties.path` that starts with `/` is used. Paths and Attribution read it. Stored without its query string and fragment, and with one-time tokens replaced; see "What ingest does to paths" below. |
| `run_hint` | no | String. |
| `user_agent` | no | String. The `User-Agent` header as your server received it. |
| `accept_language` | no | String. The `Accept-Language` header. |
| `signature_agent` | no | String. The `Signature-Agent` header, as received. This is the field that decides `declared` versus `anonymous`. |
| `tls_fingerprint` | no | String. |
| `ip_hash` | no | The client IP hashed on your server: HMAC-SHA256 as 64 lowercase hex characters, under a key that changes every UTC day (the `@katrinalaszlo/track` package from 0.7.3 sends it when `AGENT_TRAFFIC_ACCOUNT_SALT` is set). Anything else, a raw IP included, is rejected with `invalid_ip_hash` and nothing is stored. On an event that also has an `account_id` it is accepted and not stored. See "Hashed client IP" in section 8. |
| `signature` | no | String. The `Signature` header, as received. |
| `signature_input` | no | String. The `Signature-Input` header, as received. |
| `method` | no | String. The request method in uppercase, such as `GET`. Rejected with `invalid_method` otherwise. |
| `url` | no | String. The absolute `http` or `https` URL the agent requested, up to 2048 characters. A relative path is rejected with `invalid_url`. A signature needs this to be checked; without it the request is tiered `rejected`. |
| `outcome` | no | Object `{ "name", "value", "currency" }`: this event is a conversion. See "Outcomes" below. Needs `account_id`. |
| `covered_headers` | no | Object of lowercase header name to string value, up to 32 of them: only the headers the signature covers, besides the three above. `authorization`, `proxy-authorization`, `cookie` and `set-cookie` are rejected with `invalid_covered_headers`, as is any value with a newline. Nothing in this object is stored; it is read once by the check. |

Every string, and every key and string value inside `properties` at any depth, must be text Postgres can store. That means no U+0000 character and no unpaired UTF-16 surrogate. In practice this only bites when you copy raw bytes from a log into a field.

An accepted event cannot be changed or deleted through the API, so if you send a wrong event, the fix is to send correct ones from then on.

### What ingest does to paths

`path` and `properties.path` are cut at the first `?` or `#` before they are stored, forwarded or hashed: `/reset?token=abc` is stored as `/reset`. Query strings and fragments are where one-time codes, session ids and signed links travel, and no report reads them. The middleware already sends paths without them; this protects events sent by other code.

Then one narrow redaction: a path segment right after `invite`, `invites`, `invitation`, `reset`, `reset-password`, `password-reset`, `magic`, `magic-link`, `verify`, `verify-email`, `verification`, `token`, `tokens` or `auth` (any case, and the same names with `_`) is stored as `:token` when it looks like a token: 16 or more letters, digits, `_`, `-`, `.` or `=`, with at least one letter and one digit. That covers hex and base64url tokens, UUIDs and JWTs, so `/invite/3f2a9c1e7b4d4e0f9a8b7c6d5e4f3a2b/accept` is stored as `/invite/:token/accept`. Nothing else is changed: ids elsewhere in a path, such as `/users/123` or `/projects/<uuid>`, stay as sent, because the Paths and pages reports group by them, and short words such as `/auth/callback` are routes, not secrets. It cannot be turned off; if you need a path kept as sent that this changes, tell us. The event's content hash is computed on the stored path.

### Outcomes

An outcome is a conversion your server knows about and agent traffic cannot see in traffic: a signup, a key created, an activation, a payment. Send it as an event with an `outcome` object, and agent traffic writes an outcome row with the event, in the same transaction, so a retried batch with the same `idempotency_key` counts it once. The dashboard credits each outcome to the agent session that led to it and shows conversions and revenue by that session's class of agent (section 3). The rule: the most recent session of the same `account_id` whose class is known and that started within the 7 days before the outcome; if there is none, the session of the event the outcome arrived on. A payment from a billing webhook therefore lands on the agent session that signed the account up, as long as that session started within the week before it. An outcome with no such session, and whose own event has expired (section 8) or was in no session, is counted as unattributed. Revenue counts `paid` outcomes only; a `value` on another outcome name is stored and counted by name but is not revenue.

| Key | Rule |
| --- | --- |
| `name` | One of `signup`, `key_created`, `activation`, `paid`, `custom`. Anything else is rejected with `invalid_outcome`. |
| `value` | Whole minor units, 0 or more: `1999` for $19.99. `"19.99"` and `19.99` are rejected with `invalid_outcome_value`. Required for `paid`. |
| `currency` | ISO 4217 code such as `USD`. Required whenever `value` is set; otherwise `invalid_outcome_currency`. Revenue is reported per currency and never summed across them. |

An outcome event without `account_id` is rejected with `outcome_requires_account_id`: the account is what joins it to the agent's session. Use the same hashed id you send on that customer's requests (below). With the `@katrinalaszlo/track` package, `traffic.recordOutcome({ accountId, name, value, currency, idempotencyKey })` builds and sends the event, hashing `accountId` with the same salt as the middleware; pass your payment event id or the new account's id as `idempotencyKey`.

### Attribution

The Attribution page and the `attribution` MCP tool credit each paid outcome to the pages, files and agents that led to it. First the payment is linked to one session, by these rules in order:

1. **Same account id.** The account's most recent session in the 7 days before the payment whose class is not Unknown. The page also says how that session was followed: by a cookie, a request header, a link parameter, or grouped by account id.
2. **The payment's own request.** If rule 1 finds nothing, the session the payment's own event was in.
3. **Not linked.** Neither rule found a session. The payment is counted under Unattributed.

The touches are that session's events at or before the payment, oldest first; outcome events are not touches, and events after the payment are left out. Two events with the same `occurred_at` keep the order they were received in. Three models then share out each payment:

- **First touch**: the first touch gets the whole payment.
- **Last touch**: the last touch before the payment gets the whole payment.
- **Linear**: each of the touches gets an equal share. Shares are whole minor units; the leftover units go one each to the earliest touches, so the shares add up to the payment exactly.

Pages and files are the `path` on each touch (the middleware sends it from version 0.6.0). A payment whose session has no path recorded is under "Unattributed (no path recorded)". By agent, every touch is the session's agent and class, except a person's touch, which is credited to a "Person" row: one that arrived through a handoff link, or one sent from a plain browser (a `user_agent` named `Chrome`, `Safari`, `Firefox` or `Edge` above, with no `signature_agent`), such as the person who confirms a payment on the agent's journey. The table keeps the 30 entries with the most linear revenue and puts the rest under Other, so every column adds up to the revenue of the paid outcomes. By surface, every touch is credited to the channel its session arrived through (chatgpt, claude, gemini, copilot, perplexity, browser_agent, crawler, other), except a person's touch, which is credited to "Person". Revenue is per currency and never added across currencies: the page shows the currency with the most payments and lists the others, with a link to each. A paid outcome needs an `account_id`, a `value` and a `currency` to count. Like every report, a payment counts when its session started in the range; a payment linked to no session counts when it happened.

### Paths conversion

`GET /v1/traffic/paths` and the `traffic_paths` MCP tool say which paths and which pages lead to payment. A session is paid when at least one `paid` outcome is credited to it by the rule in Outcomes above; a session counts when it started in the range, and its payments with it. Revenue is the `value` of those payments in minor units, per currency, never added across currencies. A paid outcome with no `value` or `currency` still makes its session paid but adds no revenue. Under 20 sessions a row is marked `too_few`, the same threshold as the Funnel.

- Each entry in `paths` keeps its existing fields and adds `paid` (sessions of that path that paid), `conversion_rate` (`paid` as a percent of `sessions`, one decimal), `revenue` (`[{ currency, minor_units }]`, most first) and `too_few`.
- `conversion` is the same for every session in the range, with `min_sessions` (20).
- `sort=common` (the default) keeps the five paths with the most sessions. `sort=converting` keeps the five with the highest conversion among paths with 20 or more sessions, then the rest, too-few paths last; ties go to the path with more sessions. `sort` in the answer says which was used.
- `pages` is the Files and pages table. A row per `path` (the event's `path`, or a `properties.path` starting with `/` on older events) touched by a session in the range: `sessions` that touched it, `paid`, `conversion_rate`, `revenue`, `too_few`, and `lift`, the page's conversion over the range's (`1.8` is 1.8 times as likely to pay). `lift` is null when no session in the range paid or the range has under 20 sessions. A session counts once under every page it touched, so rows do not add up to `sessions`. The 30 pages with the most sessions are listed; `other` merges the rest (`paths` is how many, each session counted once), and `sessions_without_path` counts sessions with no path at all.

### Onboarding steps

Onboarding steps are your funnel's steps (Setting the funnel, section 3), read for where sessions stop and why. `GET /v1/traffic/onboarding` and the `onboarding_steps` MCP tool answer them, and the Friction page shows one card per step.

**Sending a step.** A step is reached by an event whose name is the step's event (with the middleware, the route's name, such as `keys_post`, plus the step's `path` when it has one). For a step your API never sees, such as opening a verification email, send an `onboarding_step` event with the step's name in `properties.step`:

```sh
curl -sS -X POST "https://alg.katrinalaszlo.com/v1/events?project_id=$PROJECT_ID" \
  -H "Authorization: Bearer $AGENT_TRAFFIC_KEY" \
  -H "Content-Type: application/json" \
  -d '[{ "idempotency_key": "verify-<account>-1", "name": "onboarding_step", "occurred_at": "2026-10-23T10:00:00Z",
         "source": "sdk", "account_id": "<hashed account id>", "properties": { "step": "verify_email" } }]'
```

Send one event per attempt: either the request the middleware records or an `onboarding_step` event, not both, or every attempt counts twice.

**Sending an error.** Errors need no extra event: any event with `properties.status_code` 400 or more is an error. For a failure your API does not answer with a status code, send an `error` event with the step in `properties.step` and the text in `properties.message`: `{ "name": "error", "properties": { "step": "verify_email", "message": "Verification email never opened" } }`. An `error` event never reaches a step.

**How each number is counted.** Sessions that started in the range, with all their events and the outcomes credited to them, the same sessions and order rules as the Funnel: a session reaches a step only after every step before it, the first step may share the session's first timestamp and each later step must come strictly later. A step is reached when the session sends its event, whatever the status code: a session that tried to create a key and got a 500 reached the step and had an error there.

| Field | Meaning |
| --- | --- |
| `reached` | Sessions that reached the step. The first row, `sessions`, is every session in the range. |
| `continued`, `dropped`, `drop_rate` | Of the sessions that reached the step, how many reached the next one, how many did not, and that as a percent. The last step has none. |
| `median_seconds_from_previous` | Median time from the step before (from the session's first event for the first step). |
| `median_seconds_from_start` | Median time from the session's first event. |
| `errors`, `sessions_with_errors`, `top_error` | Failed events at the step, the sessions that had one, and the most common error text (`401 Unauthorized: invalid API key`, or an `error` event's message). A failed event that reaches a step, or an `error` event that names one, is that step's error, even if the session had not reached it in order. Any other failed event is an error at the step the session was in: the last step it reached. Failures before the first step count on the `sessions` row; failures after the last step are not counted. |
| `retries`, `sessions_retrying` | A retry is the step reached again, later in the same session: every event that would reach the step, sent after the event that first reached it. A session that creates a key, gets a 500 and creates one again has reached the step once and retried it once. An `error` event is not a retry, and neither is a second outcome (a second payment). |
| `too_few` | Under 20 sessions reached the step. |

`worst_step` is the step that loses the most sessions to the next one, among steps 20 or more sessions reached: the Funnel's biggest drop. It can be the `sessions` row, when most sessions never reach the first step. `by_bucket` and `by_agent` are the Funnel's splits. `definition` is the saved funnel (`funnel_id`, `version`, each step's `event` and `path`), `null` for the default steps (signup, key created, paid). `seen_steps` lists the `properties.step` values `onboarding_step` events sent in the range, by sessions, so you can see what arrives before putting it in the funnel.

### Handing off to a person

An agent often cannot finish on its own: a person has to approve a payment or verify an email. When your server sends that person a link, add a handoff token to it, and the person's actions count toward the agent's journey: their checkout is credited to the agent that brought them.

1. While the agent is on journey `J` (the journey key of its requests), ask for a token:

```sh
curl -sS -X POST "https://alg.katrinalaszlo.com/v1/handoffs" \
  -H "Authorization: Bearer $AGENT_TRAFFIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "journey_id": "j_4f9c0e7a2b6d4e1f8a3c5b7d9e0f1a2b" }'
```

It answers `201`:

```json
{ "token": "h_Q2x2c1Zx0m4bX7yQe9Rk3vT8pLw6nJ5aHc1dGf2sUoA", "param": "track_h", "journey_id": "j_4f9c0e7a2b6d4e1f8a3c5b7d9e0f1a2b", "expires_at": "2026-10-24T18:00:00.000Z" }
```

2. Append it to the link you send: `https://example.com/checkout?plan=pro&track_h=h_Q2x2…`.
3. When the person's request arrives with `?track_h=`, send its value as `handoff_token` on that request's event. Agent traffic stores that event on `J` with `journey_source` `handoff`, and its `202` lists the event under `journeys`:

```json
{ "accepted": 1, "rejected": [], "journeys": [{ "idempotency_key": "req_9a1b", "journey_id": "j_4f9c0e7a2b6d4e1f8a3c5b7d9e0f1a2b", "journey_source": "handoff" }] }
```

4. Carry `J` on the person's later requests: set the `track_j` cookie to it in your response, so their sign-in and checkout land on the agent's journey too.

A token links once, to the first event that brings it back, and stops linking 24 hours after it was created. Agent traffic stores only its SHA-256, never the token, so treat the link like any one-time link: send it to the person only. An event with a token that is unknown, expired, already used or from another project is still stored, on its own journey key if it had one, and its `202` carries a warning under `event_warnings` instead of `journeys`: `{ "idempotency_key", "warning": "handoff_not_linked", "message" }`. The warning never says which of those it was. A value that is not a token shape is rejected with `invalid_handoff_token`. A project can create 60 tokens a minute; past that `POST /v1/handoffs` answers `429 rate_limited`.

The person usually signs in as the account the agent worked for, which is the point: their payment lands in the agent's session. If a different account signs in on that journey, it gets a session of its own as on any shared browser (section 4), and its payments are never credited to the agent's account.

With the `@katrinalaszlo/track` package from 0.7.0, `await traffic.handoffUrl(link, { req })` adds the token for the journey of the current request, and the middleware does steps 3 and 4: a request with `?track_h=` waits up to 2 seconds for agent traffic to link it, records a `handoff_opened` event, and, with `issueJourneyKeys` on, sets the person's `track_j` cookie to the agent's journey.

### Browser snippet

The middleware sees requests your server handles. A marketing site, a docs site or a signup page served from somewhere else is invisible to it, and so are browser agents (an agent driving Chrome) and people on those pages. The browser snippet covers them. Add one line to every page, inside `<head>`, with the project's public key from the Install page:

```html
<script async src="https://alg.katrinalaszlo.com/t/1.js" integrity="sha384-…" crossorigin="anonymous" data-key="pk_0123456789abcdef0123456789abcdef"></script>
```

Copy the tag from the Install page: it carries the real `integrity` hash. `/t/1.js` is version 1, which never changes, so the browser checks the file against the hash (Subresource Integrity) and refuses to run anything else. A fix to version 1 ships as `/t/2.js` with a new hash; `/t/1.js` stays as it is, cached for a year. `/t.js` is the current version, cached for an hour, for tags without `integrity`.

The public key names the project and is not a secret: it is in every page, so anyone can copy it and send browser events to the project. What those events can and cannot do is below. Never put `AGENT_TRAFFIC_KEY` in a page.

What it sends, to `POST /v1/browser/events` on Track and nowhere else:

- A `page_view` event on load, and again when a single-page app changes the path (`history.pushState`, `replaceState`, back and forward). `path` is the page's path only: no domain, no query string, no `#` part, and a token after `/invite/`, `/reset/`, `/verify/` and the other one-time words is replaced with `:token` in the browser, the same rule as "What ingest does to paths".
- Your own events: `track("signup_started", { plan: "pro" })`. The name follows the event name rules (lowercase letters, digits and `_`). `props` is up to 20 keys of letters, digits and `_`, each a string of up to 200 characters, a number, `true`, `false` or `null`, at most 2 KB as JSON per event (4 KB for all the events of one request). `path`, `referrer`, `webdriver`, `headless`, `no_plugins` and `no_languages` are set by Track and cannot be props. A call that breaks a rule is not sent and the console says why. To call `track` before the script has loaded, define the queue first: `<script>window.track = window.track || function () { (window.track.q = window.track.q || []).push(arguments); };</script>`.
- The referrer's origin only (`https://www.google.com`), and only when it is another site.
- Four automation signals, each a boolean sent only when true: `webdriver` (`navigator.webdriver` is true, which browsers set when WebDriver, Playwright or Puppeteer drives them), `headless` (the user agent or its client hints name HeadlessChrome), `no_plugins` (`navigator.plugins` is empty) and `no_languages` (`navigator.languages` is empty). Nothing else about the device is read: no screen size, fonts, canvas or other fingerprinting.
- The journey key (below).

Track adds the request's own `User-Agent` and `Accept-Language` headers and the time it received the event as `occurred_at` (a browser clock can be hours off). The client IP is used only to rate-limit: its request counter is named by an HMAC under a key that changes every UTC day, the counter is deleted a day after its last use, and the IP is never stored. Browser events carry no `ip_hash` and no `account_id`.

Each event is stored like any other with `source` `browser`, and its props, referrer and signals in `properties`. A session with a browser event whose `webdriver` or `headless` flag is true is classified Suspected automation (rule `browser_automation_flag`, weight 0.8). `no_plugins` and `no_languages` are recorded but not used: phones list no plugins either. Browser events count in coverage under `sdk_source_breakdown.browser` and appear on the Install page under step 5.

What browser events can and cannot affect. Anyone with the public key can send them, with any name, props and `User-Agent`, so Track trusts them less than your server's events:

- They never reach a funnel or onboarding step, unless you save that step with `from_browser: true` (`PUT /v1/traffic/funnel`, or `+browser` at the end of its line in Settings). That includes events named like a step (`signup`, `paid`) and `onboarding_step` events.
- They never count as errors: a `status_code` prop is ignored, and an `error` event counts only at a step saved with `from_browser: true` that it names in `properties.step`.
- They never decide whether a session succeeded or failed, so they never appear under "What agents ran into" on the Friction page or in `fix_next`.
- Their `User-Agent` never makes a session a Known agent or a Declared agent. A browser event whose `User-Agent` names one (`ChatGPT-User` and the rest of the shipped list) matches no rule at all: its session is Unknown, or Suspected automation when the `webdriver` or `headless` flag is set, and the agent is named "Unverified browser".
- They never carry an outcome, so they never add revenue, signups or payments, and never change attribution.
- They are not sent to PostHog or GA4 unless you turn that on for the project: Settings, Browser snippet, "Forward browser events too", or `PATCH /v1/projects/:id` with `{ "forward_browser_events": true }`. It is off for every project until then. Set the site's domain first.

The snippet sends nothing at all, and `track` does nothing, when the browser sends Do Not Track (`navigator.doNotTrack` or `window.doNotTrack` is `"1"` or `"yes"`, or the older `navigator.msDoNotTrack` is `"1"`) or Global Privacy Control (`navigator.globalPrivacyControl` is true). It sets no cookies. It keeps the journey key in `sessionStorage` for the tab, so the pages of one visit share it; it is gone when the tab closes. That storage may still need a line in your cookie policy or consent banner. Events go with `navigator.sendBeacon`, else `fetch` with `keepalive`, as `text/plain` so no CORS preflight is needed; the response is not read. Your page's Content-Security-Policy needs `https://alg.katrinalaszlo.com` in `script-src` and `connect-src`.

Which pages may send: when the project has a domain, only pages on that host and its subdomains, over https on the default port, judged by the browser's `Origin` header; anything else answers `403 origin_not_allowed` and is counted on the Install page. Without a domain, any page may send with the key, and the Install page says "Open to any site". Set or clear the domain in Settings, Browser snippet, or with `domain` on `POST /v1/projects` or `PATCH /v1/projects/:id` (`null` clears it); it is kept as `https://<domain>`. A name many sites share is refused as a domain, so one project cannot take in every site on a platform: `vercel.app`, `netlify.app`, `pages.dev`, `github.io`, `herokuapp.com`, `co.uk` and the other names in Track's short list of shared hosting and country names. Use your own name under them, such as `acme.vercel.app`, which also takes `preview.acme.vercel.app`. The Origin check stops other sites' pages from sending as yours; it cannot stop a script that sends its own `Origin` header, which is what the limits in section 9 are for.

If someone else is sending with your key, rotate it: Settings, Browser snippet, "Rotate public key", or `PATCH /v1/projects/:id` with `{ "rotate_public_key": true }`. The old key stops at once (`404` from then on), so put the new one in the script tag on every page. The domain, forwarding and rotation changes need the `write` scope and show in the Agent log.

Refused browser requests are counted per hour, not logged one by one: the Install page (step 5) and install-check show how many were refused in the last 24 hours and why (over the project's daily limit, over one address's daily limit, over the per-second limit, or from a site that is not the project's domain). The snippet does not resend a refused event.

The request body, for reference (the snippet builds it): `{ "v": 1, "journey": { "id": "j_…", "from": "server" | "snippet" }, "signals": { "webdriver": true }, "referrer": "https://www.google.com" | null, "events": [{ "id": "b_…", "name": "page_view", "path": "/pricing", "props": {} }] }`, at most 8 KB and 10 events. Anything malformed is refused whole with `400` naming the field. A good request answers `202 { accepted, rejected }` as in section 6.

### Journeys across browser and server

A browser event and a middleware event are one journey when they carry the same journey key. The middleware's key lives in the `track_j` cookie, which is `HttpOnly` (since 0.7.2), so the snippet cannot read it. The snippet takes the key, in this order, from:

1. `data-journey` on the script tag. On pages your Express app renders, put the request's key there: `data-journey="${traffic.journeyIdOf(req)}"` in whatever template syntax you use (needs `issueJourneyKeys: true`, or a key the request carried). No extra request. Stored with `journey_source` `cookie`, the same journey as the server's events.
2. `data-journey-url="/"`: a path on the same site that the middleware serves with `issueJourneyKeys: true`. Once per tab, the snippet sends it a `HEAD` request with the site's cookies and reads the `Track-Journey` response header; again after a handoff link (`?track_h=`), which can move the person onto an agent's journey. That `HEAD` is a request like any other, so the middleware records it once per tab. Also `journey_source` `cookie`.
3. Otherwise the key the snippet made earlier in this tab, or a new one (`j_` and 32 hex characters), stored with `journey_source` `issued`.

Limits: a key the snippet made itself never reaches your server, so a visit that starts on a static page and continues on your API without option 1 or 2 is two journeys. Option 2 works only on the same origin as the middleware (a static `www` and an API on `api.` are different origins). A key from the server is shared with page scripts through the tag or the header; it links events and grants nothing, but any script on the page can read it.

### Tool calls from an MCP server

An MCP server is a surface of its own. An install never reaches your server: the person adds the connector in the MCP client, and the calls your server handles are tool calls. Each call is the arrival, and one event per call turns an install that is otherwise invisible into a journey with steps in it.

Send the call as an event named `tool_call`, `source` `sdk`, with `properties` `{ "tool": "search_docs", "mcp_client": "claude", "status_code": 200, "duration_ms": 42 }`. `mcp_client` is the connector's name, `status_code` 400 and above marks a failed call, and `duration_ms` is optional. Send the two numbers as numbers; a numeric string such as `"500"` is read as the number it spells, which is what a hand-built JSON body or a YAML config often produces. Any event carrying a `properties.mcp_client` gives its journey the surface `mcp` when nothing declares one, so a connector's journey is not labelled with the chat client it runs in. A session made only of `tool_call` events classifies as a declared agent on the strength of `properties.mcp_client`, so its calls count as agent journeys. Pass the MCP session id as `sessionOf` anyway (the wrapper sends it as `session_hint`, so one connector session becomes one journey), and send an `account_id` when you have one so its payments are credited to it.

`examples/mcp-track.js` is a dependency-free wrapper for this: one file, no dependencies, built to be copied into your MCP server. `curl -sS https://alg.katrinalaszlo.com/mcp-track.js -o mcp-track.js` fetches it, and the repository keeps it at `examples/mcp-track.js`. Copy it beside the code that defines your tools and import it:

```js
import { trackToolCalls } from "./mcp-track.js"; // copied from examples/mcp-track.js

const track = trackToolCalls({
  key: process.env.AGENT_TRAFFIC_KEY,
  projectId: process.env.AGENT_TRAFFIC_PROJECT_ID,
  client: "claude", // sent as properties.mcp_client
  sessionOf: (context) => context?.sessionId, // one MCP session: the calls become one journey
});

// The wrapped handler keeps its signature; register it with your MCP framework as before.
const search_docs = track.wrap(async ({ query }) => searchDocs(query), "search_docs");
```

It throws at startup when the key or the project id is missing, rather than failing one call at a time. A send never blocks the tool and never throws into it: a failed send goes to `onError`, and `await track.flush()` before the process exits waits for the sends still in flight. A handler that throws is recorded with `status_code` 500 and rethrown unchanged.

Pass `accountOf(context)` to return the caller's hashed `account_id`. With one, the call joins that account's journey like any other step and appears in the MCP tools card on the Journeys page, which lists each tool with its calls, failed calls, journeys and median duration. Without one, the call is counted in totals but belongs to no journey.

### account_id

Agent traffic never needs to know who your customers are. By default your workspace is in hashed mode, and in hashed mode `account_id` must be the HMAC-SHA256 of your account id, keyed with a salt that only you hold, written as 64 lowercase hex characters. Base64, uppercase hex or a plain account id gets the event rejected with `invalid_account_id`.

Agent traffic never sees the salt and never hashes anything for you. It checks that the value looks like a 64-character lowercase hex string and stores it as sent. That has two consequences you should plan for. First, agent traffic cannot tell when a value was hashed with the wrong salt, so a salt mix-up between two of your services shows up later as accounts that never join, not as an error now. Second, the salt has to stay the same for as long as you want hashed ids to line up across events, so store it like any other long-lived secret and use the same one everywhere you send events.

Use the salt as the HMAC key and your account id as the message, as in the examples below. Every service that sends events must do it the same way round; the other order also produces 64 hex characters, so nothing will warn you, the ids just won't match. Make the salt long and random (32 random bytes is plenty). A short or guessable salt can be found by anyone who has one of your account ids and its hash.

Leave `account_id` out, or send `null`, when there is no account behind the request.

A raw mode exists, where `account_id` is your plain id of 1 to 128 characters. A workspace can only be in raw mode with a recorded acknowledgment, and there is no setting you can change yourself, so ask us if you need raw mode. Events already stored stay as they were sent, so switching a workspace from hashed to raw part way through leaves older events hashed and newer ones raw, and they will not join with each other.

### Where sessions come from

The requests agents send your API carry no task id, so on a server you usually cannot send a `session_hint`. Send `account_id` instead: the hashed id of the customer behind the request, from whatever your auth already resolved (user id, org id or API key id). Agent traffic splits one account's events into sessions after 30 minutes without activity. Requests with no customer behind them are counted; whether they are in a session depends on who sent them, as follows.

An agent that keeps no cookies and never signs in (a crawler, or ChatGPT-User fetching your docs) carries no journey key, or with `issueJourneyKeys` on gets a new issued key (`journey_source` `issued`) on every request that never comes back. Either way those requests are one visit when they share the hashed client IP (`ip_hash`) and the exact `user_agent`, split after 30 minutes without activity, after 2 hours from the visit's first request, and at midnight UTC, when the hash changes. The journey says it was linked by "Same IP and user agent". Requests whose own class is human are left out, because many people share one IP and one browser version, so a person without cookies keeps one session per request. These visits are their own journeys. They never join a journey that has a journey key, a hint or an account, so nothing in them is credited to an account. This is a heuristic: two agents of one product on one cloud IP can share a visit, many clients behind one NAT can too, and an IPv6 client whose address rotates within its /64 stays one visit but one that moves to another network does not.

### Linking signup and rejected requests with accountIdOf

The requests where agents most often fail come before they are authenticated: the signup call itself, and calls with a key that is wrong or revoked. Agents will not carry a custom header across those steps, so your server links them, through `accountIdOf`. It runs after the response, so it can read what your handlers set while answering:

```js
app.use(agentTraffic({
  accountIdOf: (req, res) =>
    req.user?.id                      // authenticated requests: what your auth resolved
    ?? res.locals.newAccountId        // signup: set by your signup handler (below)
    ?? claimedAccountOf(req),         // rejected key: the account the key claims to belong to
}));

// In your signup handler, once the account exists:
res.locals.newAccountId = account.id;

// If your keys name their account (sk_live_<account>_<secret>, for example), a rejected key still says which
// account the agent was trying to be. Adjust the pattern to your key format; return undefined if it has none.
function claimedAccountOf(req) {
  const key = req.headers.authorization?.replace(/^Bearer /, "");
  return key?.match(/^sk_live_([a-z0-9]+)_/)?.[1];
}
```

All three must return the same id for the same account (the value `req.user.id` holds), or the signup and the rejected calls start sessions of their own. The signup then becomes the first step of that account's session, and a 401 from a mistyped or revoked key lands in Fix next under the account it claimed. A claimed account is only what the key says: nothing checked it, so treat those sessions as the agent's attempt, not proof of who sent it. Requests that name no account at all, such as reading public docs before signup, stay unattributed.

Send `session_hint` only if you have a task id of your own, for example a run id your product hands to the agent.

### session_hint

A hint identifies one task: a signup flow, one attempt at an API integration, one end-to-end run. Give each task a new hint, and send it on every event of that task.

- Do not reuse a hint across tasks. Because a hint has no idle timeout, a hint that stays the same (a constant, a user id, one value for the life of an agent process) merges every task that used it into one long session.
- Do not send the hint on only some events of a task. Events with a hint and events without one are grouped separately, so the task is split into more than one session.

### idempotency_key and retries

Give every event a key that you can regenerate for the same event, such as your request id. Agent traffic remembers each key for as long as it keeps your raw events, counted from when it received the key (your raw retention plus one day, 15 days with the default retention of 14). If you send the same key again within that window, agent traffic does not write a second event. It answers with a `duplicate` entry in `rejected` that carries the `event_id` of the event it already stored, and the duplicate does not count in `accepted`. If the second send has different content under the same key, the first event is the one that stays.

That makes retries safe. When a request times out, or answers 500 or 503, send the same batch again with the same keys. Events are written one at a time, so a batch that failed part way may have written its first events, and the retry reports those as duplicates and writes the rest. After that window a key is forgotten and the same key would be written as a new event.

### occurred_at

`occurred_at` is when the request happened on your side, and coverage counts each event on the UTC day of its `occurred_at`, not the day agent traffic received it. Always include the timezone. The value is stored as the string you sent, so `2026-10-18T05:00:00Z` and `2026-10-18T00:00:00-05:00` are the same instant but are not treated as the same content. Events of one session are ordered by `occurred_at`; events with the same `occurred_at` keep the order agent traffic received them in, so within one batch, array order.

An `occurred_at` more than 15 minutes ahead of the time agent traffic receives the event is rejected with `future_occurred_at`, so a server clock that runs ahead loses events until the clock is fixed. Keep your servers on NTP.

### Example: curl with a hashed account_id

```sh
AGENT_TRAFFIC_KEY="ark_ws..."            # from signup
PROJECT_ID="..."                  # from signup
SALT="..."                        # your own secret, never sent to agent traffic
NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ)

ACCOUNT_HASH=$(printf '%s' "acct_123" | openssl dgst -sha256 -hmac "$SALT" | awk '{print $NF}')

curl -sS -X POST "https://alg.katrinalaszlo.com/v1/events?project_id=$PROJECT_ID" \
  -H "Authorization: Bearer $AGENT_TRAFFIC_KEY" \
  -H "Content-Type: application/json" \
  -d "[{
    \"idempotency_key\": \"req_7f3a9c\",
    \"name\": \"api_call\",
    \"occurred_at\": \"$NOW\",
    \"source\": \"log\",
    \"account_id\": \"$ACCOUNT_HASH\",
    \"user_agent\": \"Claude-User (claude-code/2.1)\",
    \"properties\": { \"status_code\": 200 }
  }]"
```

### Example: Express middleware

The `@katrinalaszlo/track` npm package is Express middleware in one file (Node 18 or later, no dependencies, TypeScript types included), open source at `https://github.com/katrinalaszlo/track-skill`. It works with `require` and with `import`. It sends one event for each request your API handles, after the response is sent, in batches of up to 25 once a second, retries server errors with the same idempotency keys, logs rejections, and never blocks or fails a request.

From version 0.6.0 every event carries `path`: the request path as your app received it, without the domain, the query string or the `#` part (`/v1/users?api_key=…` is sent as `/v1/users`). Ids inside the path itself are sent as they are. Paths and Attribution read it; update with `npm install @katrinalaszlo/track@latest`.

```sh
npm install @katrinalaszlo/track
```

Register it right after creating the app, before auth and routes, so requests your auth rejects are recorded too:

```js
const { agentTraffic } = require("@katrinalaszlo/track");

// Your customer's account id, as your auth resolved it. Read after the response, so values your auth middleware set
// are there. Return undefined when there is no customer behind the request.
app.use(agentTraffic({ accountIdOf: (req, res) => req.user?.id }));
```

`accountIdOf` gets `req` and `res`, so auth that sets `res.locals.user` works too. The optional `errorOf(req, res)` returns error text for a failed response (status 400 and above), sent as `properties.error` up to 200 characters, so two errors with the same status, such as a quota 402 and a payment 402, show as separate rows in Fix next: `errorOf: (req, res) => res.locals.error`, with your handlers setting `res.locals.error`. It reads `AGENT_TRAFFIC_KEY`, `AGENT_TRAFFIC_ACCOUNT_SALT` and the optional `AGENT_TRAFFIC_PROJECT_ID` from the environment, or from the `AGENT_TRAFFIC_` lines of a `.env` when the environment lacks them: the `.env` in the directory the server starts in, else in the app root (the folder whose `node_modules` holds the package; for a copy of the file inside your app, the nearest folder with a `package.json`). Since 0.7.2 no folder above those is read, so a `.env` at a monorepo root is found only when the server starts there or the package is installed in the root `node_modules`; otherwise set the variables in the environment. You can also pass `key`, `projectId` and `salt` as options.

Each event it sends:

| Field | Value |
| --- | --- |
| `outcome` | Only on events `recordOutcome` sends: `{ name, value, currency }`, with `name` as the event name and `properties` empty. |
| `name` | The route pattern, so `/v1/users/42` and `/v1/users/43` are one step. A leading version segment and `api` are dropped, and the method is added for anything but GET: `GET /v1/docs/quickstart` is `docs_quickstart`, `POST /api/v1/api-keys` is `api_keys_post`. A request no route matched is `unmatched`. |
| `properties` | `{ "status_code": res.statusCode, "method": req.method }`, read after the response finished, plus `error` when you set `errorOf` and the response failed. |
| `account_id` | HMAC-SHA256 of what `accountIdOf` returns, keyed with `AGENT_TRAFFIC_ACCOUNT_SALT`. Left out when it returns nothing. |
| `user_agent`, `signature_agent`, `accept_language` | The request headers, as received. |
| `idempotency_key`, `occurred_at`, `source` | A random UUID per event, the time the request arrived, and `sdk`. |

Event names exclude router mount prefixes because Express exposes their matched values, which can contain raw IDs. A route `/orders/:orderId` mounted at `/customers/:customerId` records `orders_orderid` for every customer. Identical route patterns under different mounts share an event name.

On serverless hosts (Vercel functions, AWS Lambda, Netlify, detected from their environment variables) the process can be frozen as soon as the response is sent, so there the middleware sends each event at once instead of batching, and on Vercel hands the send to `waitUntil` so the function stays up until it finishes. On Lambda and Netlify an event can still be lost if the process freezes mid-send.

For another framework, build the same event from the hook that runs after the response is sent, so you have the status code. Two are already written: `https://alg.katrinalaszlo.com/skill/fastify.cjs` (an adapter that hands a Fastify request to this middleware) and `https://alg.katrinalaszlo.com/skill/fastapi.py` (FastAPI and Starlette, standard library only), and the second is the reference to port from.

## 6. Reading the response

When agent traffic reads your batch, it answers `202` with how many events it wrote and one entry for each event it did not write:

```json
{
  "accepted": 2,
  "rejected": [
    { "idempotency_key": "req_7f3a9d", "reason": "invalid_occurred_at" },
    { "idempotency_key": "req_7f3a9c", "reason": "duplicate", "event_id": "0b6f5c1e-3d1a-4e8e-9f0a-6a1d2c3b4e5f" }
  ]
}
```

Each batch, and each event rejected for one of the reasons below other than `duplicate`, is also logged for the project with its reason, `idempotency_key`, `name` and `source` (never the event itself), and kept 3 days, the same window as the ingest log. A request that fails as a whole is logged with its status and code when its `project_id` belongs to the key's workspace. Read that log in three places: `POST /v1/install-check` prints a WARN line with the last 24 hours' rejected events and refused requests, counted by reason (a FAIL when no event was accepted at all); the Install page shows each recent request with its rejections; and `GET /v1/traffic/rejections` (`read` scope, `?project_id=` optional as for events) answers the same 24 hours as JSON: `rejected_events` and `reasons` (count per `reason` and `field`), `refused_requests` and `refusals` (count per `status` and `error`), and `recent`, the newest 20 rejected events with `received_at`, `reason`, `field`, `idempotency_key`, `name` and `source`.

```sh
curl -sS https://alg.katrinalaszlo.com/v1/traffic/rejections \
  -H "Authorization: Bearer $AGENT_TRAFFIC_KEY"
```

A `202` therefore does not mean every event was written, so always read `rejected`. Each entry names the first rule the event broke, and `idempotency_key` is `null` when the event had no string key to echo back.

Two more lists appear only when an event carried `handoff_token` (see "Handing off to a person"): `journeys`, for events stored on an agent's journey (also on a retry that answers `duplicate`, so a lost first answer can be recovered), and `event_warnings`, for tokens that did not link.

| Reason | What happened | What to fix |
| --- | --- | --- |
| `invalid_event` | The event is not a JSON object. An empty body also lands here, as one rejected event. | Send an object, or an array of objects. |
| `unknown_field` | The event has a field outside the 23 in section 5, or a field agent traffic sets itself. | Remove the field. Put your own data in `properties`. |
| `missing_field` | `idempotency_key`, `name`, `occurred_at` or `source` is missing or `null`. | Send all four. |
| `invalid_idempotency_key` | The key is not a string, is empty or longer than 200 characters, or holds text Postgres cannot store. | Use a string of 1 to 200 characters. |
| `invalid_name` | `name` does not match `^[a-z][a-z0-9_]{0,63}$`. | Use lowercase letters, digits and `_`, starting with a letter. |
| `invalid_occurred_at` | Not an ISO 8601 date and time with a timezone, or a date or time that does not exist. | Send something like `2026-10-18T05:00:00Z`. |
| `future_occurred_at` | `occurred_at` is more than 15 minutes ahead of when agent traffic received the event. | Fix the clock on the server that set the time. |
| `invalid_source` | `source` is not `sdk`, `log`, `webhook` or `manual`. `browser` is refused here too: only the browser snippet's endpoint sets it. | Use one of the four. |
| `invalid_account_id` | In hashed mode, not 64 lowercase hex characters. In raw mode, not 1 to 128 characters of storable text. | In hashed mode (the default), send the lowercase hex HMAC-SHA256 digest. In raw mode, send 1 to 128 characters. Or leave the field out. |
| `invalid_properties` | `properties` is not a JSON object, or a key or string inside it holds text Postgres cannot store. | Send an object. Remove null characters (U+0000) and lone surrogate characters from its keys and string values. |
| `invalid_journey_id` | `journey_id` is not 8 to 128 characters of letters, digits, `_` and `-`. | Send the key as you read it, or leave the field out. |
| `invalid_journey_source` | `journey_source` is not `header`, `query`, `cookie` or `issued`, or only one of `journey_id` and `journey_source` was sent. | Send both, or neither. |
| `invalid_path` | `path` is not a string starting with `/`, or is longer than 2048 characters. | Send the path part of the URL only, without the host or query string. |
| `invalid_ip_hash` | `ip_hash` is not 64 lowercase hex characters, for example a raw IP address. | Send the hash, never the IP, or leave the field out. The package computes it for you. |
| `invalid_method` | `method` is not 3 to 10 uppercase letters. | Send the request method as received, such as `GET`, or leave the field out. |
| `invalid_url` | `url` is not an absolute `http` or `https` URL of at most 2048 characters. | Send the full URL the agent requested, or leave the field out. |
| `invalid_covered_headers` | `covered_headers` is not an object of up to 32 lowercase header names to strings, or it holds `authorization`, `proxy-authorization`, `cookie` or `set-cookie`, or a value with a newline. | Send only the headers the signature covers, never credentials, or leave the field out. |
| `invalid_outcome` | `outcome` is not an object of `name`, `value` and `currency` only, or its `name` is not `signup`, `key_created`, `activation`, `paid` or `custom`. | Send one of the five names; see "Outcomes" in section 5. |
| `outcome_requires_account_id` | The event has an `outcome` but no `account_id`. | Send the hashed `account_id` of the customer the outcome belongs to. |
| `invalid_outcome_value` | `value` is not a whole number of minor units from 0 to 1,000,000,000,000, or a `paid` outcome has no `value`. | Send `1999` for 19.99 in the currency. |
| `invalid_outcome_currency` | `currency` is not three uppercase letters, or a `value` came without one. | Send an ISO 4217 code such as `USD` with every value. |
| `invalid_handoff_token` | `handoff_token` is not a string of `h_` and 32 to 64 characters of letters, digits, `_` and `-`. | Send the `?track_h=` value as received, or leave the field out. A well-formed token that does not link is not a rejection; see "Handing off to a person". |
| `invalid_session_hint`, `invalid_run_hint`, `invalid_user_agent`, `invalid_accept_language`, `invalid_signature_agent`, `invalid_tls_fingerprint`, `invalid_signature`, `invalid_signature_input` | That field is not a string, or holds text Postgres cannot store. | Send a string, or leave the field out. |
| `duplicate` | An event with this `idempotency_key` was already stored in this project within your raw retention window. Carries that event's `event_id`. | Nothing, if this was a retry. If it was a new event, give it a new key. |

When the whole request fails, nothing in the batch was looked at event by event, and the answer is an HTTP error with a body of `{ "error": "<code>", "message": "<text>" }`.

Refusals an agent can act on also carry two more fields:

- **`next_step`**: what to do, in one plain sentence.
- **`resolved_by`**: who can do it. `agent` means the caller can fix it with what it has (wait and retry, use another key it holds, pick another project id). `customer` means the person who owns the workspace has to (make a key with another scope, decide which project to delete).

They are on `insufficient_scope`, `project_key`, `not_found` for a project, `already_claimed`, every `429` and `too_many_projects`, and on `origin_not_allowed` from the browser snippet's endpoint. Every other field stays as it was.

| Status | Code | What it means |
| --- | --- | --- |
| 400 | `invalid_json` | The body is not valid JSON. |
| 400 | `invalid_field` | The array is empty or has more than 100 events ("Send 1 to 100 events."). |
| 400 | `request_aborted` | The connection closed before the whole body arrived. Retry. |
| 401 | `invalid_key` | The key looks right but is unknown or revoked. Check the key, or create a new one. |
| 401 | `key_rotated` | The key was rotated and its grace window has passed. The body names `rotated_at` and `expired_at`. Set `AGENT_TRAFFIC_KEY` to the key the rotation returned and restart your server. |
| 409 | `key_already_rotated` | Only on `POST /v1/keys/rotate`: this key has already been rotated; rotate with its successor instead. |
| 401 | `sign_in_required` | No `Authorization: Bearer` header was sent, or the value does not look like a Track key (`ark_`…). |
| 403 | `insufficient_scope` | The key is valid but lacks the scope this route needs (`write` for events, `read` for coverage). The body names `required_scope` and `granted_scopes`. Create a key with that scope. `resolved_by: customer`: a key cannot be widened, so the person who owns the workspace makes one under Settings. |
| 403 | `project_key` | A key bound to one project was used where a workspace key is needed (MCP, `POST /v1/claim-link`). Use the workspace key signup returned. `resolved_by: agent`. |
| 409 | `already_claimed` | `POST /v1/claim-link` on a workspace a person already claimed. Nothing to do: the person has it, and the key keeps working. `resolved_by: customer`. |
| 409 | `too_many_projects` | `POST /v1/projects` in a workspace that has 25. Reuse a project, or ask the person which one to delete. `resolved_by: customer`. |
| 429 | `rate_limited`, `signup_rate_limited`, `connect_rate_limited` | A request limit (section 9). Wait `Retry-After` seconds and send the same request again. `resolved_by: agent`. |
| 400 | `project_id_required` | No `project_id`, and the key is a workspace key in a workspace with more than one project. Pass `project_id`, or use a project key. |
| 404 | `not_found` | The `project_id` is not a UUID, does not exist, belongs to another workspace, or is not the project a project key was made for. All these cases get the same answer on purpose, so check that the key and the project come from the same workspace. `resolved_by: agent`. |
| 413 | `request_too_large` | The body is over 32 KB. Send smaller batches. |
| 503 | `hosting_not_configured` | The deployment has no database to write to. This is on our side. Retry later and tell us if it persists. |
| 503 | `database_unavailable` | The database could not take the request, possibly after some events in the batch were written. Wait `Retry-After` seconds and send the same batch again with the same keys. `resolved_by: agent`. |
| 500 | `internal_error` | Something failed on our side, possibly after some events in the batch were written. Retry the same batch with the same keys. |

The body and the batch size are checked before the project, so a request that is both malformed and aimed at the wrong project answers `400`, not `404`.

## 7. Reading coverage through the API

The dashboard reads the same report. To read it from your own code:

```sh
curl -sS "https://alg.katrinalaszlo.com/v1/traffic/coverage?project_id=$PROJECT_ID&days=14" \
  -H "Authorization: Bearer $AGENT_TRAFFIC_KEY"
```

`days` is how many complete UTC days to cover, ending yesterday. It defaults to 30 and must be a whole number from 1 to 90, otherwise the answer is `400 invalid_field`. The `project_id` rules and the `404` are the same as for sending events. The report is read fresh on every request, so it changes as soon as the state behind it does.

The answer always has `project_id` and `range_days`, and then either `pending` or `days`.

### pending

`pending` means no snapshot exists yet for this project, and it comes in two forms. Before agent traffic has received any event for the project:

```json
{
  "project_id": "…",
  "range_days": 30,
  "pending": {
    "state": "pending",
    "message": "Waiting for the first events. Snapshots start the day after the first event, after 02:00 UTC.",
    "first_received_date": null,
    "available_after": null
  }
}
```

After events have arrived but before the first snapshot run that can count them, the message and `available_after` tell you when to look again:

```json
{
  "pending": {
    "state": "pending",
    "message": "First snapshot available after 02:00 UTC on 2026-10-21",
    "first_received_date": "2026-10-20",
    "available_after": "2026-10-21T02:00:00Z"
  }
}
```

The snapshot job runs once a day at 02:00 UTC. The first snapshot comes from the first run that falls after both of two moments, when agent traffic received your first event and the end of the UTC day of your earliest `occurred_at`. If your first event arrives at 15:00 UTC on October 20 and happened that day, the first snapshot is available after 02:00 UTC on October 21. If you backfill old events on October 20, the answer is the same, because a run has to happen after the events arrived.

### days

Once snapshots exist, `days` lists one entry per UTC date, newest first, from the earliest snapshot (or the start of the range, whichever is later) through yesterday. Each entry is either a snapshot or missing.

```json
{
  "project_id": "…",
  "range_days": 30,
  "days": [
    {
      "date": "2026-10-22",
      "state": "snapshot",
      "total_requests": 412,
      "by_identity_tier": { "verified": 0, "declared": 37, "anonymous": 375, "rejected": 0, "not_assessed": 0 },
      "by_bucket": { "unknown": 412 },
      "unclassified_share": 1,
      "js_instrumented_share": null,
      "sdk_source_breakdown": { "sdk": 412, "log": 0, "webhook": 0, "manual": 0, "browser": 0 },
      "journeys": {
        "sessions": 61,
        "by_bucket": {
          "known_agent": { "sessions": 40, "paid": 3, "revenue": [{ "currency": "USD", "minor_units": 14700 }] },
          "declared_agent_assisted": { "sessions": 2, "paid": 0, "revenue": [] },
          "suspected_automation": { "sessions": 6, "paid": 0, "revenue": [] },
          "human": { "sessions": 9, "paid": 1, "revenue": [{ "currency": "USD", "minor_units": 2900 }] },
          "unknown": { "sessions": 4, "paid": 0, "revenue": [] }
        }
      },
      "method_version": "coverage-4",
      "notes": [
        "0 verified: Web Bot Auth signatures are not checked yet",
        "0 classified: no session that day matched an agent rule or carried a signature"
      ]
    },
    {
      "date": "2026-10-21",
      "state": "missing",
      "notes": ["Snapshot missing: the coverage job may not have run for 2026-10-21"]
    }
  ]
}
```

The numbers above are an example. In a snapshot, `total_requests` is every event agent traffic stored with an `occurred_at` on that UTC date, the five tiers and the five sources (`sdk`, `log`, `webhook`, `manual` and `browser`, the browser snippet's; snapshots from before `coverage-3` list the first four) each add up to that total. `js_instrumented_share` is always `null`: it is kept for compatibility, and browser snippet events are counted under `sdk_source_breakdown.browser` instead. A day with no events is still a snapshot, with `total_requests` of 0, `unclassified_share` of `null`, and the note "No events".

`journeys` counts the journeys (sessions) that started on that UTC date, by the same rules as the Overview and Paths: a session counts on the day of its first event, when it holds at least one event that is not an outcome, and in its class (`by_bucket`, all five classes, their `sessions` adding up to `sessions`). `paid` is how many of them were credited a paid outcome (see Attribution), and `revenue` those payments' values per currency in minor units, never added across currencies; a payment without a value still makes its journey paid. A payment can arrive days after its journey started, so a day's `paid` can still grow while the day is inside the nightly recompute. The Overview's agent journeys are `known_agent` plus `declared_agent_assisted`, and agent conversion is their `paid` over their `sessions`. `journeys` is `null` on snapshots written before `coverage-4`: they did not record journeys, and they are never filled in afterwards. `today` carries `journeys` too, for journeys that started today so far.

A `missing` day means the job did not write that day, and it carries no counts. Each night the job recomputes the last 7 complete UTC days, so a gap of a day or two usually fills in on the next run. A day that stays missing for longer than that will not fill in, and you should tell us.

That nightly recompute also means a snapshot can change for up to 13 days after its date (raw retention minus one day), as late events arrive. An event whose `occurred_at` is more than 13 days before agent traffic receives it is stored but never added to a snapshot, because its day has already left the window. Days before your project was created are never counted.

### The method-change marker

Every snapshot records the `method_version` that produced it, `coverage-4` today (`coverage-4` added `journeys`; `coverage-3` added the `browser` source). When agent traffic changes what a count means, it writes snapshots under a new version beside the old ones and never rewrites the old ones. The report shows the highest version for each date, and the first date counted under a new version carries the note `Counts from this date use method coverage-2` (with the new version's name), so you know not to compare across that line without thinking.

### Notes

Every entry has a `notes` array of short text meant to be shown next to that day. These are all the notes the report can return:

| Note | When |
| --- | --- |
| `Snapshot missing: the coverage job may not have run for <date>` | The day has no snapshot. |
| `Counts from this date use method <version>` | The method version changed from the previous snapshot date. |
| `No events` | The snapshot has `total_requests` of 0. |
| `0 verified: Web Bot Auth signatures are not checked yet` | `verified` is 0 and signature checking is off for the project (every project created before 2026-10-22, until we switch it on with you). |
| `0 verified: no request carried a Web Bot Auth signature that checked out` | `verified` is 0 and signature checking is on: no event that day carried a signature, or every one that did was `rejected`. |
| `<n> events were not assessed for identity tier` | `not_assessed` is above 0. |
| `0 classified: no session that day matched an agent rule or carried a signature` | `unclassified_share` is 1: every event that day is in the `unknown` bucket. |

### How events identified themselves

The `identity_tier` field says how much the request told you about who sent it. Every snapshot carries all five tiers, including the ones at zero, so the shape of the answer never changes.

| Tier | What it means today |
| --- | --- |
| `verified` | The request carried a Web Bot Auth signature that agent traffic checked against the key the agent published: the signature covered the request, the key came from the issuer named in `Signature-Agent`, and the signature was fresh. It says who signed. It does not say the agent behaved well, and it is 0 for a project whose signature checking is off. |
| `declared` | The event's `signature_agent` field held a `Signature-Agent` value whose every entry is an `http` or `https` URL. The agent named itself, but nobody checked the claim. |
| `anonymous` | The event had no `signature_agent`, or had one whose entries were not all web URLs. |
| `rejected` | A signature was present and failed the check: expired, wrong key, a key set that could not be fetched, a covered part of the request that was not sent, or an issuer agent traffic refuses to fetch from (an IP address, a local name, or a name that resolves to a private address). The reason is stored with the event. |
| `not_assessed` | Agent traffic could not assign a tier to the event because tiering failed on our side. The event is still stored and counted. |

A Web Bot Auth signature covers the HTTP request as your server received it, so the check needs that request: its method, its full URL, the `Signature` and `Signature-Input` headers, and whatever other headers the signature covers. The `@katrinalaszlo/track` package sends those with the event when the request was signed (section 5, the last five fields), and agent traffic checks them on receipt, fetching the agent's published key set once per issuer and caching it. Signature checking is a per-project switch. Projects created from 2026-10-22 have it on; older projects have it off until we switch it on with you, and their snapshots say `not checked yet` rather than counting unsigned requests as a finding. When it is on and a day's `verified` is 0, the note says so in those words: no request that day carried a signature that checked out.

Classification puts each session in one of five buckets from what its events say about the sender, and `by_bucket` counts events by their session's bucket: `known_agent` (an event with a checked signature, or a user agent on the shipped list of agent vendors), `declared_agent_assisted` (the agent named itself in `Signature-Agent` or in `properties.mcp_client`, nobody checked, and no vendor user agent matched; a vendor user agent with an unchecked signature is still a `known_agent`), `suspected_automation` (an HTTP client library or a headless browser), `human` (a browser), and `unknown` (nothing matched, or the event is in no session). `unclassified_share` is the `unknown` share of the day. The rules are case-insensitive patterns over the `User-Agent` header, versioned, and a session's row names the ones that matched. Buckets say how the sender looked, not what it did: a browser user agent is a string any program can send. An MCP client name is read from server-side events only, never from a browser snippet, whose properties anyone with the public key can set; it classifies the session as a declared agent while the identity tier stays whatever the signature evidence says, so a declared class is not the same as a checked identity.

### Agent types

A session classed as an agent (`known_agent`, `declared_agent_assisted` or `suspected_automation`) also gets an `agent_type`, so a crawler that never signs up does not lower the conversion of agents that act for a person:

| `agent_type` | Meaning | User-Agent tokens and Signature-Agent hosts |
|---|---|---|
| `crawler` | fetches pages on its own schedule to train a model or build a search index | GPTBot, OAI-SearchBot ([OpenAI](https://developers.openai.com/api/docs/bots)); ClaudeBot, Claude-SearchBot ([Anthropic](https://support.claude.com/en/articles/8896518-does-anthropic-crawl-data-from-the-web-and-how-can-site-owners-block-the-crawler)); PerplexityBot ([Perplexity](https://docs.perplexity.ai/guides/bots)); Googlebot, Google-Extended ([Google](https://developers.google.com/search/docs/crawling-indexing/google-common-crawlers)); bingbot ([Bing](https://www.bing.com/webmasters/help/which-crawlers-does-bing-use-8c184ec0)); meta-externalagent ([Meta](https://developers.facebook.com/docs/sharing/webmasters/web-crawlers)); Amazonbot ([Amazon](https://developer.amazon.com/amazonbot)); Applebot ([Apple](https://support.apple.com/en-us/119829)); DuckDuckBot ([DuckDuckGo](https://duckduckgo.com/duckduckgo-help-pages/results/duckduckbot)); CCBot ([Common Crawl](https://commoncrawl.org/ccbot)); MistralAI-Index, MistralAI-Training ([Mistral](https://docs.mistral.ai/robots)); Bytespider (ByteDance publishes no page; every public bot registry lists it as a crawler) |
| `assistant` | fetches a page because a person asked it something, then answers them | ChatGPT-User ([OpenAI](https://developers.openai.com/api/docs/bots)); Claude-User ([Anthropic](https://support.claude.com/en/articles/8896518-does-anthropic-crawl-data-from-the-web-and-how-can-site-owners-block-the-crawler)); Perplexity-User ([Perplexity](https://docs.perplexity.ai/guides/bots)); Google-GeminiNotebook ([Google](https://developers.google.com/search/docs/crawling-indexing/google-user-triggered-fetchers)); meta-externalfetcher ([Meta](https://developers.facebook.com/docs/sharing/webmasters/web-crawlers)); DuckAssistBot ([DuckDuckGo](https://duckduckgo.com/duckduckgo-help-pages/results/duckassistbot)); MistralAI-User ([Mistral](https://docs.mistral.ai/robots)) |
| `browser_agent` | drives a browser for a person | Signature-Agent `https://chatgpt.com`, ChatGPT's cloud browser ([OpenAI](https://help.openai.com/en/articles/11845367-chatgpt-works-cloud-browser-allowlisting)); Signature-Agent `https://agent.bot.goog`, Google-Agent ([Google](https://developers.google.com/search/docs/crawling-indexing/google-user-triggered-fetchers)); HeadlessChrome ([Chrome](https://developer.chrome.com/docs/chromium/headless)), Puppeteer, Playwright, PhantomJS, Selenium, WebDriver |
| `other` | an agent Track cannot place | a vendor name with no documented product token (`anthropic`, `openai`, `gemini`, `copilot`, `mistralai`), tokens the vendor no longer documents (Claude-Web, FacebookBot) or never did (cohere-ai), HTTP client libraries, any other Signature-Agent host, and your own rules |

A `human` or `unknown` session has `agent_type` `null`. The User-Agent decides first, so ChatGPT-User stays an `assistant` even if it also signs as `chatgpt.com`; a Signature-Agent host decides only when no User-Agent token matched. The type is worked out when a report is read, not stored, so a change to the list applies to past sessions too.

The Journeys page also names the **operator** behind the agent (OpenAI, Anthropic, Google, Perplexity, Meta, Microsoft, Amazon, Apple, DuckDuckGo, Common Crawl, Mistral, ByteDance, Cohere, or Other). Operator is computed at read time from the shipped User-Agent list and the Signature-Agent host, the same way as agent type, so it applies to past sessions and needs no backfill. It is an additive dimension on Journeys; `agent_type` keeps its four values.

The Journeys page and the `journeys` tool also carry a **surface**: the channel the arrival came through. It is `chatgpt` for ChatGPT-User or a `chatgpt.com` signature, `claude` for Claude-User or `claude.ai`, `gemini`, `copilot` and `perplexity` for the other assistants, `browser_agent` for browser automation with no assistant signature, `crawler` for an indexing or training fetch, `other` for an agent Track cannot place, and `none` for a session that is not an agent's. Like operator and agent type it is computed when a report is read, so it applies to past sessions with no backfill. It answers "did the ChatGPT listing convert?" only coarsely: the shipped signals cannot separate a business listing, an app or a connector from ordinary chat, which needs a surface the customer declares.

Every journey row shows its `identity_tier`: **Verified** (a signature was checked), **Declared** (the agent named itself, unchecked), **Anonymous** (no identity claim), **Rejected** (a signature failed; the reason is stored), or **Not assessed** (tiering could not run). The journey detail shows the same evidence for each event. A project whose signature checking is off shows "Not checked yet", never a verified badge. It appears on every journey (the `journeys` tool and the journey pages), on each agent in `GET /v1/traffic/paths` (`agents`, `ungrouped_agents`, `recent_sessions`) with `sessions_by_agent_type`, in the funnel as `funnel.by_agent_type` (both group only known and declared agents by type, and put suspected automation in `automation` and human and unknown sessions in `not_agent`, the same split the Overview counts) and on each `funnel.by_agent` group, on each agent row of the `attribution` tool with `dimension` `agent`, on each outcome of the `conversions` tool, and on events forwarded to PostHog and GA4. The `type` filter still takes a class, not an agent type.

## 8. Data retention

Agent traffic keeps your raw events for your workspace's raw retention plus one extra day, and then the daily job deletes them. Retention is 14 days by default, which means events from the last 15 full UTC days plus today are kept. The extra day is there so that every day the snapshot job recounts still has all of its events.

The cutoff follows `occurred_at`, not when the event arrived. If you backfill events whose `occurred_at` is already older than the cutoff, they are deleted by the next daily run, within a day of arrival. They would not have appeared in a snapshot anyway, because they are outside the 13-day recount window (raw retention minus one day).

Events that arrive more than 13 days after their `occurred_at` are stored (until the retention cutoff deletes them) but not added to a coverage snapshot. The recipe: 14 days of raw retention plus one slack day keeps events for 15 full days, and the snapshot job recomputes the complete days inside that kept window except the last one, so 13 with the default of 14. A longer retention widens the recompute to at most 14 days. If you plan to backfill historical data, contact us before sending it. We can tell you which events will appear in your report and whether a one-off recount is possible for the rest.

Handoff tokens (their hashes) are kept as long as raw events, counted from when they were created; a token stops linking after 24 hours either way.

Sessions are deleted on the same clock, counted from their last event, because a session cannot be read without the events in it. The payments credited to a session survive it: the outcome and attribution rows stay and only their session link is cleared, so revenue never disappears with its journey.

Two tables have their own window rather than following raw retention. The per-request ingest log, the batches the Install page names from an event's `batch_id` and the rejected events, is kept 3 days. Idempotency keys are kept as long as raw events plus the slack day, so a retry that would have matched a still-readable event is still deduplicated, and a key never outlives the event it protects.

Running your own database? `bin/db-maintenance.js` reports the biggest relations and what the nightly job would delete (a dry run by default), applies it with `--apply`, and returns the disk with `--shrink`.

### Hashed client IP

What is sent: with `AGENT_TRAFFIC_ACCOUNT_SALT` set, the `@katrinalaszlo/track` package (0.7.3 and later) sends `ip_hash` on each request's event. It is HMAC-SHA256 of the client IP (an IPv6 address as its /64 prefix), keyed with a key your server derives from your salt and the UTC date. The IP and the salt never leave your server. Without the salt, no `ip_hash` is sent.

To send the same hash from another stack, so its requests group with the middleware's, compute it exactly as the middleware does (`hashIp` in its source):

1. The day key: HMAC-SHA256 with your salt as the key, over the text `agent-traffic ip_hash v1 ` followed by the event's UTC date as `YYYY-MM-DD` (for example `agent-traffic ip_hash v1 2026-10-24`), as raw bytes.
2. The address text: an IPv4 address as is (`203.0.113.7`); an IPv4-mapped IPv6 address (`::ffff:203.0.113.7`) as its IPv4; any other IPv6 address as its first four 16-bit groups in lowercase hex without leading zeros, joined by `:` and followed by `::/64`. So `2001:0DB8:0000:0042:1:2:3:4` is `2001:db8:0:42::/64`, and `::1` is `0:0:0:0::/64`. A zone (`%eth0`) is dropped first.
3. `ip_hash`: HMAC-SHA256 with the day key as the key, over the address text, as 64 lowercase hex characters.

Purpose: only grouping an anonymous agent's requests into one visit (section 5, "Where sessions come from"), for analytics. Only requests with no `account_id` whose own class is not human are grouped. `ip_hash` is not shown in the dashboard, not returned by any API or MCP tool, not forwarded to PostHog or GA4, and not written to logs.

Rotation and retention: the key changes every UTC day, so the same IP hashes differently from one day to the next. An event that carries an `account_id` is stored without `ip_hash`, so Track never holds a signed-in request's account and IP hash together. On an event without one, the first session refresh that classifies the event human sets `ip_hash` to `NULL` (a refresh runs when you open the dashboard and in the daily job), so a person's `ip_hash` and user agent are held until the next refresh and never more than 48 hours. Every other event's `ip_hash` is set to `NULL` before it reaches 48 hours after Track received it: the daily job and every session refresh clear anything older than 24 hours, so with a 24-hour job the oldest hash is 24 hours plus the gap to the next run, never past the 48-hour promise. The event itself stays for the raw retention above, and a visit already grouped stays grouped. Track has no stable cross-day identifier for your visitors.

How retention is enforced and monitored: the clearing runs as one database statement at the end of every session refresh, for that project, and in the 02:00 UTC daily job for every project; the database refuses any other change to a stored event. Every run of the daily job is recorded. A check runs every day at 03:30 UTC and alerts the Track maintainer when any `ip_hash` is older than 50 hours (48 plus two hours of slack) or the daily job has not succeeded in 26 hours.

It is a heuristic: NAT puts many clients behind one IP, cloud agents share egress IPs, and IPv6 addresses rotate, so a visit can merge two clients or split one.

Idempotency keys follow the same clock as your raw events, counted from when agent traffic received the key: your raw retention plus the slack day. A retry that could still match a readable event is still recognized as a duplicate, and a key is not kept for weeks after the events it protects have gone.

Daily snapshots hold counts, not events, and the daily job does not delete them. Your coverage history stays readable after the raw events behind it are gone.

Two things to plan for:

- **Volume.** If you expect to send more than a few thousand events a day, tell us before you start.
- **Retention.** Plan on 14 days. There is no setting you can change yourself yet; ask us if you need longer.

## 9. Limits and what is not built yet

### Request limits

Every limit answers `429` with a `Retry-After` header in seconds and the same number as `retry_after_seconds` in the body. Each limit allows a burst up to the first number, then a steady rate.

| Route | Counted per | Limit |
| --- | --- | --- |
| `POST /v1/events` | project | 600 requests at once, then 20 a second (up to 2,000 events a second in batches of 100). A refused request shows on the Install page and in install-check as `429 rate_limited`. Retry it with the same idempotency keys and nothing is lost or doubled. |
| `POST /v1/install-check` | key | 20 at once, then 1 a minute. A rerun rebuilds sessions only when events arrived since the last build. |
| `POST /api/refresh` | key | 20 at once, then 1 a minute. |
| `POST /v1/handoffs` | project | 60 a minute. |
| `POST /v1/browser/events` | client IP | 120 requests at once, then 2 a second. The counter is named by an HMAC of the address that changes daily; the address is not stored. |
| `POST /v1/browser/events` | project | 600 requests at once, then 20 a second. |
| `POST /v1/browser/events` | client address, per day | 5,000 events a day, counted in events, refilled evenly over 24 hours. An IPv6 address counts by its /48, so moving between the /64s of one network does not reset it. The `429` body has `limit: "ip_daily_events"`. |
| `POST /v1/browser/events` | project, per day | 50,000 events a day, counted in events, refilled evenly over 24 hours, so one stranger cannot fill a project with junk. The `429` body has `limit: "project_daily_events"`. |
| `POST /v1/signup` | address | 20 workspaces an hour per IPv4 address or IPv6 /64, and 300 an hour across all addresses. |
| `POST /v1/connect/start` | address | 30 logins an hour per IPv4 address or IPv6 /64, and 600 an hour across all addresses. |
| `/claim/<token>` (opening or posting a claim link) | client address | 20 at once, then 20 every 15 minutes. |

Every browser refusal is counted on the Install page and in install-check. The snippet does not retry. A browser event's props are at most 2 KB as JSON (4 KB per request), and a request at most 8 KB and 10 events.

Signup creates one project. Make more with the "New project" button in the dashboard or `POST /v1/projects`, up to 25 per workspace. Workspace settings such as raw retention and the account id mode cannot be changed by you yet; ask us.

Sessions are built from every stored event still inside raw retention when the refresh runs (14 days by default, plus one slack day). Events sent after their raw retention has passed are deleted on the next expiry run and never placed in sessions.

Signature checking is off for projects created before 2026-10-22, so their `verified` and `rejected` tiers stay 0 and `declared` is the highest tier they show. Ask us to switch it on; there is no setting you can change yourself yet.

Classification uses the shipped rule set only; there is no way to add your own rules yet. Ask us if an agent that matters to you lands in `unknown`.

There is no API to read raw events back. The dashboard's session pages show each session's events and their properties. Events are written once and cannot be changed or deleted through the API.

The Express middleware in section 5 is the `@katrinalaszlo/track` npm package. For other frameworks you send events from your own code with the calls above.

## Why not a readiness score

Readiness scanners read your docs and grade what is documented. That tells you what an agent could find, not whether one got through.

**A real agent attempts the task; an independent checker verifies the key, and on the two payment tasks, the money.** The x402 and Stripe Projects runs settle a real payment, and the evaluator reads the settlement rather than the agent's word for it.
