openapi: 3.1.0
info:
  title: Microsoft Clarity Data Export 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:
  securitySchemes:
    bearer_token:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: API access token generated by the project admin from the Clarity settings page
  schemas:
    MetricEntry:
      type: object
      properties:
        metricName:
          type: string
          example: Traffic
        information:
          type: array
          items:
            type: object
            additionalProperties: true