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

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:

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:

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

[
    {
     "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

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