openapi: 3.1.0
info:
  title: Microsoft Clarity Data Export DataExport API
  description: 'The Microsoft Clarity Data Export API lets project admins download

    dashboard insights programmatically. Returns JSON for the last 1-3

    days, broken down by up to three dimensions (Browser, Device,

    Country/Region, OS, Source, Medium, Campaign, Channel, URL).

    Authentication is via a Bearer JWT API token generated in the

    Clarity project settings. Max 10 requests per project per day;

    responses limited to 1000 rows and not paginated.

    '
  version: v1
  contact:
    name: Kin Lane
    email: kin@apievangelist.com
  license:
    name: Microsoft Terms of Use
    url: https://www.microsoft.com/en-us/legal/terms-of-use
servers:
- url: https://www.clarity.ms
  description: Microsoft Clarity production
security:
- bearer_token: []
tags:
- name: DataExport
  description: Project live insights data export
paths:
  /export-data/api/v1/project-live-insights:
    get:
      tags:
      - DataExport
      summary: Fetch project live insights
      description: 'Fetches dashboard data for a Clarity project over the last 1, 2,

        or 3 days, broken down by up to three dimensions. Returns

        metrics including Traffic, Engagement Time, Scroll Depth,

        Popular Pages, Browser, Device, OS, Country/Region, Page Title,

        Referrer URL, Dead Click Count, Excessive Scroll, Rage Click

        Count, Quickback Click, Script Error Count, and Error Click

        Count.

        '
      operationId: getProjectLiveInsights
      parameters:
      - name: numOfDays
        in: query
        required: true
        description: Number of days for export (1, 2, or 3)
        schema:
          type: integer
          enum:
          - 1
          - 2
          - 3
      - name: dimension1
        in: query
        schema:
          type: string
          enum:
          - Browser
          - Device
          - Country/Region
          - OS
          - Source
          - Medium
          - Campaign
          - Channel
          - URL
      - name: dimension2
        in: query
        schema:
          type: string
          enum:
          - Browser
          - Device
          - Country/Region
          - OS
          - Source
          - Medium
          - Campaign
          - Channel
          - URL
      - name: dimension3
        in: query
        schema:
          type: string
          enum:
          - Browser
          - Device
          - Country/Region
          - OS
          - Source
          - Medium
          - Campaign
          - Channel
          - URL
      responses:
        '200':
          description: Insights data
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MetricEntry'
        '400':
          description: Bad request - invalid request parameters
        '401':
          description: Unauthorized - missing, invalid, or expired token
        '403':
          description: Forbidden - token not authorized for operation
        '429':
          description: Too Many Requests - exceeded daily limit (10/project/day)
components:
  schemas:
    MetricEntry:
      type: object
      properties:
        metricName:
          type: string
          example: Traffic
        information:
          type: array
          items:
            type: object
            additionalProperties: true
  securitySchemes:
    bearer_token:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: API access token generated by the project admin from the Clarity settings page