Skip to content
bucker

Analytics actions: named, retroactive sets of events

An action gives a name to a set of things people did, so a funnel, a trend or an alias can say "checkout" instead of listing events. It is a definition only: nothing is captured for it. It is applied, at read time, to what Bucker has already stored, so an action created today counts last month. (The page is named actions-analytics so it never reads as the remediation actions registry, actions.md.)

An action is stored per project, behind the product-analytics gate (PA-01). A project that has not opened the gate has no actions and every read and write here refuses.

Matchers

An action holds one to ten matchers. A person counts for the action when any matcher fits (OR across matchers). A matcher fits only when every part it names fits the same occurrence (AND within one).

Kind Fits Read from
event a custom event, optionally one value of a promoted property (where: { property, equals }) pa_core_event_daily
url a page view whose path equals, contains or fits a route template such as /orders/:id the page-view event's promoted path property ($pageview / $pathname unless the matcher names others)
click an interaction-layer click: a selector chain (matched on its leaf), the element text, on an optional route template interaction_route_hours
screen a screen name of a mobile surface the $screen event's promoted $screen_name

Every event a matcher reads must be a core event of the project: the rollups hold no other, so an action over one could never count and would read as "nothing happened". Creating one is a 422 that names the declared set.

What the counts mean

  • A row counts once. The union of matchers is a union of stored rows, so two matchers that fit the same row (an equals and a route over the same path; two clicks on one selector) never double count. Each matcher also reports its own count.
  • Counts, not people. A match count is a number of events or interactions. Clicks are interactions, not people; the answer says so in approximation.
  • Values folded into other by the rollup's per-day value cap cannot be matched by a URL, screen or property matcher; the answer says so.
  • Element text is stored nowhere. No rollup keeps what an element said, so a matcher that names text is text_not_stored and contributes nothing. It is stated beside the number, never counted as zero. A click matcher that combines a selector with text is unverifiable for the same reason.
  • A URL, screen or property matcher on a property that is not promoted is property_not_promoted: breakdown rows exist only for promoted properties.
  • Interaction rollups are kept 90 days; a window that reaches past that says so.

A funnel step may name an action ({ "action": "checkout" }) wherever it names an event, and the saved insight is bound to the action's revision: a change to the matchers is a new answer, never a cached one.

Only a plain-event action can be a funnel step. A funnel needs, per person, the first time each step happened, and the stored first sightings are keyed by core event only: no URL, no selector, no property value. A plain-event action's step is the union of its events' sightings, one per person and day (the earliest), so a person who did two of its events in one day enters once. An action with a URL, click, screen or property matcher answers counts (a preview, a trend) and is tier_unavailable as a funnel step, with the reason action_not_subject_level naming the matcher kinds. Counting only its event half would be a silently wrong number.

The preview reproduces in the saved insight where it can. For a plain-event action the preview reports entries, the number of (person, day) pairs the action's events have a first sighting on: exactly the entered of a funnel's first step over the same days.

An action can also be the alias that names near-duplicate event names (sign_up, Signup): make an action of both and use it. Trend series and cohort rules read the action through the same matchActionSet once the insight grammar's series accept an action (see the wiring note).

Creating one

POST /orgs/:org/projects/:project/analytics/actions, or the MCP tool analytics_action_create. Both are the governed operation analytics_action.create:

  • ELEVATED, allowed by default. It changes no number that exists: nothing reads an action until an insight names it.
  • It asks a person when a click selector is fragile. The server checks every click matcher against the click stream of the last seven days, using the same leaf identity as heatmap_get's selector_check. A matcher is fragile when its leaf is a bare tag (button) or a position (li:nth-child(3)), was not seen on its route (or on any route, when it names none) in the last seven days, or names only element text. The fact is computed on the server; no argument states it, and an ALLOW policy row cannot lift it. An agent should call heatmap_get with include: ["selector_check"] first.
  • A preview is its own route (POST …/actions/preview): the 30-day counts per matcher and for the union, the selector check, and whether the create would ask. It stores nothing.
  • A key that is taken is refused (422 action_key_taken), whatever the other values. The create doors never turn into an edit of the existing action: that would hand an agent analytics_action.update, which has no MCP tool.

Changing and removing

Act Class Who
analytics_action.create ELEVATED, ALLOW (asks on a fragile selector) a person or an agent
analytics_action.update SENSITIVE, ASK a person through the dashboard or API; no MCP tool
analytics_action.archive ELEVATED, ALLOW for an action nothing reads; an edit (ASK) for one a saved insight or metric reads a person or an agent through the API
analytics_action.delete human-only (org:admin), irreversible a person on their own sign-in

An agent that wants a different action creates a new one and a person archives the old one, so no number an insight shows changes under an agent. The previous values are the inverse (operation_revert); a create's inverse is an archive. Delete is a person's act: an agent, an OAuth client or an organization token is refused. A saved insight that names a deleted action fails with "Action not found" rather than computing without it; archive is the reversible path.

Reading them

  • GET …/analytics/actions lists actions with their 30-day counts and what reads each.
  • GET …/analytics/actions/:action shows the matchers, each matcher's count and status, the daily series, the selector checks and the revision history.
  • taxonomy_get lists actions in the definitions block of the events page as kind: "action" with a 30-day match count: names, counts and matcher kinds only. No selector, URL pattern or element text reaches an agent through that block.

Selector chains and click text come from customer pages: they are never echoed by analytics_action_create, and a plan that carries them records them as free text so the engine can tell a value an agent copied from served telemetry.

Limits

At most 200 actions per project and ten matchers per action; a matcher value is at most 200 characters, a selector chain 1,024 and element text 64. A read pulls at most 50,000 rollup rows and says read_truncated when it stopped.