Key terms · Dokumentace Zeno

These docs, the dashboard and the API use a handful of words in one sense each. Read this page first: the quickstart and every guide after it use these words without explaining them again.

Term	In the API	Means
Organization		Holds your projects and their bill, in one currency. Teammates are per project; everyone on one of its projects is in the organization.
Project		One site, or a few that belong together: its keys, allowed origins, settings, events and visitors. Nothing is shared between projects, visitor ids included.
Visitor	`visitorId`	One browser on one device, within one project. Not a person, and not the hardware alone.
Event	`requestId`	One identification: one `get()` call that reached the API. `requestId` is the event's id.
Identification		What you're billed for: each new event counts as one.
External ID	`externalId`	Your own id for the user, account, customer or order behind the browser.
Returning	`returning`	Whether the project had seen this visitor before this event.
Action	`action`	What the visitor was doing, in your own words, like `signup` or `checkout`.
Metadata	`metadata`	Your own key-values on an event, like an order id or a plan, returned with it and never used for detection.
Confidence	`confidence`	How sure the visitor id is, 0.1 to 1. Below 0.8, treat the match as uncertain.
Detected	`detected`	The smart signals that fired, like `vpn` or `automation`.
Risk score	`riskScore`	The flags' points added up, per family. Start by challenging from 9 and blocking from 15; see Risk score.
Bot verdict	`bot`	`bad` for a script driving the browser (`automation`, `headless`), a replayed request or a fake crawler; `good` for a known crawler; else `not_detected`. See Bot verdict.
Velocity	`velocity`	How busy the visitor, IP and external ID were lately; below.
Related	`/fingerprints`	Which visitors and IPs each external ID was seen with, and so which external IDs share them.
Capped	`capped: true`	An identification that a limit stopped, so there's no event; below.
Budget		A daily, weekly or monthly amount a project, or a whole organization, may spend; past it, identifications are capped.
Spend limit		The same for one public key, a month at a time.
Zero trust mode		A project setting: the browser only gets the `requestId`, never the visitor id. See Project settings.

Visitor

A visitor is one browser on one device, as far as its hardware and settings can tell. Its visitorId is 20 letters and digits, like q1yLOPpzvOstEQCFQQxE. The id is per project: the same browser gets a different visitorId in each of your projects, so ids can't be matched across them.

The id comes from the device's signals (graphics card, canvas and audio output, fonts, cores, memory, platform and more), and the browser also keeps it in localStorage and a first-party cookie. What that means in practice:

Situation	Same visitor?
The same browser next week, after a browser update	Yes. The stored id is kept while the hardware still matches.
Cookies and site data cleared	Usually yes: the id is worked out from the device again. `confidence` is a little lower.
A private or incognito window	Usually yes, for the same reason; it also gets the `incognito` flag.
Chrome and Safari (or Firefox) on one laptop	No, usually two visitors: browsers draw, list fonts and report the graphics card differently.
A browser that leaves some of its signals out	Usually yes, with a lower `confidence`. When it could be one of several visitors, it gets a new id with a low `confidence`, and `visitorMatch.method` says `ambiguous-fingerprint`.
Two browser profiles in one browser	Often one visitor, since the device and browser are the same.
A phone and a laptop of the same person	No, two visitors. Pass the same `externalId` and both are linked to it.
Two identical phones (same model, OS version and settings)	Can be one visitor. Nothing in the browser tells them apart.

Shared visitor ids

Identical devices (the same phone model on the same OS) can share one visitor id, and a family can share one laptop. So a shared visitorId, and a Related duplicate, is a lead to review together with the external IDs, flags and connection, never proof on its own that two accounts are one person. The other pages link here rather than repeat it.

The visitor API lists every external ID a visitor was seen with, its flags and its latest events.

Event

Every get() that reaches the API stores one event, with the visitor id, the connection, the flags and the score. Its id is the requestId: 13 digits, a dot and 6 letters or digits, like 1792578564800.yU4Ety. The browser gets the requestId, your server reads the event with GET /events/{requestId}, and the dashboard's Events page lists them.

"Identification" is the same thing counted: the usage page and the bill count identifications, one per event. A get() answered from the agent's cache (the same requestId again), or answered { capped: true }, makes no event and isn't billed. So a get() is billed when it comes back with a fresh requestId.

External ID

Your own id for whoever is behind the browser: a user id, an account number, an order id. Pass it to get({ externalId }), or attach it on your server afterwards with PATCH /events/{requestId} (as at signup, before the user id exists). 1 to 256 characters; an empty one is refused. Use an internal, pseudonymous id, never an email address or a name: the id is stored with every event and sent in webhooks.

An external ID and a visitor aren't the same thing, and the gap between them is what you're looking for:

one external ID with several visitors is a user on a phone and a laptop, or an account shared between people;
one visitor with several external IDs is a shared computer, or one person making many accounts.

The dashboard and the Related API sometimes call external IDs "accounts", as in the related external IDs' accounts list. It's the same thing.

Returning

returning is false on a visitor's first event in the project and true on every later one. It comes back to the browser from get() (not in zero trust mode) and is stored on the event. It says nothing about the person: a returning visitor with a new external ID is a known browser making a new account.

Capped

The answer { capped: true } instead of a requestId: one of four limits stopped the identification, so nothing was identified or billed:

a project or organization budget;
a public key's monthly spend limit;
the project's usage limit during the beta;
the per-IP rate limit on identify (600 a minute per public key).

It's not an error and not a bot, but your server can't tell it apart from a bot that never ran the agent. No request ID says what to do, and Budgets and limits how each limit works.

Each event with an external ID links that external ID to the event's visitor id and IP. Two external IDs that share a visitor id are a duplicate; external IDs reached through shared values, a hop or several away, are related. Shared IPs are weak links (offices, mobile networks and VPN exits put many people on one IP), so only a shared visitor id makes a duplicate. See Related.

Other words

Velocity

How busy the event's visitor, its IP and its external ID were in the 5 minutes, the hour and the 24 hours up to and including this event. Every count includes the event itself, so a visitor's first event has events: 1. It's worked out when you read an event, so only GET /events/{requestId} returns it, not search, webhooks or sealed results. Every count and what to look for is in Smart signals › Velocity.

Public and secret keys

The public key (pk_) goes in browser code and only identifies. The secret key (sk_) stays on your server and reads every event. See Keys and billing.