Connect Microsoft Clarity¶

Connecting Microsoft Clarity gives Squoosh a source for calibrating your AI shoppers' device, geography, and traffic-source mix. This page covers setup and the connection's limits.

Beta: short-window traffic only

Each calibration read covers the previous 72 hours. Squoosh does not read a conversion signal from this API. For a conversion rate or a longer calibration window, connect Google Analytics, Shopify, or another analytics source alongside Clarity.

What the connection does¶

Squoosh reads Clarity's live-insights data to calibrate AI shoppers against your traffic. Traffic-source buckets are derived from Clarity's Source values using Squoosh's classification. They can differ from Clarity's own Channel grouping.

Clarity does not calibrate conversion rate. The connection is optional; Squoosh can build a pool from a general e-commerce mix. See AI shoppers for how calibration works.

Connect Clarity¶

A Clarity project admin must open Settings → Data Export → Generate new API token. The token belongs to the project, so no separate project ID is needed. See Microsoft's Data Export API instructions.

In the sidebar, click Integrations.
In the Microsoft Clarity row, click Connect.
Enter your Data export API token. Squoosh keeps it private after saving.
Click Connect.

Squoosh verifies the token before saving and then reads the first calibration snapshot.

What it grounds¶

Dimension	Source	Notes
Device	Clarity's Device breakdown	PC, Mobile, and Tablet are mapped. Other is excluded.
Geography	Clarity's Country/Region breakdown	Requires populated geography values.
Traffic source	Clarity's Source breakdown	Classified by Squoosh; not Clarity's Channel grouping. Missing Source values are excluded.
Conversion rate	Unavailable	Squoosh does not read a conversion signal from this endpoint.

Limits and caveats¶

Rolling 72-hour window. Every snapshot requests the previous 3 days from call time, with results in UTC. A longer requested calibration window does not extend this read.
Exactly 10 API requests per project per day. Verification calls, snapshot reads, and retries share this allowance with other API consumers. Squoosh uses an 8-hour refresh hint, but it is not a global quota gate; multiple server instances and connection checks can still exhaust the allowance.
1,000 rows with no pagination. Squoosh requests Device, Country/Region, and Source in one call. When the Traffic response reaches 1,000 rows, it flags the snapshot as capped; distributions may be incomplete.
Session-count basis. Squoosh uses totalSessionCount without subtracting totalBotSessionCount. Microsoft's reference does not define whether the total includes bots.
Always partial. The short window makes each Clarity snapshot a partial calibration signal.

The API's parameters, rolling window, quotas, and row cap are documented in Microsoft's Data Export API reference. Clarity's dashboard vocabulary is described in its filters overview.

Troubleshooting¶

Problem	What to do
Connection fails immediately	Check that the token is valid, has not expired or been revoked, and belongs to the intended project.
Permission denied	Ask the project admin to check the token's authorization.
Daily limit exceeded	Wait for Clarity's quota to reset. Repeated connection checks will not restore the allowance. Microsoft does not specify the reset instant.
Data looks thin or does not update	Check the short window, missing breakdown values, row cap, and daily quota.
Traffic sources differ from Clarity	Squoosh classifies Source values; Clarity has its own Channel grouping.
I need a conversion rate	Connect a source with conversion tracking, such as Google Analytics or Shopify.