pages.engagement
Analyze page engagement with metrics on attention, bounce rate, and scroll depth to identify which pages hold visitors and where they drop off.
Instructions
Per-page metrics with a selectable detail level. The view parameter chooses what comes back:
view="summary" (default): pathname, pageviews, visitors. Cheap; use as the standard "top pages" call.
view="engagement": adds avg_engagement_seconds (active tab time from the SDK's pageview_end beacon), bounce_rate (% of single-page sessions that started on this path), avg_max_scroll (mean max scroll % the user reached on the page), and scroll_distribution (cumulative % of pageview_end events that reached 25/50/75/100 scroll depth — answers "how far do visitors actually get down this page"). Use to answer "which pages hold attention", "which pages bounce", or "are visitors reading past the fold".
view="sections": returns per-section view counts for the specified pathname. Requires
pathnameto be set. Each section is a data-clamp-section element on that page, counted once per session when at least 40% scrolls into view. Use to answer "which parts of /pricing get seen" or "is the FAQ being read".
Examples:
"top pages this week" → view omitted (or "summary"), period="7d"
"which pages bounce hardest" → view="engagement", then sort by bounce_rate
"how far down /pricing do people scroll" → view="sections", pathname="/pricing"
Limitations: avg_engagement_seconds is null for pages without pageview_end data (SDK <0.3 or pages closed during navigation). view="sections" requires the section-views SDK extension installed (see /docs/sdk/extensions/section-views) and only counts elements with the data-clamp-section attribute — pages with no instrumented sections return []. view="sections" without pathname returns 400.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | No | Target project ID (e.g. "proj_abc123"). Required when the credential has access to multiple projects. If omitted and only one project is accessible, that project is used automatically. Call `projects.list` to discover available project IDs. | |
| period | No | Time period. Use "today", "yesterday", "7d", "30d", "90d", or a custom range as "YYYY-MM-DD:YYYY-MM-DD" (e.g. "2026-01-01:2026-03-31"). Defaults to "30d". | |
| limit | No | Max rows to return (1-50). Defaults to 10. | |
| view | No | Detail level. "summary" (default) returns pathname/pageviews/visitors only. "engagement" adds avg_engagement_seconds and bounce_rate. "sections" returns per-section view counts for the pathname (requires pathname). | |
| pathname | No | Filter to a specific page path (e.g. "/pricing", "/blog/my-post"). Must start with /. | |
| utm_source | No | Filter by UTM source (e.g. "google", "twitter", "newsletter"). Case-sensitive, must match the value in the tracking URL. | |
| utm_medium | No | Filter by UTM medium (e.g. "cpc", "email", "social"). Case-sensitive. | |
| utm_campaign | No | Filter by UTM campaign name (e.g. "spring-launch", "product-hunt"). Case-sensitive. | |
| utm_content | No | Filter by UTM content (e.g. "hero-cta", "sidebar-banner"). Case-sensitive. | |
| utm_term | No | Filter by UTM term (e.g. "running+shoes"). Case-sensitive. | |
| referrer_host | No | Filter by referrer hostname (e.g. "news.ycombinator.com", "twitter.com", "github.com"). Use this to see what traffic from a specific source did. Must match the value returned by `traffic.breakdown(dimension="referrer_host")` exactly (lowercase, no protocol or path). | |
| country | No | ISO 3166-1 alpha-2 country code, uppercase (e.g. "US", "GB", "DE", "NL", "JP"). Filter results to visitors from this country. | |
| region | No | Administrative region inside a country (e.g. "California", "Bavaria"). Case-sensitive; must match the stored region exactly. Use traffic.breakdown(dimension="region") to discover values. | |
| city | No | City name (e.g. "San Francisco", "London"). Case-sensitive; must match the stored value. Use traffic.breakdown(dimension="city") to discover values. | |
| device_type | No | Device category. One of: "desktop", "mobile", "tablet". | |
| browser | No | Browser family (e.g. "Chrome", "Safari", "Firefox"). Use traffic.breakdown(dimension="browser") to discover the exact stored values. | |
| browser_version | No | Browser version string (e.g. "120.0"). Case-sensitive. | |
| os | No | Operating system family (e.g. "macOS", "iOS", "Windows", "Android"). Use traffic.breakdown(dimension="os") to discover stored values. | |
| os_version | No | OS version string (e.g. "14.2"). Case-sensitive. | |
| channel | No | Traffic channel. One of: "direct", "organic_search", "organic_social", "paid", "email", "referral". |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| pages | No | ||
| sections | No |