# Microsoft Clarity

> Microsoft Clarity is a free behavioral analytics service — heatmaps, session
> recordings, frustration signals (rage clicks, dead clicks, excessive scroll),
> Smart Events, funnels and AI/bot traffic analytics. Instrumentation is a
> client-side tracking tag or a mobile SDK. Data comes back out through one
> HTTP operation (the Data Export API) or through a first-party MCP server.
> Clarity is free forever, with no paid tier and no credit card.

<!--
generated: 2026-08-13
method: generated
source: apis.yml plus artifacts in this repository; Microsoft Clarity publishes
no /llms.txt of its own — probed 2026-08-13, https://www.clarity.ms/llms.txt
returned 404, https://learn.microsoft.com/llms.txt returned 404, and
https://clarity.microsoft.com/llms.txt returned an HTTP 200 HTML SPA shell
rather than a document.
-->

## What you can call

- [Data Export API](https://learn.microsoft.com/en-us/clarity/setup-and-installation/clarity-data-export-api): One operation. `GET https://www.clarity.ms/export-data/api/v1/project-live-insights` returns dashboard metrics as JSON for the last 1-3 days, broken down by up to three dimensions.
- [Clarity client API](https://learn.microsoft.com/en-us/clarity/setup-and-installation/clarity-api): In-page JavaScript command API — `window.clarity(verb, ...)` with verbs consent, identify, set, event, upgrade — plus the `data-clarity-mask` / `data-clarity-unmask` HTML attributes.
- [Clarity MCP Server](https://learn.microsoft.com/en-us/clarity/third-party-integrations/clarity-mcp-server): First-party MCP server, `@microsoft/clarity-mcp-server`. Local stdio only — `npx @microsoft/clarity-mcp-server --clarity_api_token=<token>`. There is no hosted MCP endpoint.

## Authentication

- HTTP API: a project-scoped JWT sent as `Authorization: Bearer <token>`. Generated by a project admin at Clarity Settings -> Data Export -> Generate new API token. No OAuth, no scopes, no client registration.
- Client API: the Clarity project ID is the key. No separate credential.
- MCP server: reuses the same Data Export API token.

## Limits you must plan around

- 10 API requests per project per DAY. This is the binding constraint on every integration.
- Responses cap at 1,000 rows and cannot be paginated.
- Lookback is 1, 2 or 3 days only. There is no historical export.
- At most 3 dimensions per request.
- No rate-limit response headers of any kind. Exhaustion is a bare 429 with the message "Exceeded daily limit"; there is no counter to read and no Retry-After.
- The MCP server draws on the same 10/day budget.
- Recordings retain for 30 days (favorites and a sampled subset up to 9 months).
- Results are returned in UTC.

## Dimensions

Browser, Device, Country/Region, OS, Source, Medium, Campaign, Channel, URL

## Metrics returned

Scroll Depth, Engagement Time, Traffic, Popular Pages, Browser, Device, OS,
Country/Region, Page Title, Referrer URL, Dead Click Count, Excessive Scroll,
Rage Click Count, Quickback Click, Script Error Count, Error Click Count.
Metrics are not selectable — every call returns the full set, sliced by the
dimensions you requested.

## Errors

- 400 BadRequest — invalid request parameters
- 401 Unauthorized — missing, invalid, or expired token
- 403 Forbidden — token not authorized for operation
- 429 TooManyRequests — exceeded daily limit

No error response body is documented. Branch on the status code.

## First-party libraries

- npm `@microsoft/clarity` 1.0.2 (2025-11-27) — web
- npm `@microsoft/clarity-mcp-server` 2.0.1 (2025-10-28) — MCP server
- npm `@microsoft/react-native-clarity` 4.7.0 (2026-08-12)
- npm `@microsoft/cordova-clarity` 3.0.0 (2025-05-22)
- npm `clarity-js` / `clarity-decode` / `clarity-visualize` 0.8.68 (2026-07-19) — open source, github.com/microsoft/clarity
- Maven `com.microsoft.clarity:clarity` and `:clarity-compose` 3.9.0 (2026-08-11) — Android
- pub.dev `clarity_flutter` 1.9.0 (2026-04-26)
- Swift Package `github.com/microsoft/clarity-apps` 3.5.4 (2026-06-17) — iOS

## Docs

- Documentation: https://learn.microsoft.com/en-us/clarity/
- Data Export API reference: https://learn.microsoft.com/en-us/clarity/setup-and-installation/clarity-data-export-api
- Client API reference: https://learn.microsoft.com/en-us/clarity/setup-and-installation/clarity-api
- MCP server: https://learn.microsoft.com/en-us/clarity/third-party-integrations/clarity-mcp-server
- SDK changelog: https://learn.microsoft.com/en-us/clarity/mobile-sdk/sdk-changelog
- FAQ: https://learn.microsoft.com/en-us/clarity/faq
- Pricing: https://clarity.microsoft.com/pricing
- Sign in / sign up: https://clarity.microsoft.com/
- GitHub: https://github.com/microsoft/clarity, https://github.com/microsoft/clarity-apps, https://github.com/microsoft/clarity-mcp-server
- Support: clarityMS@microsoft.com

## What does not exist

Do not look for these — they are absent, not hidden:

- No OpenAPI/Swagger document published by Microsoft (the spec in this repo is API Evangelist's, written from the docs).
- No hosted/remote MCP endpoint. stdio package only.
- No A2A agent card on any Clarity host.
- No webhooks, no event stream, no AsyncAPI.
- No OAuth authorization server, no scopes, no `/.well-known/` documents on clarity.ms or clarity.microsoft.com.
- No first-party status page and no SLA.
- No published API versioning or deprecation policy, and no Sunset/Deprecation headers.
- No sandbox or test-mode credentials; there is a read-only public demo project instead.
- No REST endpoint for session recordings — that is MCP-and-dashboard only.