Skip to main content
Microsoft Clarity is a free behavior analytics tool — it records how visitors actually use your website, with session recordings, heatmaps and frustration signals such as rage clicks, dead clicks and quick backs. This connector brings the figures behind the Clarity dashboard into your Lakehouse: traffic, engagement time, scroll depth and the frustration counters, broken down by page, device, browser, operating system, country and campaign.
Clarity’s Data Export API only exposes the last 24, 48 or 72 hours of a project, allows 10 requests per project per day, and returns a single total for the whole window rather than one figure per day. There is no way to backfill history: the table is built up one snapshot at a time, so schedule this source to run once a day and let it accumulate. Days on which the source does not run are lost permanently.

​
1. Add your Microsoft Clarity access

  1. In the Sources tab, click on the “Add source” button located on the top right of your screen. Then, select the Microsoft Clarity option from the list of connectors.
  2. Click Next and you’ll be prompted to add your access.
  • API Token: Your Clarity Data Export token. In Clarity, open the project, go to Settings → Data Export → Generate new API token, give it a name and copy the token immediately. Only project admins can create one, and each token gives access to a single project.
  • Days per Snapshot: (Optional) How many of the most recent days each snapshot covers: 1, 2 or 3. Keep it at 1 — the default — and run this source once a day, so each snapshot lines up with a calendar day. A larger window returns one combined total for the whole period, which cannot be split back into daily figures.
  • Dimension Breakdowns: (Optional) Extra breakdowns to pull, on top of the project-wide figures that are always collected. Each entry costs one of the 10 daily API requests, and may combine up to three of Browser, Device, Country, OS, Source, Medium, Campaign, Channel and URL — for example URL for per-page figures, or Source,Medium for per-campaign ones. Leave it empty to spend a single request per sync.
  • Start Date: (Optional, advanced) Ignored by this source. The Clarity API has no date filter and no history, so every sync reports the last few days regardless of this value.
A token stops working as soon as the user who created it loses access to the project. If the source starts failing to authenticate, generate a new token under Settings → Data Export and update it here.
  1. Click Next.

​
2. Select your Microsoft Clarity streams

  1. The next step is letting us know which streams you want to bring. You can select entire groups of streams or only a subset of them.
    Tip: The stream can be found more easily by typing its name.
If you don’t see a stream you were expecting to find, please check if your access key has access to it. If that’s not the issue, then it’s probably because we still haven’t implemented it. Feel free to get in touch and request it!
  1. Click Next.

​
3. Configure your Microsoft Clarity data streams

  1. Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a name for each table (which will effectively contain the fetched data) and the type of sync.
  • Layer: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
  • Table name: we suggest a name, but feel free to customize it. You have the option to add a prefix to all tables at once and make this process faster!
  • Sync Type: depending on the data you are bringing to the lake, you can choose between INCREMENTAL and FULL_TABLE. Read more about Sync Types here.
Use INCREMENTAL for this source. Each run brings a new snapshot of the last few days, and incremental sync is what stacks those snapshots into a history. A full sync would replace the table with the latest snapshot and discard everything collected before it.
  1. Click Next.

​
4. Configure your Microsoft Clarity data source

  1. Describe your data source for easy identification within your organization. You can inform things like what data it brings, to which team it belongs, etc.
  2. To define your Trigger, consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times).
  3. Optionally, you can define some additional settings (if available).
  • Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource here.
  • Determine when to execute an Additional Full Sync. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while.

​
Check your new source!

  1. Click Next to finalize the setup. Once completed, you’ll receive confirmation that your new source is set up!
  2. You can view your new source on the Sources page. Now, for you to be able to see it on your Catalog, you have to wait for the pipeline to run. You can now monitor it on the Sources page to see its execution and completion. If needed, manually trigger the pipeline by clicking on the refresh icon. Once executed, your new table will appear in the Catalog section.
If you encounter any issues, reach out to us via Slack, and we’ll gladly assist you!

​
How the data is replicated

Clarity’s API answers with the figures of the last 24, 48 or 72 hours counted back from the moment of the request — it carries no date of its own and cannot be asked for a past period. Every run is therefore a snapshot, and the table grows by appending snapshots rather than by updating rows. Each row is stamped with extracted_at — the moment of the sync, which is also the incremental replication key — plus the window_start and window_end it covers. To read the latest state of a metric, filter on the most recent extracted_at. To follow it over time, group by day of extracted_at. Because a snapshot is a fresh reading rather than a correction of the previous one, running the source more than once a day produces overlapping windows for the same period. Running it once a day with Days per Snapshot at 1 keeps one clean reading per calendar day.
All timestamps and figures are in UTC, as returned by Clarity.

