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
pathskeeps its existing fields and addspaid(sessions of that path that paid),conversion_rate(paidas a percent ofsessions, one decimal),revenue([{ currency, minor_units }], most first) andtoo_few. conversionis the same for every session in the range, withmin_sessions(20).sort=common(the default) keeps the five paths with the most sessions.sort=convertingkeeps 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.sortin the answer says which was used.pagesis the Files and pages table. A row perpath(the event'spath, or aproperties.pathstarting with/on older events) touched by a session in the range:sessionsthat touched it,paid,conversion_rate,revenue,too_few, andlift, the page's conversion over the range's (1.8is 1.8 times as likely to pay).liftis 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 tosessions. The 30 pages with the most sessions are listed;othermerges the rest (pathsis how many, each session counted once), andsessions_without_pathcounts 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:
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:
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:
{ "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:
{ "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:
<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_viewevent on load, and again when a single-page app changes the path (history.pushState,replaceState, back and forward).pathis 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:tokenin 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_).propsis up to 20 keys of letters, digits and_, each a string of up to 200 characters, a number,true,falseornull, at most 2 KB as JSON per event (4 KB for all the events of one request).path,referrer,webdriver,headless,no_pluginsandno_languagesare set by Track and cannot be props. A call that breaks a rule is not sent and the console says why. To calltrackbefore 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.webdriveris true, which browsers set when WebDriver, Playwright or Puppeteer drives them),headless(the user agent or its client hints name HeadlessChrome),no_plugins(navigator.pluginsis empty) andno_languages(navigator.languagesis 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+browserat the end of its line in Settings). That includes events named like a step (signup,paid) andonboarding_stepevents. - They never count as errors: a
status_codeprop is ignored, and anerrorevent counts only at a step saved withfrom_browser: truethat it names inproperties.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-Agentnever makes a session a Known agent or a Declared agent. A browser event whoseUser-Agentnames one (ChatGPT-Userand the rest of the shipped list) matches no rule at all: its session is Unknown, or Suspected automation when thewebdriverorheadlessflag 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/:idwith{ "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:
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:
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
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.
npm install @katrinalaszlo/trackRegister it right after creating the app, before auth and routes, so requests your auth rejects are recorded too:
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.