Skip to content
bucker

Accounts

An account is a company, a workspace or a team that your product's users belong to. Bucker treats it as a first-class unit of analysis, next to the user, with no add-on and no multiplier: an account never changes the unit budget or the bill, and every insight can aggregate by it.

Everything here is behind the project's product-analytics gate (PA-01). A project that has not enabled analytics refuses the two account reads with 422 analytics_not_enabled; configuring account types does not read an end user and does not need the gate.

Account types

A project defines at most five account types (index 0 to 4), for example company, workspace and team. A type is a lower-case key ([a-z][a-z0-9_]{0,31}) the SDK names in accounts: { company: "acme" }, a label, and a nonPersonal flag. A person defines them; there is no MCP tool for any of it, because types are set once and change ingestion.

Act Who Class What it does
account_type.create a person's approved request SENSITIVE, always asked Adds a type. It lands archived and inert: no event links to it. Putting it to work is the same act again, approved on its own digest.
account_type.archive a person's approved request SENSITIVE, always asked Stops linking new events to the type. Nothing is removed; un-archiving is the reversal.
account_type.narrow analytics:write ELEVATED Makes a non-personal type personal again, so its names stop reaching readers.
account_type.widen a person only (org:admin) human-only Marks a type non-personal. An agent, a service, an OAuth client (even for the person who authorized it) and a derived credential are refused. A stated reason is required and the owners are told.
account_type.delete a person only (org:admin) human-only, irreversible Removes the type, its accounts, their usage and the membership recorded on subjects. The key is typed back after a preview that lists what goes. Archiving is the reversible path.

The first three run through the operations engine: the request names a type and states one thing it should be (label for a new type, archived, or nonPersonal); the family reads the act from the difference, never from an argument. A request that would widen is refused before anyone is asked. POST .../account-types/preview shows the act and whether a governed request can carry it, without writing anything. The five-type cap counts archived types.

An event carries accounts: { type: key }. The ingest door turns each key into a keyed pseudonym (purpose account, computed from the type and the identifier together, so the same identifier under two types is two accounts) before anything is stored, so no raw account identifier is ever held. The account fold links an event only to a live type: an archived type, an unknown type and a key that is not a pseudonym link nothing and are counted. A subject's current account of each type is recorded on the subject, so an account is a population of subjects and leaves with them on erasure. A subject in two companies is a member of the one it was last seen under.

Account properties (name, plan, anything else, up to 100 keys and 8 KiB) arrive through account sets. They are customer-supplied strings.

What a reader sees

Surface Key Name Properties Usage
GET .../accounts, GET .../accounts/{key} always (a pseudonym) only for a non-personal type, scrubbed and labelled untrusted never 7, 30 or 90 days, withheld under the floor
  • Names. A name reaches a reader without pii:read only when a person marked the type non-personal, and then it passes the agent-tier scrub and the injection scanner and is labelled untrusted. A name the scanner refuses is withheld and says so.
  • The floor is counted in accounts and in subjects. An account whose busiest day had fewer active subjects than the project's cohort floor reports no usage. A count of accounts below the floor is not stated. Inside an insight, an account with fewer member subjects than the floor contributes none, a filter that names several accounts and keeps fewer than the floor describes a few accounts and resolves to nobody, and an aggregation bucket with fewer than the floor active accounts reads 0.
  • Usage per account and day is events, distinct active subjects and sessions, exact per day. The distinct counts are not additive across days, so the read names the sum activeSubjectDays.

Insights by account

Every subject-keyed node (retention, lifecycle, stickiness, funnel) takes the account filter:

{ "type": "account", "account_type": "company", "op": "in", "values": ["acme", "globex"] }

values are the identifiers your SDK sent or the accounts' keys. The filter resolves to the subjects that currently belong to those accounts and can only narrow a node. Trends and paths keep no subject in their rollups, so for trends the account question is two aggregations in series.math:

  • x_active_accounts: distinct accounts with any product event in the bucket.
  • x_events_per_active_account: the bucket's product events over its distinct active accounts.

Both read the per-account daily rollup (the series' event does not narrow them), are exact across the days of a week or month bucket for the distinct count, and state that buckets under the floor were suppressed. The envelope carries an accounts block naming the floor and the types.

The insight widget

A dashboard tile of type insight shows a saved insight: its config is { "insightId": "...", "display"?: "line" | "bar" | "big_number" | "table" }, never a node. It runs the saved node through the same compiler as everything above, as a fixed principal without pii:read, so every viewer of a board sees the same figures. A draft insight renders as a note (share it to put it on a board), a project without product analytics renders a note, an insight the rollups cannot answer says why, and an insight of another organization is an empty tile. Widget rows written before widgets had keys still load.

Doors

Route Relation
GET /orgs/{org}/projects/{project}/account-types read_analytics
POST .../account-types/preview configure_analytics
POST .../account-types configure_analytics, governed account_type.create
POST .../account-types/{type}/archive configure_analytics, governed account_type.archive
POST .../account-types/{type}/narrow configure_analytics, governed account_type.narrow
POST .../account-types/{type}/widen admin on the organization, human-only
POST .../account-types/{type}/delete/preview admin on the organization
POST .../account-types/{type}/delete admin on the organization, human-only
GET .../accounts?type=&window=&limit=&cursor= read_analytics
GET .../accounts/{accountKey}?type=&window= read_analytics

Another organization's project is the same 404 as one that does not exist.