​
How the table is organized

The Clarity API returns its data grouped by metric, and each metric brings its own set of figures. The project_insights table keeps that shape: one row per metric and per dimension value, rather than one wide row per page or per day.
  • metric_name says which metric a row belongs to — Traffic, EngagementTime, ScrollDepth, PopularPages, Browser, Device, OS, Country, PageTitle, ReferrerUrl, DeadClickCount, RageClickCount, ExcessiveScroll, QuickbackClick, ScriptErrorCount or ErrorClickCount. Only the columns that metric reports are filled; the rest are null.
  • breakdown says what was requested: overall for the project-wide request, or the dimension names you configured, such as URL or Source,Medium.
  • The dimension columns — url, page_title, referrer_url, os, browser, device, country, source, medium, campaign, channel — carry the value the row refers to.
  • raw always holds the original row exactly as Clarity returned it, as a JSON string. Clarity documents only part of the fields each metric returns, so anything without a dedicated column is still readable there.
The project-wide request already includes Clarity’s own breakdowns — traffic by browser, device, operating system and country, plus popular pages, page titles and referrers — at no extra request. Only add Dimension Breakdowns when you need a metric crossed with a dimension Clarity does not break down on its own, such as scroll depth per page.

​
Limits and quotas

Clarity applies the following limits to every project, and they cannot be raised — Clarity is a free product with no paid tier for the API:
The quota is shared by everything that calls the API with tokens of the same project, including manual tests. If several sources or scripts read the same Clarity project, plan the runs so they fit within the 10 daily requests.

​
Streams and Fields

Below you’ll find all available data streams from Microsoft Clarity and their corresponding fields.
The dashboard figures of the Clarity project, as one row per metric and dimension value per snapshot.Key Fields:
  • id - Deterministic identifier of the row, hashed from the snapshot timestamp, the requested breakdown, the metric and the dimension values. Clarity does not ship an identifier of its own
  • extracted_at - Timestamp of the sync that produced this snapshot, shared by every row of the run and used as the incremental replication key
  • window_start - Start of the period the figures cover, that is extracted_at minus num_of_days
  • window_end - End of the period the figures cover, identical to extracted_at
  • num_of_days - Length of the snapshot window in days: 1, 2 or 3
  • project_id - Identifier of the Clarity project the data belongs to, read from the API token
  • breakdown - Which dimensions were requested for this row: overall for the project-wide request, or the dimension names joined by commas
  • metric_name - Clarity metric this row belongs to, which determines the value columns that are filled
  • url - Page URL the row refers to, on the URL breakdown and on page-level metrics
  • page_title - Title of the page the row refers to, on the PageTitle metric
  • referrer_url - Address the visit came from, on the ReferrerUrl metric
  • os - Operating system of the visitors counted in this row, such as Windows, Android or iOS
  • browser - Browser of the visitors counted in this row, such as Chrome, Safari or Edge
  • device - Device category of the visitors counted in this row: PC, Mobile, Tablet or Other
  • country - Country or region the visitors counted in this row browsed from
  • source - Traffic source of the visits, taken from the utm_source parameter
  • medium - Traffic medium of the visits, taken from the utm_medium parameter
  • campaign - Marketing campaign the visits came from, taken from the utm_campaign parameter
  • channel - Marketing channel Clarity classified the visits into, such as Direct, OrganicSearch, PaidSearch or Social
  • sessions_count - Number of sessions this row accounts for, reported by most metrics as the population the metric was measured over
  • total_session_count - Total number of sessions in the window, reported by the Traffic metric
  • total_bot_session_count - Number of sessions attributed to bots, reported by the Traffic metric. Subtract it from total_session_count for human traffic
  • distant_user_count - Number of distinct users in the window, reported by the Traffic metric
  • pages_per_session_percentage - Average number of pages viewed per session, reported by the Traffic metric
  • sub_total - Count reported by the counting metrics: how many dead clicks, rage clicks, excessive scrolls, quick backs, script errors or error clicks were observed, depending on metric_name
  • average_scroll_depth - Average share of the page visitors scrolled through, in percent, reported by the ScrollDepth metric
  • total_time - Total time visitors spent, in seconds, reported by the EngagementTime metric. Includes time the page was open but idle
  • active_time - Time visitors actively interacted, in seconds, reported by the EngagementTime metric
  • visits_count - Number of visits this row accounts for, when the metric reports it
  • raw - The untouched row exactly as Clarity returned it, as a JSON string