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

# List Monitoring Alerts

> Retrieve a paginated list of monitoring alerts for failed monitorings.

## Overview

Retrieve a paginated list of monitoring alerts for the failed monitoring runs. Supports filtering by seen/unseen status and execution time, and provides an unseen alert count.

## Request

* **Method**: `GET`
* **Path**: `/monitoring-alerts`
* **Query Parameters**: Optional filters and pagination

### Query Parameters

* `page_size` (integer, optional) - Number of alerts per page
  * Default: 10
  * Range: 1-100
  * Must be a positive integer
* `next_token` (string, optional) - Pagination token for next page
* `only_unacknowledged` (boolean, optional) - If true, returns only unacknowledged alerts
* `acknowledged` (boolean, optional) - If true, returns only acknowledged alerts
* `execution_time_before` (ISO8601 string, optional) - Only include alerts executed before this time
* `execution_time_after` (ISO8601 string, optional) - Only include alerts executed after this time

### Example Request

```
GET /monitoring-alerts?page_size=20&only_unacknowledged=true
```

## Success Response

* **Status**: 200 OK

### Response Body

* `items` (array) - List of alert objects
  * `id` (string) - Unique identifier for the alert
  * `monitoring_id` (string) - ID of the monitoring that triggered this alert
  * `customer_id` (string) - ID of the customer that owns this monitoring
  * `execution_result_id` (string) - ID of the execution result
  * `website` (string) - URL of the monitored website
  * `failed_checks` (array) - List of checks that failed
    * `check` (string) - The type of check that failed
    * `explanation` (string) - Explanation of the failure
    * `method_used` (string) - Method used for checking
    * `status` (string) - Status of the check
  * `execution_time` (string) - ISO8601 timestamp of when the monitoring was executed
  * `created_at` (string) - ISO8601 timestamp of when the alert was created
  * `acknowledged_at` (string|null) - ISO8601 timestamp of when the alert was acknowledged, or null if not acknowledged
  * `external_id` (string, optional) - External reference ID
* `unacknowledged_count` (integer) - Number of unacknowledged alerts for the customer
* `next_token` (string|null) - Token for next page (null if no more pages)

### Example Response

```json theme={null}
{
  "items": [
    {
      "id": "532ebbd3-269d-4c8f-b73b-2269eb83f1ae",
      "monitoring_id": "c3853e7e-46dc-4c1f-afb4-028b3bdfce19",
      "customer_id": "69df5d81-2b74-4f42-a401-13eb96ba0619",
      "execution_result_id": "e79a2fe0-041f-4357-8b3b-43aa8410ab0b",
      "website": "https://dokanstore-sa.com/",
      "failed_checks": [
        {
          "check": "non_operational_website",
          "explanation": "No Website Data found",
          "method_used": "",
          "status": "FAILED"
        }
      ],
      "execution_time": "2025-06-20T18:25:51.409Z",
      "created_at": "2025-06-20T20:45:48.460Z",
      "acknowledged_at": null,
      "external_id": "cb7f0fab-38b7-4043-bd7f-5976ed4b5e19"
    },
    {
      "id": "f085ca1e-8079-4a6c-8b1d-c17796c0aff5",
      "monitoring_id": "288888fc-b5b4-4131-bac8-d45c33e9e32b",
      "customer_id": "69df5d81-2b74-4f42-a401-13eb96ba0619",
      "execution_result_id": "bccc5556-96bf-492a-aa69-09a1faefed15",
      "website": "https://example-02.com/",
      "failed_checks": [
        {
          "check": "non_operational_website",
          "explanation": "No Website Data found",
          "method_used": "",
          "status": "FAILED"
        }
      ],
      "execution_time": "2025-06-20T18:25:45.215Z",
      "created_at": "2025-06-20T20:45:48.460Z",
      "acknowledged_at": null,
      "external_id": "cb7f0fab-38b7-4043-bd7f-5976ed4b5e19"
    }
  ],
  "unacknowledged_count": 2,
  "next_token": null
}
```

