Exit1.dev History API

openapi: 3.2.0
info:
  title: exit1.dev History 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: History
paths:
  /v1/public/checks/{id}/history:
    get:
      operationId: getCheckHistory
      summary: Check history
      description: Retrieve the execution history for a specific check, newest first.
      tags:
      - History
      parameters:
      - $ref: '#/components/parameters/CheckId'
      - name: limit
        in: query
        description: Number of results per page (max 200)
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 25
      - name: page
        in: query
        description: Page number
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: from
        in: query
        description: Only results at or after this time. ISO 8601 or a Unix timestamp in seconds or milliseconds.
        schema:
          type: string
      - name: to
        in: query
        description: Only results at or before this time. ISO 8601 or a Unix timestamp in seconds or milliseconds.
        schema:
          type: string
      - name: status
        in: query
        description: Only results with this exact status (for example online, offline, degraded, disabled). Defaults to all.
        schema:
          type: string
          default: all
      - name: q
        in: query
        description: Case-sensitive substring match against the error message and status
        schema:
          type: string
      responses:
        '200':
          description: Check history entries
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/HistoryEntry'
                  meta:
                    $ref: '#/components/schemas/HistoryMeta'
        '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:
  schemas:
    HistoryEntry:
      type: object
      description: Optional fields are omitted rather than sent as null.
      required:
      - id
      - checkId
      - websiteId
      - timestamp
      - status
      - createdAt
      properties:
        id:
          type: string
          example: hist_001
        checkId:
          type: string
          example: abc123
        websiteId:
          type: string
          deprecated: true
          description: Same value as checkId
          example: abc123
        timestamp:
          type: integer
          description: Epoch ms when the check ran
          example: 1736951400000
        status:
          type: string
          description: Result status, for example online, offline, degraded or disabled
          example: online
        responseTime:
          type: number
          description: Response time in ms
          example: 245
        statusCode:
          type: integer
          example: 200
        error:
          type: string
        redirectLocation:
          type: string
        createdAt:
          type: integer
          description: Same value as timestamp
          example: 1736951400000
    HistoryMeta:
      type: object
      properties:
        page:
          type: integer
          example: 1
        limit:
          type: integer
          example: 25
        total:
          type: 'null'
        totalPages:
          type: 'null'
        hasNext:
          type: boolean
        hasPrev:
          type: boolean
    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)
  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
  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.

        '