> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devhelm.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Uptime, downtime and incidents per component group and component over a date range

> Groups and components come in page order. The range is in UTC days, at most 366 days long, within the last 730 days and not in the future; it defaults to the last 30 days. The same report downloads as CSV or JSON from /export/reports.



## OpenAPI

````yaml /openapi/monitoring-api.json get /api/v1/status-pages/{id}/reports
openapi: 3.0.1
info:
  title: DevHelm API
  description: >-
    DevHelm monitoring and incident management API. Create and manage uptime
    monitors, incidents, alert channels, notification policies, and more.
  version: '1.0'
  contact:
    name: DevHelm
    url: https://devhelm.io
    email: support@devhelm.io
servers:
  - url: https://api.devhelm.io
    description: Production
security:
  - BearerAuth: []
tags:
  - name: Alert Channels
    description: Alert channel CRUD and connectivity testing
  - name: Alert Deliveries
    description: 'Delivery audit trail: inspect per-attempt details for alert deliveries'
  - name: API Auth
    description: Identity and quota info for API key authentication
  - name: API Keys
    description: Organization API key management
  - name: Artifacts
    description: Run evidence file content
  - name: Audit Log
    description: Organization audit trail
  - name: Bundles
    description: Upload code for browser and multi-step checks
  - name: Check Results
    description: Query raw check results, uptime statistics, and summary data
  - name: Dashboard
    description: Overview dashboard aggregates
  - name: Definitions
    description: Code-monitor definition catalog and revisions
  - name: Deploy Lock
    description: Mutex for CLI deploy operations
  - name: Device Login
    description: Device-code login that gives the CLI a named, revocable API key
  - name: Device Login
    description: Dashboard approval for CLI device-code logins
  - name: Email Testing
    description: Receive domains, captured mail, and JSON inject
  - name: Entitlements
    description: Plan entitlements and usage limits
  - name: Environments
    description: Variable namespace management for monitors
  - name: Forensics
    description: >-
      Detection engine event-sourced history (policy snapshots, rule
      evaluations, state transitions)
  - name: Heartbeat
    description: Public ping endpoint for heartbeat monitors
  - name: Incident Policies
    description: Manage trigger, confirmation, and recovery rules for monitors
  - name: Incidents
    description: Incident management and lifecycle
  - name: Integrations
    description: Static catalog of supported alert channel integrations
  - name: Invites
    description: Organization invite management
  - name: Maintenance Windows
    description: Schedule alert-suppression windows for monitors
  - name: Members
    description: Organization member management
  - name: Monitor Alert Channels
    description: Manage alert channel mappings for a monitor
  - name: Monitor Assertions
    description: Manage assertions for a monitor
  - name: Monitor Auth
    description: Manage authentication configuration for a monitor
  - name: Monitor definitions
    description: Publish, rollback, and revision history for code monitors
  - name: Monitor History
    description: Scheduled ticks that did not run
  - name: Monitor Runs
    description: Per-monitor code run history and run-now
  - name: Monitor secret requests
    description: Secret keys a monitor requires and how they are fulfilled
  - name: Monitor session
    description: Cached sign-in session for a monitor
  - name: Monitors
    description: Monitor CRUD and lifecycle management
  - name: Notification Dispatches
    description: >-
      Dispatch debugging API: inspect which policies matched an incident and
      track delivery status
  - name: Notification Policies
    description: Org-level notification routing policies with JSONB match rules
  - name: Notifications
    description: In-app notification center
  - name: Organizations
    description: Organization management
  - name: Regions
    description: Public regions
  - name: Resource Groups
    description: Resource group CRUD and member management
  - name: Revisions
    description: Definition revision packages
  - name: Runs
    description: Code-monitor run list, snapshot, cases, events, and cancel
  - name: Secrets
    description: Organization environment secret management
  - name: Sender Domains
    description: Custom domains for status page email
  - name: Service Subscriptions
    description: Manage which services an organization tracks
  - name: Status Data
    description: Public service status catalog, components, uptime, and incident history
  - name: Status Pages
    description: Status page management
  - name: Synthetics metrics
    description: Measured metrics for the BROWSER and MULTI_STEP_API family
  - name: Tags
    description: Org-scoped tag management for monitors
  - name: Vault
    description: Organization vault management (admin-only)
  - name: Webhook Testing
    description: Inboxes that capture inbound HTTP and wait for events
  - name: Webhooks
    description: Webhook endpoint management, event catalog, and delivery history
  - name: Workspaces
    description: Workspace management within an organization