## Error Handling

* **400 Bad Request**
  * Invalid query parameter values
  * Example: `{ "error": "page_size must be a positive integer between 1 and 100" }`
* **401 Unauthorized**
  * Missing or invalid customer authentication
* **500 Internal Server Error**
  * Unexpected server error

## Pagination

The API uses cursor-based pagination with Base64-encoded tokens:

1. First request: Don't include `next_token`
2. Subsequent requests: Use the `next_token` from the previous response
3. Last page: `next_token` will be `null`


## OpenAPI

````yaml GET /monitoring-alerts
openapi: 3.0.1
info:
  version: 1.5.0
  title: Diligent
  description: >
    Download Postman collection
    [here](https://docs.godiligent.ai/files/postman_collection.json).
servers:
  - url: https://api.godiligent.ai
    description: Production
  - url: https://api.sandbox.godiligent.ai
    description: Sandbox
security:
  - xApiKey: []
tags:
  - name: CDD
    description: Customer Due Diligence
  - name: Company
    description: Company Information
  - name: Blocked Companies
    description: Manage blocked companies
  - name: Monitorings
    description: Website monitoring and alerts for changes and risks
  - name: Webhooks
    description: >

      ## How to Secure Webhook Deliveries

      To ensure that webhook payloads are securely transmitted and verified.
      This guide explains how to configure and validate

      webhook deliveries using a shared secret.


      ### How It Works


      When setting up a webhook, a secret is configured on both the sender (our
      system) and the receiver (your endpoint). Each

      webhook payload is signed using this secret, allowing the receiver to
      verify its authenticity.


      #### Step 1: Configuring Your Webhook Secret


      1. When creating a webhook in our system, specify a unique secret key.
      This secret should be a strong, randomly

      generated string.

      2. Store this secret securely on your server; it should never be exposed
      publicly.


      #### Step 2: Receiving Webhook Payloads


      When your server receives a webhook event, the request will include an
      `X-Signature` header containing a HMAC signature

      of the payload.


      Example header:


      ```

      X-Signature: sha256=abcdef1234567890...

      ```


      #### Step 3: Validating the Webhook Signature


      To verify the webhook payload:


      1. Retrieve the `X-Signature` value from the request headers.

      2. Compute the HMAC SHA-256 signature of the request payload using your
      webhook secret.

      3. Compare the computed signature with the one in the `X-Signature`
      header.

      4. If they match, the webhook is valid.


      #### (Python)


      ```python

      import hashlib

      import hmac

      import json


      def verify_webhook_signature(secret, payload, signature):
        computed_signature = hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest()
        expected_signature = f"sha256={computed_signature}"
        return hmac.compare_digest(expected_signature, signature)

      # Example usage:

      secret = "your_webhook_secret"

      payload = json.dumps({"event": "example"})

      received_signature = "sha256=abcdef1234567890..."


      if verify_webhook_signature(secret, payload, received_signature):
        print("Valid webhook received!")
      else:
        print("Invalid webhook signature!")
      ```


      #### (JavaScript)


      ```javascript

      const crypto = require('crypto');


      function verifyWebhookSignature (secret, payload, signature) {

      const computedSignature = `sha256=${crypto.createHmac('sha256', secret)

      .update(payload)

      .digest('hex')}`;

      return crypto.timingSafeEqual(Buffer.from(computedSignature),
      Buffer.from(signature));

      }


      // Example usage:

      const secret = "your_webhook_secret";

      const payload = JSON.stringify({ event: "example" });

      const receivedSignature = "sha256=abcdef1234567890...";


      if (verifyWebhookSignature(secret, payload, receivedSignature)) {

      console.log("Valid webhook received!");

      } else {

      console.log("Invalid webhook signature!");

      }

      ```


      #### Security Considerations


      - Always use HTTPS to prevent interception of webhook payloads.

      - Reject webhook requests that fail signature validation.

      - Rotate secrets periodically to enhance security.


      By following this guide, you ensure that webhook deliveries are secure and
      trusted.
  - name: Instant Screening (experimental)
    description: Instant Website Screening API
  - name: Name Screening
    description: Name screening search, alert management and remediation
paths:
  /monitoring-alerts:
    get:
      tags:
        - Monitorings
      summary: List monitoring alerts
      description: >-
        Retrieve a paginated list of monitoring alerts for the authenticated
        customer. Supports filtering by seen/unseen status and execution time,
        and provides an unseen alert count.
      parameters:
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
          description: Number of alerts per page (1-100, default 10)
        - name: next_token
          in: query
          required: false
          schema:
            type: string
          description: Pagination token for next page (Base64-encoded)
        - name: only_unacknowledged
          in: query
          required: false
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
          description: If 'true', returns only unacknowledged alerts
        - name: acknowledged
          in: query
          required: false
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
          description: If 'true', returns only acknowledged alerts
        - name: execution_time_before
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Only include alerts executed before this time (ISO8601)
        - name: execution_time_after
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Only include alerts executed after this time (ISO8601)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitoringAlertsListResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
      security:
        - xApiKey: []
components:
  schemas:
    MonitoringAlertsListResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/MonitoringAlert'
        unacknowledged_count:
          type: integer
          description: Number of unacknowledged alerts
          example: 1
        next_token:
          type: string
          description: Pagination token for next page (null if last page)
          example: >-
            eyJjdXN0b21lcklkIjp7IlMiOiI2OWRmNWQ4MS0yYjc0LTRmNDItYTQwMS0xM2ViOTZiYTA2MTkifSwiZXhlY3V0aW9uVGltZSI6eyJTIjoiMjAyNS0wNy0zMVQxMjowMTozMC44OTFaIn19
    ValidationError:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ValidationErrorItem'
      required:
        - errors
    MonitoringAlert:
      type: object
      properties:
        id:
          type: string
          description: Unique alert identifier
          example: a1b2c3d4
        monitoring_id:
          type: string
          format: uuid
          description: Monitoring ID
          example: d6e3b214-30b1-4401-a1b8-a1bd3c6a84e4
        customer_id:
          type: string
          format: uuid
          description: Customer ID
          example: d6e3b214-30b1-4401-a1b8-a1bd3c6a84e4
        execution_result_id:
          type: string
          format: uuid
          description: Execution result ID
          example: d6e3b214-30b1-4401-a1b8-a1bd3c6a84e4
        website:
          type: string
          format: uri
          description: Website URL
          example: https://example.com
        failed_checks:
          type: array
          items:
            type: object
            properties:
              check:
                type: string
                description: Check type
                example: non_operational_website
              explanation:
                type: string
                description: Explanation of the failed check
                example: Website is not reachable
              method_used:
                type: string
                description: Method used to perform the check
                example: AI
              status:
                type: string
                description: Status of the check
                example: FAILED
          description: Failed checks
          example:
            - check: non_operational_website
              explanation: No Website Data found
              method_used: ''
              status: FAILED
        execution_time:
          type: string
          description: Execution time of the monitoring
          example: '2022-01-01T00:00:00.000Z'
        created_at:
          type: string
          description: Creation time of the alert
          example: '2022-01-01T00:00:00.000Z'
        acknowledged_at:
          type: string
          nullable: true
          description: Acknowledged time of the alert or null if not acknowledged
          example: '2025-08-01T06:12:47.905Z'
        external_id:
          type: string
          nullable: true
          description: External reference ID or null if not set
          example: '123456'
    ValidationErrorItem:
      type: object
      properties:
        path:
          type: array
          items:
            type: string
          description: JSON path to the field with the error
        message:
          type: string
          description: Error message
        code:
          type: string
          description: Error code indicating the type of error
      required:
        - path
        - message
        - code
  securitySchemes:
    xApiKey:
      type: apiKey
      name: X-API-KEY
      in: header

````