Connect Microsoft Clarity

Microsoft Clarity provides behavioural metrics — rage clicks, dead clicks, scroll depth, engagement time — for each landing page. This integration uses Clarity’s Data Export API (not the tracking script alone), so a per-business Clarity project ID and API token are required. Open it from a business’s Settings → Data Sources → Clarity.

​

Generate Clarity credentials

1. In Microsoft Clarity, open the project for this client.
2. Go to Settings → Data Export.
3. Copy the Project ID.
4. Select Generate new API token and copy the token.

You’ll paste both into the Clarity panel in The Agency Engineer.

​

Clarity panel

The Clarity panel surfaces connection state and credentials:

• Status badge — Connected when a token is stored and verified.
• Description — Sync rage clicks, scroll depth, and other behavioral metrics from Microsoft Clarity. Generate a token at Clarity → Settings → Data Export → Generate new API token. The Clarity API allows 10 calls per project per day — the daily scheduler uses 4 of those.
• Last synced — Timestamp of the most recent successful sync (for example, 31/05/2026, 05:00:46).

​

Fields

​

Actions

• Update — Save changes to Project ID or API Token.
• Test — Verify the token by making one API call. Counts against your 10 daily Clarity calls.
• Refresh — Reload the connection state.
• Sync enabled (toggle) — Pause or resume the daily scheduler without disconnecting.
• Disconnect — Remove credentials. Historical metrics already stored are retained.

​

API limits enforced by the integration

The Data Export API has hard limits the integration respects:

• 10 calls per project per UTC day.
• 1–3 days of data per request (numOfDays).
• Up to 3 dimensions per call.
• No pagination — up to ~1,000 rows per response.

The daily scheduler uses 4 of the 10 daily calls to cover the dimension combos described below. That leaves 6 calls for manual tests and the client portal’s connection test.

​

What data is synced

Each API call slices data by up to three of these dimensions: Browser, Device, Country/Region, OS, Source, Medium, Campaign, Channel, URL The daily scheduler runs four default combos (one API call each):

1. URL + Device
2. URL + Source
3. URL + Country/Region
4. URL + Campaign + Channel

​

Metric groups returned by Clarity

Clarity returns groups including Traffic, ScrollDepth, EngagementTime, DeadClickCount, RageClickCount, ExcessiveScroll, QuickbackClick, ScriptErrorCount, ErrorClickCount, plus PopularPages, PageTitle, and ReferrerUrl. The sync normalises and stores these fields per dimension tuple: Dimension values land in columns like url, device, country, source, campaign, channel, browser, os, medium. URLs are normalised for consistent joins. Raw API rows are also kept in raw_payload for audit and debugging. Rows are stored in clarity_daily_metrics keyed by (business_id, date, dimension_hash) so different breakdowns don’t get summed together incorrectly.

​

How the sync works

1. Configuration — Saving credentials writes them to clarity_business_config. Test verifies the token (uses 1 daily call).
2. Scheduled sync — The daily clarityScheduler runs once per UTC day per enabled business, fetches 1 day of data, upserts into clarity_daily_metrics, and tracks each job in clarity_sync_jobs.
3. Failure handling — Bad auth disables the config automatically. Rate-limit errors leave it enabled so it retries the next UTC day.
4. Client portal — The same config and test endpoints are available under client-user routes for client-facing setup.

​

How the data is used

​

Automation rules (primary use)

Synced data is rolled up business-wide over the rule’s date window via getBusinessBehavioralAggregates (using the Device,URL slice to avoid double-counting). Those aggregates feed the rule builder and are attached to every campaign / ad set / ad evaluation: If Clarity isn’t configured or has no data for the window, values are null and conditions that depend on them don’t trigger — rules still run for other metrics. Example rules:

• Pause spend when clarity_rage_click_rate exceeds a threshold over the last 7 days.
• Send an alert when clarity_dead_clicks spikes after a landing page change.

​

Prepared but not wired

getUrlBehavioralAggregates (per landing URL) exists in the model but isn’t yet called elsewhere. Per-URL rules and optimiser logic are not active today — only business-wide aggregates are used.

​

Summary

​

Troubleshooting

​

Next steps