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
equalsand arouteover 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
otherby 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_storedand 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.
Funnels, trends and aliases
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'sselector_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 callheatmap_getwithinclude: ["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 agentanalytics_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/actionslists actions with their 30-day counts and what reads each.GET …/analytics/actions/:actionshows the matchers, each matcher's count and status, the daily series, the selector checks and the revision history.taxonomy_getlists actions in thedefinitionsblock of the events page askind: "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.