openapi: 3.1.0
info:
  title: Checkly Public Accounts Analytics API
  version: v1
  description: The Checkly Public API allows you to programmatically manage your monitoring checks, alerts, and more. If you have any questions, please do not hesitate to get in touch with us.
  contact:
    name: Checkly Support
    url: https://checklyhq.com/support
  license:
    name: MIT
servers:
- url: https://api.checklyhq.com
  description: Production server
security:
- bearerAuth: []
  accountId: []
tags:
- name: Analytics
paths:
  /v1/analytics/api-checks/{id}:
    get:
      summary: Get API Check Analytics
      description: Get analytics data for API checks
      operationId: getApiCheckAnalytics
      parameters:
      - name: id
        in: path
        required: true
        description: The check ID
        schema:
          type: string
      responses:
        '200':
          description: API check analytics data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiCheckAnalytics'
      tags:
      - Analytics
  /v1/analytics/browser-checks/{id}:
    get:
      summary: Get Browser Check Analytics
      description: Get analytics data for browser checks
      operationId: getBrowserCheckAnalytics
      parameters:
      - name: id
        in: path
        required: true
        description: The check ID
        schema:
          type: string
      responses:
        '200':
          description: Browser check analytics data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrowserCheckAnalytics'
      tags:
      - Analytics
  /v1/analytics/metrics/{checkType}:
    get:
      summary: List Analytics Metrics
      description: Returns all the available metrics for a specific check-type (API, URL, TCP or BROWSER)
      operationId: listAnalyticsMetrics
      parameters:
      - name: checkType
        in: path
        required: true
        description: The check type to retrieve metrics for
        schema:
          type: string
          enum:
          - api
          - url
          - tcp
          - browser
          - heartbeat
          - multistep
      - name: category
        in: query
        description: Filter by metric category
        schema:
          type: string
          enum:
          - response_time
          - success_rate
          - core_web_vitals
          - heartbeat
          - performance
          - volume
      - name: includeThresholds
        in: query
        description: Include performance thresholds and benchmarks
        schema:
          type: boolean
          default: false
      - name: format
        in: query
        description: Response format
        schema:
          type: string
          enum:
          - detailed
          - summary
          default: detailed
      - name: includeExamples
        in: query
        description: Include example values and use cases
        schema:
          type: boolean
          default: false
      - name: includeCalculations
        in: query
        description: Include calculation method details
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: List of available metrics for the specified check type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricsList'
        '400':
          description: Bad Request - Invalid check type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Analytics
components:
  schemas:
    Error:
      type: object
      required:
      - error
      - message
      properties:
        error:
          type: string
          description: Error type
        message:
          type: string
          description: Error message
        statusCode:
          type: integer
          description: HTTP status code
    BrowserCheckAnalytics:
      type: object
      properties:
        id:
          type: string
          description: Check ID
        averageLoadTime:
          type: number
          description: Average page load time in milliseconds
        successRate:
          type: number
          description: Success rate percentage
        totalRuns:
          type: integer
          description: Total number of runs
    ApiCheckAnalytics:
      type: object
      properties:
        id:
          type: string
          description: Check ID
        averageResponseTime:
          type: number
          description: Average response time in milliseconds
        successRate:
          type: number
          description: Success rate percentage
        totalRequests:
          type: integer
          description: Total number of requests
    Metric:
      type: object
      properties:
        name:
          type: string
          description: Metric identifier name
        displayName:
          type: string
          description: Human-readable metric name
        description:
          type: string
          description: Detailed description of what the metric measures
        unit:
          type: string
          description: Unit of measurement (milliseconds, percentage, count, etc.)
        dataType:
          type: string
          enum:
          - number
          - integer
          description: Data type of the metric value
        availableFor:
          type: array
          items:
            type: string
          description: Check types this metric is available for
        calculationMethod:
          type: string
          description: How the metric is calculated
        precision:
          type: integer
          description: Number of decimal places for precision
        category:
          type: string
          description: Metric category grouping
        goodThreshold:
          type: number
          description: Threshold value considered good performance
        needsImprovementThreshold:
          type: number
          description: Threshold value that needs improvement
        range:
          type: object
          properties:
            min:
              type: number
              description: Minimum possible value
            max:
              type: number
              description: Maximum possible value
    MetricsList:
      type: object
      properties:
        data:
          type: object
          properties:
            responseTimeMetrics:
              type: array
              items:
                $ref: '#/components/schemas/Metric'
            successMetrics:
              type: array
              items:
                $ref: '#/components/schemas/Metric'
            volumeMetrics:
              type: array
              items:
                $ref: '#/components/schemas/Metric'
            browserSpecificMetrics:
              type: array
              items:
                $ref: '#/components/schemas/Metric'
            heartbeatSpecificMetrics:
              type: array
              items:
                $ref: '#/components/schemas/Metric'
        meta:
          type: object
          properties:
            totalMetrics:
              type: integer
              description: Total number of metrics available
            categories:
              type: array
              items:
                type: string
              description: Available metric categories
            checkTypes:
              type: array
              items:
                type: string
              description: Supported check types
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API Key authentication for Checkly API. You can get your API key at https://app.checklyhq.com/settings/user/api-keys
    accountId:
      type: apiKey
      in: header
      name: X-Checkly-Account
      description: Your Checkly account ID. You can find it at https://app.checklyhq.com/settings/account/general