Skip to content
Sprigr

Microsoft Clarity

The Microsoft Clarity app connects Clarity’s behaviour analytics to Sprigr Team. Agents can read traffic (sessions, users, bot sessions), engagement time, scroll depth, popular pages and friction signals (dead clicks, rage clicks, quick-back clicks, excessive scrolling, script errors, error clicks), broken down by browser, device, country, OS, source, medium, campaign, channel or URL. One install can hold any number of Clarity projects, each with its own token, cache, daily history and request budget.

Prerequisites

Section titled “Prerequisites”
  • A Microsoft Clarity project, and permission to generate an API token for it. In Clarity, open the project’s Settings > Data Export and generate a new API token.
  • Admin or Owner role in your Sprigr Team organisation to install the app.

Installing and connecting

Section titled “Installing and connecting”

  1. Install the app

    Sign in to team.sprigr.com, open Apps in the sidebar, find Microsoft Clarity under Available, and install it. The CLARITY_API_TOKEN secret is optional: fill it in only if you want one project registered automatically on first run without opening the settings page. See Installing Apps.

  2. Add a Clarity project

    Open the app’s settings page from Apps > Installed. Under Clarity projects, click Add a Clarity project, give it a short name agents will use (for example “marketing” or “app”), and paste the project’s Data Export API token. Repeat for each project. Tokens can be rotated or the project removed from the same list.

  3. Check the connection

    Ask your agent “What Clarity projects are connected and how much budget is left today?” It calls clarity_status.

Budget, cache and history

Section titled “Budget, cache and history”
  • Live insights spend budget. clarity_insights reads the last one to three days for one project, optionally broken down by up to three dimensions. Results for the same project and parameters are cached for the rest of the UTC day; a live call spends one of that project’s 10 daily requests, and the agent only forces a refresh when you ask for fresher numbers.
  • History is free. Once a day the app snapshots each project’s site-wide insights into a history table. clarity_history reads that history for trends and anything older than 72 hours without spending any budget, so “compare rage clicks week over week” costs nothing.
  • Status. clarity_status reports, per project, whether it has a token, how many of today’s 10 requests are used and remain, what is cached, how many history days exist and their range, and the most recent API error.

What agents can do

Section titled “What agents can do”
ToolDescription
clarity_insightsLive behaviour analytics for one project over the last 1 to 3 days, with up to three breakdown dimensions
clarity_historyThe stored daily history of site-wide insights for one project, for trends and older questions
clarity_statusConnection and budget state per project, and the way to discover which projects exist

Clarity’s API exposes no session recordings, heatmaps or write surface; those stay in the Clarity UI.

Common use cases

Section titled “Common use cases”
  • Friction report. The agent lists pages with the most dead and rage clicks so the web team knows where to look in recordings.
  • Weekly trend. A scheduled workflow reports sessions, engagement time and scroll depth from the history, week over week.
  • Campaign landing check. “How are visitors from the newsletter behaving on the landing page?” breaks down by source and URL.
  • Multi-site comparison. With several projects connected, the agent compares the marketing site and the app on the same measures.

Troubleshooting

Section titled “Troubleshooting”

Not connected or no projects configured No project token has been added. Add a Clarity project on the settings page, or set CLARITY_API_TOKEN at install for a single project.

Budget exhausted Each project gets 10 API requests a day from Clarity, and failed attempts count. Ask about history instead, or wait for the UTC day to roll over. clarity_status shows remaining budget.

Only three days of live data Clarity’s export API looks back at most 72 hours. Anything older comes from the app’s daily history, which starts on the day the project was added.

Token rejected Tokens are per project and can be revoked in Clarity. Rotate the token from the settings page with a fresh one from the project’s Data Export settings.

Next steps

Section titled “Next steps”