exploring-autocapture-events

Run a count query before doing anything else. If the count is zero, autocapture may be disabled. There are two ways this happens:

• Project settings — the team can set autocapture_opt_out in PostHog project settings
• SDK config — the posthog-js init() call can pass autocapture: false

Tell the user if no data is found so they can check both settings.

SELECT count() as cnt
FROM events
WHERE event = '$autocapture'
  AND timestamp > now() - INTERVAL 7 DAY

Start broad using the materialized columns. The goal is to understand what users are clicking before narrowing down.

Useful explorations:

• Top clicked tag names (via elements_chain_elements)
• Top clicked text values (via elements_chain_texts)
• Top clicked hrefs (via elements_chain_href)
• Raw elements_chain values for a specific page (filtered by properties.$current_url)

See example queries for all patterns.

Once the user identifies an interaction they care about, find a CSS selector that identifies it.

Priority order for selector attributes (best first):

1. data-attr or other data-* attributes — highest specificity, stable across deploys, developer-intended anchors. Search with match(elements_chain, 'data-attr=') or extractAll.
2. Element ID (attr_id) — also highly stable, queryable via elements_chain_ids.
3. Tag + class combination — moderately stable but classes change with CSS refactors.
4. Text content — fragile (changes with copy edits, i18n) but sometimes the only option.
5. Tag name alone — too broad on its own, useful as a qualifier.

When a data-attr value is found, construct a selector like [data-attr="value"] or button[data-attr="value"].

A selector is only useful if it matches the intended interaction and not unrelated events.

Run a uniqueness check using elements_chain =~ with the regex pattern for the selector. Then sample matching events to inspect what the selector actually captures. Compare the count against total autocapture volume to understand selectivity.

A good selector matches a single logical interaction. If it matches too many distinct elements, refine it in the next step.

If the selector alone is not unique enough, layer on additional filters:

• Text filter — match by element text content using elements_chain_texts
• URL filter — restrict to a specific page using properties.$current_url
• Href filter — match by link target using elements_chain_href

Re-run the uniqueness check after each refinement. Only include filters that are needed — fewer filters means more resilience to minor DOM changes.

When the user wants a funnel, trend, or other insight, the filter shape is different from HogQL. Each step in a FunnelsQuery / TrendsQuery is an EventsNode (or ActionsNode) with event: "$autocapture" and a properties array.

Two distinct property type values matter — they are not interchangeable:

• type: "element" — keys: selector, tag_name, text, href. Matched against the parsed elements_chain. Operator support is split:
  • selector and tag_name only support exact and is_not — any other operator is rejected by the query engine and the query errors.
  • text and href accept the full string operator set (exact, is_not, icontains, not_icontains, regex, not_regex, is_set, is_not_set).
• type: "event" — keys: any of the canonical autocapture properties ($event_type, $el_text, $current_url) or anything else on the event. Standard event-property operators (exact, icontains, regex, etc.).

Example funnel from clicking one button to clicking another:

{
  "kind": "FunnelsQuery",
  "series": [
    {
      "kind": "EventsNode",
      "event": "$autocapture",
      "properties": [
        {
          "type": "element",
          "key": "selector",
          "value": ["[data-attr=\"autocapture-series-save-as-action-banner-shown\"]"],
          "operator": "exact"
        }
      ]
    },
    {
      "kind": "EventsNode",
      "event": "$autocapture",
      "properties": [
        {
          "type": "element",
          "key": "selector",
          "value": ["[data-attr=\"autocapture-save-as-action\"]"],
          "operator": "exact"
        }
      ]
    }
  ]
}

Two things easy to get wrong:

• value is an array even when matching a single selector
• The selector string includes the [data-attr="..."] wrapper — it is a CSS selector, not a bare attribute value

Decision rule: prefer an action (ActionsNode referencing an existing action — see Step 8) when the interaction will be referenced more than once; inline type: "element" / type: "event" filters when it's a one-off insight; raw HogQL (Step 7) when joining across events or doing custom aggregations.

The discovered selector can be used directly in HogQL without creating an action.

Trends — count matching clicks over time:

SELECT
  toStartOfDay(timestamp) as day,
  count() as clicks
FROM events
WHERE event = '$autocapture'
  AND timestamp > now() - INTERVAL 14 DAY
  AND elements_chain =~ '(^|;)button.*?data-attr="checkout"'
GROUP BY day
ORDER BY day

Funnel — pageview to click conversion:

SELECT
  person_id,
  first_pageview,
  first_click_after
FROM (
  SELECT
    p.person_id,
    p.pageview_time as first_pageview,
    min(c.click_time) as first_click_after
  FROM (
    SELECT person_id, min(timestamp) as pageview_time
    FROM events
    WHERE event = '$pageview'
      AND timestamp > now() - INTERVAL 14 DAY
      AND properties.$current_url ILIKE '%/pricing%'
    GROUP BY person_id
  ) p
  INNER JOIN (
    SELECT person_id, timestamp as click_time
    FROM events
    WHERE event = '$autocapture'
      AND timestamp > now() - INTERVAL 14 DAY
      AND elements_chain =~ '(^|;)button.*?data-attr="signup"'
  ) c ON p.person_id = c.person_id AND c.click_time > p.pageview_time
  GROUP BY p.person_id, p.pageview_time
)

For recurring analysis, prefer creating an action (next step) or using posthog:query-trends / posthog:query-funnel with the action.

Actions are the durable version of ad-hoc selector queries. Once the criteria uniquely identify the interaction, create an action using posthog:action-create.

Construct the step with only the filters needed for uniqueness:

{
  "name": "Clicked checkout button",
  "steps": [
    {
      "event": "$autocapture",
      "selector": "button[data-attr='checkout']",
      "text": "Complete Purchase",
      "text_matching": "exact",
      "url": "/checkout",
      "url_matching": "contains"
    }
  ]
}

Available step fields for $autocapture:

• selector — CSS selector (e.g. button[data-attr='checkout'])
• tag_name — HTML tag name (e.g. button, a, input)
• text / text_matching — element text (exact, contains, or regex)
• href / href_matching — link href (exact, contains, or regex)
• url / url_matching — page URL (exact, contains, or regex)

After creation, verify with matchesAction():

SELECT count() as matching_events
FROM events
WHERE matchesAction('Clicked checkout button')
  AND timestamp > now() - INTERVAL 7 DAY