Exit1.dev Statistics API

openapi: 3.2.0
info:
  title: exit1.dev Statistics API
  description: 'The exit1.dev API provides programmatic access to your website monitoring data.


    This file covers the read endpoints. Write endpoints (create, update,

    delete, toggle) are documented at https://docs.exit1.dev/api-reference.


    ## Authentication

    All requests must include an `X-Api-Key` header with a valid API key.

    API access is available on all plans.


    ## Timestamps

    All timestamps in responses are Unix epoch milliseconds.


    ## Rate Limits (API keys)

    - Pre-authentication: 20 requests/minute per IP

    - Per API key: 5 requests/minute

    - Per endpoint per key: 1 request/minute

    - Daily per key: 500 requests

    - Daily per user: 2,000 requests


    `GET /v1/public/checks/status` has its own limits (6/minute per key,

    12/minute per user) and does not count toward the ones above.'
  version: 1.2.0
  contact:
    name: exit1.dev Support
    url: https://exit1.dev
    email: connect@exit1.dev
servers:
- url: https://us-central1-exit1-dev.cloudfunctions.net/publicApi
  description: Production API
security:
- ApiKeyAuth: []
tags:
- name: Statistics
paths:
  /v1/public/checks/{id}/stats:
    get:
      operationId: getCheckStats
      summary: Check stats
      description: 'Retrieve uptime statistics for a specific check.


        Single-range mode (default) uses `from` and `to`. The window never

        starts more than 90 days before now; omitting `from` means 90 days ago.


        Multi-range mode uses `ranges` and returns an object keyed by range

        name, each value having the Stats shape. `from` is ignored in this mode.'
      tags:
      - Statistics
      parameters:
      - $ref: '#/components/parameters/CheckId'
      - name: from
        in: query
        description: Start of the window (single-range mode). ISO 8601 or Unix timestamp. Defaults to 90 days ago and is clamped to at most 90 days ago.
        schema:
          type: string
      - name: to
        in: query
        description: End of the window. ISO 8601 or Unix timestamp. Defaults to now.
        schema:
          type: string
      - name: ranges
        in: query
        description: Comma-separated predefined ranges (max 5). Allowed values are 1h, 6h, 1d, 7d, 30d, 60d, 90d.
        schema:
          type: string
          example: 1d,7d,30d
      responses:
        '200':
          description: Uptime statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    oneOf:
                    - $ref: '#/components/schemas/Stats'
                    - type: object
                      description: Multi-range result keyed by range name
                      additionalProperties:
                        $ref: '#/components/schemas/Stats'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  headers:
    Retry-After:
      description: Seconds to wait before retrying (429 responses only)
      schema:
        type: integer
    RateLimit-Limit:
      description: Maximum requests allowed in the current window
      schema:
        type: integer
    RateLimit-Remaining:
      description: Requests remaining in the current window
      schema:
        type: integer
    RateLimit-Reset:
      description: Seconds until the current window resets
      schema:
        type: integer
    RateLimit:
      description: Combined form, for example "limit=1, remaining=0, reset=42"
      schema:
        type: string
  parameters:
    CheckId:
      name: id
      in: path
      required: true
      description: The unique check identifier (letters, digits, - and _, max 128 characters)
      schema:
        type: string
  responses:
    BadRequest:
      description: Invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Invalid check ID format
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Not found
    RateLimited:
      description: Rate limit exceeded
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Rate limit exceeded. Please try again later.
            retryAfter: 42
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Internal error
    Forbidden:
      description: Missing scope, or the check belongs to another account
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: 'Credential does not have the required scope: checks:read'
    Unauthorized:
      description: Missing, invalid or disabled credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Invalid API key
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Human-readable error message
        retryAfter:
          type: integer
          description: Seconds to wait before retrying (429 responses)
        quotaLimit:
          type: integer
          description: Daily request quota (daily-quota 429 responses only)
        quotaReset:
          type: integer
          description: Epoch ms when the daily quota resets (daily-quota 429 responses only)
    Stats:
      type: object
      properties:
        totalChecks:
          type: integer
          example: 720
        onlineChecks:
          type: integer
          example: 714
        offlineChecks:
          type: integer
          description: Confirmed offline results outside maintenance
          example: 6
        uptimePercentage:
          type: number
          description: onlineDurationMs / totalDurationMs * 100, or 0 when there is no data
          example: 97.5
        totalDurationMs:
          type: integer
          example: 86400000
        onlineDurationMs:
          type: integer
          example: 84240000
        offlineDurationMs:
          type: integer
          example: 2160000
        responseSampleCount:
          type: integer
          example: 714
        avgResponseTime:
          type: number
          example: 245.1
        minResponseTime:
          type: number
          example: 120
        maxResponseTime:
          type: number
          example: 890
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: 'API key for authentication. Create keys at Settings > API.

        Format: `ek_live_<64 hex characters>`

        A key can carry an expiry (401 "API key expired" afterwards) and can be

        restricted to specific checks and/or folders (subfolders included).

        A restricted key only lists its own checks and gets 404 for others.

        '