paths:
  /api/v1/status-pages/{id}/reports:
    get:
      tags:
        - status-page-report-controller
      summary: >-
        Uptime, downtime and incidents per component group and component over a
        date range
      description: >-
        Groups and components come in page order. The range is in UTC days, at
        most 366 days long, within the last 730 days and not in the future; it
        defaults to the last 30 days. The same report downloads as CSV or JSON
        from /export/reports.
      operationId: getStatusPageReport
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: from
          in: query
          description: First day of the range (UTC), e.g. 2026-10-01; set with to
          required: false
          schema:
            type: string
            format: date
        - name: to
          in: query
          description: Last day of the range (UTC), e.g. 2026-10-31; set with from
          required: false
          schema:
            type: string
            format: date
        - name: X-DevHelm-Client
          in: header
          description: Calling surface and version, e.g. cli/1.4.0 or sdk-js/2.0.0
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/SingleValueResponseStatusPageReportDto'
        '400':
          description: Bad request — the payload failed validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required — the plan or quota does not allow this
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden — the actor lacks permission for this resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found — the requested resource does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict — the request collides with current resource state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '410':
          description: Gone — the resource is no longer available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests — retry after the window resets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error — see the message field for details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Bad gateway — an upstream provider returned an error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable — try again shortly
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    SingleValueResponseStatusPageReportDto:
      required:
        - data
      type: object
      properties:
        data:
          $ref: '#/components/schemas/StatusPageReportDto'
    ErrorResponse:
      required:
        - category
        - code
        - message
        - status
        - timestamp
        - retryable
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code (mirrors the response status line)
          format: int32
          example: 404
        code:
          type: string
          description: >-
            Stable machine code for this error, such as NOT_FOUND or
            SYNTHETICS_USAGE_CAPPED
          example: NOT_FOUND
        category:
          $ref: '#/components/schemas/ErrorCategory'
        retryable:
          type: boolean
          description: Whether a later attempt can succeed without changing the request
          example: false
        message:
          type: string
          description: Human-readable error message; safe to surface to end users
          example: Monitor not found
        timestamp:
          type: integer
          description: Server time when the error was produced (epoch milliseconds)
          format: int64
          example: 1737302400000
        requestId:
          type: string
          description: >-
            Opaque per-request id; same value as the X-Request-Id response
            header. Use in support tickets.
          nullable: true
          example: 5b6f7a8c-1234-4d5e-9f0a-1b2c3d4e5f6a
        errors:
          type: array
          description: >-
            Structured per-field rejections; populated for validation errors,
            null otherwise
          nullable: true
          items:
            nullable: true
            allOf:
              - $ref: '#/components/schemas/ErrorEntry'
        retryAfterSeconds:
          type: integer
          description: Seconds to wait before retrying a rate limit
          format: int64
          nullable: true
          example: 30
        resource:
          type: string
          description: Meter or resource this limit applies to
          nullable: true
          example: browser_runs
        used:
          type: integer
          description: Amount used in the current period
          format: int64
          nullable: true
          example: 1000
        limit:
          type: integer
          description: Maximum allowed for this period or plan
          format: int64
          nullable: true
          example: 1000
        resetsAt:
          type: string
          description: When this quota window resumes (ISO-8601)
          nullable: true
          example: '2026-11-01T00:00:00Z'
        plan:
          type: string
          description: Plan this refusal was evaluated against
          nullable: true
          example: FREE
        upgradeUrl:
          type: string
          description: Page where an admin can change the plan
          nullable: true
          example: https://app.devhelm.io/settings/billing
        canRaise:
          type: string
          description: Role that can raise this limit
          nullable: true
          example: org admin
        owner:
          type: string
          description: Who owns the resource when a write is refused
          nullable: true
        required:
          type: string
          description: Missing scope, secret key, or other required value
          nullable: true
        have:
          type: integer
          description: Current amount compared with the plan limit
          format: int64
          nullable: true
          example: 10
        reason:
          type: string
          description: Why this was refused, such as scope, role, or no_route
          nullable: true
          example: no_route
        next:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/ErrorNext'
        details:
          type: object
          additionalProperties:
            type: object
            description: >-
              Extra fields for this error, such as a missing secret key and
              environment
            nullable: true
          description: >-
            Extra fields for this error, such as a missing secret key and
            environment
          nullable: true
        expiredAt:
          type: string
          description: When this evidence expired
          format: date-time
          nullable: true
        policy:
          type: string
          description: Retention written when the artifact was saved, such as P7D
          nullable: true
      description: Uniform error envelope returned for every non-2xx response
      example:
        status: 404
        code: NOT_FOUND
        category: not_found
        message: Monitor not found
        timestamp: 1737302400000
        requestId: 5b6f7a8c-1234-4d5e-9f0a-1b2c3d4e5f6a
    StatusPageReportDto:
      required:
        - components
        - from
        - groups
        - incidents
        - to
      type: object
      properties:
        from:
          type: string
          description: First day of the range (UTC)
          format: date
        to:
          type: string
          description: Last day of the range (UTC)
          format: date
        groups:
          type: array
          description: Component groups of the page, in page order
          items:
            $ref: '#/components/schemas/StatusPageReportGroupDto'
        components:
          type: array
          description: >-
            Every component of the page in page order, each group's members
            after it
          items:
            $ref: '#/components/schemas/StatusPageReportComponentDto'
        incidents:
          type: array
          description: >-
            Published incidents (not maintenance) that overlap the range, oldest
            first
          items:
            $ref: '#/components/schemas/StatusPageReportIncidentDto'
      description: >-
        Uptime and incidents per component group and component over a date range
        (UTC days)
    ErrorCategory:
      type: string
      description: Machine class clients use to choose the next action
      enum:
        - validation
        - blocked
        - auth
        - permission
        - ownership
        - plan
        - quota
        - rate_limit
        - conflict
        - confirmation_required
        - not_found
        - gone
        - platform
    ErrorEntry:
      required:
        - code
        - message
      type: object
      properties:
        code:
          minLength: 1
          type: string
          description: >-
            Stable machine-readable code; see ValidationErrorCode for the
            registry
          example: MONITOR_HEARTBEAT_GRACE_EXCEEDS_INTERVAL
        field:
          type: string
          description: >-
            JSON-pointer-like path to the offending field, or null for
            request-wide errors
          nullable: true
          example: config.gracePeriod
        message:
          minLength: 1
          type: string
          description: Human-readable message; safe to surface to end users
      description: One structured validation rejection
    ErrorNext:
      type: object
      properties:
        command:
          type: string
          description: Command that fixes this error
          nullable: true
          example: devhelm account usage
        docs:
          type: string
          description: Documentation page for this error
          nullable: true
          example: https://docs.devhelm.io/errors/SYNTHETICS_USAGE_CAPPED
      description: Command and documentation that fix this error
    StatusPageReportGroupDto:
      required:
        - componentIds
        - id
        - incidentIds
        - name
        - trackedDays
        - downtimeMinutes
        - majorOutageMinutes
        - partialOutageMinutes
        - incidentCount
      type: object
      properties:
        id:
          type: string
          description: Component group id
          format: uuid
        name:
          minLength: 1
          type: string
          description: Component group name
        componentIds:
          type: array
          description: Ids of the group's components, in page order
          items:
            type: string
            description: Ids of the group's components, in page order
            format: uuid
        uptimePercentage:
          type: number
          description: >-
            Group uptime percentage, as the public page shows it; null when no
            day was tracked
          format: double
          nullable: true
        trackedDays:
          type: integer
          description: >-
            Days in the range the group was tracked, including today's partial
            day
          format: int32
        downtimeMinutes:
          type: integer
          description: >-
            Outage minutes weighted like uptime: major outage in full, partial
            outage at 30%
          format: int64
        majorOutageMinutes:
          type: integer
          description: Minutes of major outage in the range
          format: int64
        partialOutageMinutes:
          type: integer
          description: Minutes of partial outage in the range
          format: int64
        incidentCount:
          type: integer
          description: >-
            Published incidents in the range that affected the group's
            components
          format: int32
        incidentIds:
          type: array
          description: >-
            Ids of those incidents, oldest first, as listed in the report's
            incidents
          items:
            type: string
            description: >-
              Ids of those incidents, oldest first, as listed in the report's
              incidents
            format: uuid
      description: >-
        Uptime, downtime and incidents of one component group over the report's
        range
    StatusPageReportComponentDto:
      required:
        - id
        - incidentIds
        - name
        - trackedDays
        - downtimeMinutes
        - majorOutageMinutes
        - partialOutageMinutes
        - incidentCount
      type: object
      properties:
        id:
          type: string
          description: Component id
          format: uuid
        name:
          minLength: 1
          type: string
          description: Component name
        groupId:
          type: string
          description: Group the component belongs to; null when ungrouped
          format: uuid
          nullable: true
        uptimePercentage:
          type: number
          description: >-
            Mean daily uptime percentage over the tracked days; null when no day
            was tracked
          format: double
          nullable: true
        trackedDays:
          type: integer
          description: >-
            Days in the range the component was tracked, including today's
            partial day
          format: int32
        downtimeMinutes:
          type: integer
          description: >-
            Outage minutes weighted like uptime: major outage in full, partial
            outage at 30%
          format: int64
        majorOutageMinutes:
          type: integer
          description: Minutes of major outage in the range
          format: int64
        partialOutageMinutes:
          type: integer
          description: Minutes of partial outage in the range
          format: int64
        incidentCount:
          type: integer
          description: Published incidents in the range that affected the component
          format: int32
        incidentIds:
          type: array
          description: >-
            Ids of those incidents, oldest first, as listed in the report's
            incidents
          items:
            type: string
            description: >-
              Ids of those incidents, oldest first, as listed in the report's
              incidents
            format: uuid
      description: Uptime, downtime and incidents of one component over the report's range
    StatusPageReportIncidentDto:
      required:
        - componentIds
        - id
        - impact
        - startedAt
        - status
        - title
      type: object
      properties:
        id:
          type: string
          description: Incident id
          format: uuid
        title:
          minLength: 1
          type: string
          description: Incident title
        impact:
          type: string
          description: Incident impact
          enum:
            - NONE
            - MINOR
            - MAJOR
            - CRITICAL
        status:
          type: string
          description: Current incident status
          enum:
            - INVESTIGATING
            - IDENTIFIED
            - MONITORING
            - RESOLVED
        startedAt:
          type: string
          description: When the incident started
          format: date-time
        resolvedAt:
          type: string
          description: When the incident was resolved; null while it is open
          format: date-time
          nullable: true
        componentIds:
          type: array
          description: Ids of the components the incident affected
          items:
            type: string
            description: Ids of the components the incident affected
            format: uuid
      description: A published incident that overlaps the report's range
  securitySchemes:
    BearerAuth:
      type: http
      description: API key (dh_live_...) or Auth0 JWT token
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.