Clarity Data Export API

The Microsoft Clarity Data Export API enables users to download their dashboard data programmatically, facilitating advanced data analysis, and system integration. This guide provides essential information for effective API use.

Getting started

Prerequisites

• An active Microsoft Clarity account. Learn how to sign up for Clarity.
• An API access token generated by the project's admin from the settings page.
• Familiarity with RESTful APIs and the JSON data format.

Authentication

Access to the API is secured via JWT tokens. Include the token in the request header as follows:

Authorization: Bearer <Your_API_Token>

Obtaining access tokens

Note

Only project admins can manage access tokens.

1. Go to your Clarity project. Select Settings -> Data Export -> Generate new API token.

   

2. Provide a descriptive name for the token for easy identification.

   

   Note

   Token Name Requirements:

   Length Constraints:

   • Minimum Length: Each token name must be at least 4 characters long.
   • Maximum Length: Token names should not exceed 32 characters.

   Allowed Characters:

   • Alphanumeric Characters: Tokens can include any upper case (A-Z) and lower case (a-z) letters, as well as numbers (0-9).
   • Special Characters: For better readability and separation, hyphens (-), underscores (_), and periods (.) are permitted.

   Disallowed Characters:

   • Spaces: Token names should not contain spaces.
   • Restricted Special Characters: Avoid using special characters such as @, #, $, %, &, *, ! as they are not allowed.

   Uniqueness:

   Each token name must be unique within a project. This requirement ensures that every token can be easily identified and managed within its respective project environment.

3. Copy and save the generated token securely for future reference.

   

API endpoint

   GET https://www.clarity.ms/export-data/api/v1/project-live-insights

Fetches the dashboard data structured in JSON format over a specified date range and can break down insights by up to three dimensions.

Parameters

• numOfDays: (1, 2, or 3) The number of days for the data export since the API call, relating to the last 24, 48, or 72 hours, respectively.
• dimension1: The first dimensions to break down insights.
• dimension2: The second dimensions to break down insights.
• dimension3: The third dimensions to break down insights.

Dimensions and metrics

Possible dimensions:

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

Metrics:

• 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

Example requests

cURL

Following is an example command-line request:

Note

Replace YOUR _TOKEN with the actual token.

curl --location 'https://www.clarity.ms/export-data/api/v1/project-live-insights?\numOfDays=1&dimension1=OS' 
--header 'Content-Type: application/json' 
--header 'Authorization: Bearer YOUR_TOKEN'

Python

Following is a python example request:

Note

Replace YOUR _TOKEN with the actual token.

import requests

params = {"numOfDays": "1", "dimension1": "OS"}
headers = {
   "Authorization": "Bearer YOUR_TOKEN",
   "Content-type": "application/json"
}
response = requests.get("https://www.clarity.ms/export-data/api/v1/project-live-insights",
   params=params,
   headers=headers,
)

print(response.json())

Sample response

Note

• Additional metrics and dimensions may be included in the full API response.
• The API returns results in UTC timezone.

[
    {
     "metricName": "Traffic",
     "information": [
      {
        "totalSessionCount": "9554",
        "totalBotSessionCount": "8369",
        "distantUserCount": "189733",
        "PagesPerSessionPercentage": 1.0931,
        "OS": "Other"
      },
      {
        "totalSessionCount": "291942",
        "totalBotSessionCount": "31076",
        "distantUserCount": "212836",
        "PagesPerSessionPercentage": 2.2609,
        "OS": "Android"
      }
      // Additional data points may be included in the full response. 
      ]
    }
 ]

Possible response errors

Code	Response	Message	Possible Reasons
401	Unauthorized	-	Missing, invalid, or expired token
403	Forbidden	-	Token not authorized for operation
400	BadRequest	-	Invalid request parameters
429	TooManyRequests	Exceeded daily limit	Surpassing the daily request limit

Limitations and usage quotas

• Maximum of 10 API requests are allowed per project per day.
• Data retrieval is confined to the previous 1 to 3 days.
• Maximum of three dimensions can be passed in a single request.
• The response is limited to 1,000 rows and can't be paginated.

Best practices

• Protect and securely store API tokens.

• Anticipate and manage rate limit errors.

• Comply with data protection regulations while managing data.

• To ensure security, promptly replace API tokens if a user with access is removed from the project.

  

• Contact Microsoft Clarity support for further assistance.

Visit Clarity

Case studies

Demo

Sign in

Blog

Benchmarks