Glossary

Quick reference for terms used across the Pug docs, SDKs, and API. Definitions are kept concise — follow the linked pages for full explanations.

Term	Definition
Organization	Top-level tenant. Owns members, billing, and email configuration. Projects belong to an organization. See Core concepts.
Project	Isolated data boundary inside an organization. Owns events, profiles, insights, and API keys. All analytics queries are project-scoped. See Core concepts.
Public key (`pub_…`)	Project-scoped write credential for client SDKs. Sent as `x-api-key`; lets you ingest events and identify users, but cannot read analytics. Safe to ship in a browser bundle or mobile binary. See Authentication.
Private key (`prv_…`)	Project-scoped read/write credential for trusted server-side code. Sent as `x-api-key`; reaches `shared.*` services (insights, profiles). Never ship in client code. See Authentication.
Event	A named occurrence with custom properties and a timestamp — the atomic unit of analytics data. The event name is its `kind`; names starting with `pug.` are reserved. See Events API.
Property	A custom key/value pair attached to an event (string, integer, double, boolean, or timestamp). Keys must not start with `$`. Sent in `customProperties` on each event.
Auto-property	A `$`-prefixed property attached automatically by the SDK or server — for example `$url`, `$browser`, `$country`. `$`-prefixed keys are reserved and cannot be set as custom properties. See Auto-properties.
Well-known event	A standard event name (e.g. `page_view`, `purchase`) that carries a typed schema. Custom event names not in the registry are also accepted without schema validation. See Well-known events.
Profile	A persistent record representing one user — identified or anonymous — with an accumulated set of traits (properties). Created or updated by `identify()`. See Profiles API.
Anonymous ID	An SDK-generated identifier in the form `anon-…`, created when a visitor first arrives. Events are attributed to this ID until the user is identified.
External ID	Your stable user identifier (e.g. a database user ID), passed as `external_id` to `Identify`. Use a value that does not change — not an email address.
Distinct ID	The identifier an event is attributed to: the anonymous ID before `identify()` is called, the external ID after. Stored as `distinct_id` on every event.
Alias	The association of multiple identifiers with one profile — most commonly the anonymous-to-identified merge on the first `identify()` call (there is no separate `alias()` method). See Profiles API.
Session	A window of activity grouped by the SDK. A new session starts after the idle timeout (default 30 min) or the maximum session duration (default 24 h). The session ID is synced across browser tabs. See Core concepts.
Insight	A server-side analytics query specification — event selection, filters, time range, granularity, aggregation, and optional breakdowns. The same spec powers dashboard charts and the `InsightsService` API. Types: `TRENDS`, `SEGMENTATION`, `FUNNEL`, `RETENTION`, `USER_FLOW`. See Insights API.
Connect RPC	The API transport protocol used by all Pug services. Supports the Connect, gRPC, and gRPC-Web protocols over HTTP/1.1 and HTTP/2. Request path format: `/<package>.<Service>/<Method>`. See Authentication and the API overview.
Batch	A single `BatchCreate` call carrying up to 1 000 events. All event ingestion goes through this endpoint — there is no single-event API. See Events API.
Sampling rate	An SDK option (0–1) that keeps only a fraction of events. Useful to limit volume on high-traffic pages without disabling tracking entirely.

Glossary

Further reading