How to build Contentsquare dashboards in Metabase

Contentsquare is a digital experience analytics platform — the company behind Hotjar and Heap — covering journey analysis, heatmaps, session replay, and product analytics. Metabase is where you turn those customer signals into shared, trustworthy dashboards. This guide covers two complementary paths: a lightweight MCP + CLI route that pulls live data with the Contentsquare MCP server and loads a CSV into Metabase with the Metabase CLI, and a durable pipeline route that syncs Contentsquare data into a database so you can build dashboards anyone can read.

How do you connect Contentsquare to Metabase?

Most teams combine both routes: use MCP and CLI uploads for a fast first pass, then move recurring product reporting to a warehouse-backed model.

What can you analyze from Contentsquare data in Metabase?

• Session frustration signals by journey — built from behavioral event rollups and the related journeys and funnels, frustration scores, heatmap aggregates data your sync exposes.
• Funnel conversion and drop-off — built from behavioral event rollups and the related journeys and funnels, frustration scores, heatmap aggregates data your sync exposes.
• Feature adoption from Heap events — built from behavioral event rollups and the related journeys and funnels, frustration scores, heatmap aggregates data your sync exposes.
• Frustration score by page and release — built from behavioral event rollups and the related journeys and funnels, frustration scores, heatmap aggregates data your sync exposes.
• Journey comparison by segment — built from behavioral event rollups and the related journeys and funnels, frustration scores, heatmap aggregates data your sync exposes.

Which Contentsquare dashboards should you build in Metabase?

How do you use the Contentsquare MCP server with the Metabase CLI?

Pair the Contentsquare MCP server with the Metabase CLI for fast, hands-on analysis. MCP is useful for scoped lookups and summarized exports; the Metabase CLI's upload command loads CSV data into Metabase and creates a ready-to-query table and model.

Example workflow

• Ask the MCP server for a daily rollup of behavioral event rollups for the flows or features you care about.
• Export the result as CSV, keeping stable IDs, statuses, segments, and timestamps.
• Run mb upload csv to load it into Metabase as a table and model, then build questions and dashboards on top.

Be honest about the limits

• MCP lookups are excellent for exploration, not scheduled reporting.
• A CSV upload is a snapshot; refresh it with mb upload replace or move to the pipeline for real history.
• Daily rollups are required for adoption and frustration trends — a single snapshot can't show direction.
• mb upload csv needs an uploads database configured under Admin → Settings → Uploads.

How do you set up Contentsquare MCP and the Metabase CLI?

{
  "mcpServers": {
    "contentsquare": {
      "url": "https://api.contentsquare.com/mcp"
    }
  }
}

Setup normally starts in-app under Analysis setup → Model Context Protocol (MCP). Tool calls that return analytics data are metered from an account-level allowance (300 per month on the free tier; more on paid plans), but the server is available on every tier. Contentsquare owns Hotjar and Heap, and this is the one official MCP across all three brands — if you're searching for a "Hotjar MCP" or "Heap MCP", this is it.

# Install the Metabase CLI
npm install -g @metabase/cli

# Log in (opens your browser; requires Metabase v62+)
mb auth login --url https://your-metabase.example.com

# Load a behavioral-event-rollups export — creates a table AND a model
mb upload csv --file contentsquare-behavioral-event-rollups.csv --collection root

# Refresh that same table later from a new export
mb upload replace <table-id> --file contentsquare-behavioral-event-rollups.csv

Can you generate a Contentsquare dashboard with AI?

Yes. Use the prompt below with any assistant that can run the Contentsquare MCP server and the Metabase CLI. It works end to end: if Contentsquare tables already exist in Metabase it analyzes those; otherwise it pulls scoped, summarized data over MCP, loads it with mb upload csv, then builds the dashboard and caveats any metric that needs missing history.

Create a polished Metabase dashboard for Contentsquare product experience analytics.
Work end to end: get the data into Metabase if it isn't there yet, then build.

Goal: Help product teams understand feature adoption, frustration signals, activation funnels, and account engagement from Contentsquare data.

Step 1 — Find or load the data:
- First, check what already exists in Metabase (search for contentsquare tables and
  models). If durable Contentsquare data is already present — synced from a warehouse
  or uploaded earlier — use it and skip to Step 2.
- If nothing is there, pull a scoped, summarized export with the Contentsquare MCP server:
  behavioral event rollups, plus journeys and funnels, frustration scores, heatmap aggregates.
  Prefer aggregated or rollup views over raw events. Write each result to a CSV,
  then load it with the Metabase CLI — run "mb upload csv --file <export>.csv" so
  each upload creates a table and a ready-to-query model. Use "mb upload replace
  <table-id> --file <export>.csv" to refresh an existing table instead of creating
  duplicates.

Step 2 — Inspect before querying:
Do not assume exact table or column names. Inspect available fields, statuses,
segments, and timestamps, and whether history exists before creating duration
or trend cards.

Important:
- Build on whatever data is present; don't claim Metabase connects natively to
  Contentsquare — it reads a database or CLI-uploaded tables.
- Never load raw event or session streams into Metabase; use rollups, entity
  tables, and response- or request-grain data.
