pages.engagement
Retrieve per-page engagement metrics including average engagement seconds and bounce rate to identify pages that hold attention or drive bounces.
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) and bounce_rate (% of single-page sessions that started on this path). Use to answer "which pages hold attention" or "which pages bounce".
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. | |
| device_type | No | Device category. One of: "desktop", "mobile", "tablet". | |
| channel | No | Traffic channel. One of: "direct", "organic_search", "organic_social", "paid", "email", "referral". |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| pages | No | ||
| sections | No |