- Compute NPS as % promoters (9-10) minus % detractors (0-6) on the 0-10 scale,
  and always show response volume next to the score.
- Only compute durations (time to close, time to complete) when the required
  timestamps exist.
- Exclude internal, test, and anonymous-preview activity from headline cards,
  and segment by plan or customer segment where the field exists.
- A single CSV is a point-in-time snapshot: only build trend cards if there is a
  usable date column or multiple periods have been uploaded.

Dashboard title: Contentsquare Product Experience Overview

Sections:
1. Executive summary: Weekly active users; Adoption rate of key features;
   Frustrated-session share; Activation rate.
2. Adoption: Active accounts by feature; usage breadth per account.
3. Frustration: Rage, dead, and error clicks by page and flow.
4. Activation: Cohort funnel by step; time to first key action.
5. Accounts: Engagement trends; accounts with declining usage.

Filters: Date range, Product area, Segment, Status, Survey or Feature.

Output: Build the dashboard if you have permission; otherwise provide the exact
questions, SQL, model definitions, and layout. Include caveats for any metric
that cannot be calculated from the available data.

How do you sync Contentsquare data into a database or warehouse?

For dashboards that need history and reliability, land Contentsquare data in a database first, then connect Metabase to that database.

Connector options

• Managed ETL or native export — use a connector or the vendor's own warehouse sync when one covers the objects you need.
• Custom pipeline — use the Contentsquare APIs (including Heap Connect) for control over objects, fields, and refresh cadence.
• MCP + CSV — use this for quick exploration and one-off slices.

Heap Connect — now marketed as Data Connect under Contentsquare — is the standout pipeline: it auto-models Heap's behavioral data into BigQuery, Redshift, or Snowflake retroactively, with relabeled events backfilling full history. Fivetran also covers Heap for managed ETL; journey and heatmap aggregates come via the Contentsquare APIs.

Notes

• Decide the grain first — request, response, or daily rollup — it drives every trend card and the warehouse bill.
• Land raw entity tables first, then build clean Metabase models on top.
• Normalize account, feature or flow, segment, usage-date, event-count, and user-count fields.

How should you model Contentsquare data in Metabase?

Core tables

Modeling advice

• Build a clean product_usage_rollups model with common columns across tools, so multi-source dashboards don't fork definitions.
• Separate entity tables (requests, surveys, features, accounts) from time-series rollups and event-grain tables.
• Exclude internal users, test workspaces, and preview traffic from headline metrics; keep segment as an explicit column.
• Use stable IDs for account, request, and survey joins; display names change.

Which Contentsquare metrics should you track in Metabase?

What SQL powers Contentsquare dashboards in Metabase?

These assume a cleaned analytical model in a warehouse (PostgreSQL dialect). Adjust table and column names to match your pipeline.

WITH eligible_accounts AS (
  -- One eligible population, used on BOTH sides of the ratio.
  -- Add plan/entitlement filters here if the feature ships on some plans only.
  SELECT id AS account_id
  FROM accounts
  WHERE is_active
    AND NOT is_internal
), adoption AS (
  SELECT
    r.feature_name,
    COUNT(DISTINCT r.account_id) AS adopting_accounts
  FROM product_usage_rollups r
  JOIN eligible_accounts e ON e.account_id = r.account_id
  WHERE r.usage_date >= CURRENT_DATE - INTERVAL '28 days'
  GROUP BY r.feature_name
)
SELECT
  a.feature_name,
  a.adopting_accounts,
  (SELECT COUNT(*) FROM eligible_accounts) AS eligible_accounts,
  ROUND(
    100.0 * a.adopting_accounts
    / NULLIF((SELECT COUNT(*) FROM eligible_accounts), 0), 1
  ) AS adoption_pct
FROM adoption a
ORDER BY adoption_pct DESC;

SELECT
  page_or_flow,
  date_trunc('week', usage_date) AS week,
  ROUND(
    1000.0 * SUM(rage_clicks) / NULLIF(SUM(sessions), 0), 2
  ) AS rage_clicks_per_1k_sessions
FROM session_rollups
GROUP BY 1, 2
ORDER BY 1, 2;

WITH recent AS (
  SELECT account_id, SUM(event_count) AS events_28d
  FROM product_usage_rollups
  WHERE usage_date >= CURRENT_DATE - INTERVAL '28 days'
  GROUP BY account_id
), prior AS (
  SELECT account_id, SUM(event_count) AS events_prior_28d
  FROM product_usage_rollups
  WHERE usage_date >= CURRENT_DATE - INTERVAL '56 days'
    AND usage_date < CURRENT_DATE - INTERVAL '28 days'
  GROUP BY account_id
)
SELECT
  p.account_id,
  p.events_prior_28d,
  COALESCE(r.events_28d, 0) AS events_28d,
  ROUND(
    100.0 * (COALESCE(r.events_28d, 0) - p.events_prior_28d)
    / NULLIF(p.events_prior_28d, 0), 1
  ) AS change_pct
FROM prior p
LEFT JOIN recent r USING (account_id)
WHERE p.events_prior_28d > 0
ORDER BY change_pct ASC
LIMIT 20;

What are common mistakes when analyzing Contentsquare in Metabase?

Related

Related analytics

Related dashboards

Related integrations

FAQ