> ## 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 Monitorings

> Get a paginated list of monitoring configurations for a customer

## Overview

Retrieve a paginated list of monitoring configurations for the authenticated customer. Supports filtering by website or state, and various sorting options.

## Request

* **Method**: `GET`
* **Path**: `/monitorings`
* **Query Parameters**: Optional filters and pagination

### Query Parameters

* `page_size` (integer, optional) - Number of items per page
  * Default: 10
  * Range: 1-100
  * Must be a positive integer

* `sort_by` (string, optional) - Field to sort results by
  * Default: `"last_execution"`
  * Options:
    * `"last_execution"` - Sort by last execution time
    * `"next_run"` - Sort by next scheduled run
    * `"state"` - Sort by running state
    * `"website"` - Sort by website URL

* `sort_direction` (string, optional) - Sort order
  * Default: `"desc"`
  * Options:
    * `"asc"` - Ascending order
    * `"desc"` - Descending order

* `next_token` (string, optional) - Pagination token for next page
  * Base64 encoded token returned from previous response
  * Used to fetch subsequent pages of results

* `state` (string, optional) - Filter by running state
  * Returns only monitorings in specified state
  * Cannot be combined with website filter

* `website` (string, optional) - Filter by specific website
  * Returns only monitorings for the specified URL
  * Cannot be combined with state filter

### Example Request

```
GET /monitorings?page_size=20&sort_by=next_run&sort_direction=asc
```

```
GET /monitorings?website=https://example.com
```

```
GET /monitorings?next_token=eyJjdXN0b21lcl9pZCI6ImN1c3RvbWVyXzEyMyIsImlkIjoiZDZlM2IyMTQtMzBiMS00NDAxLWExYjgtYTFiZDNjNmE4NGU0In0=
```

## Success Response

* **Status**: 200 OK

### Response Body

* `items` (array) - List of monitoring objects
* `next_token` (string|null) - Token for next page (null if no more pages)

### Example Response

```json theme={null}
{
  "items": [
    {
      "id": "d6e3b214-30b1-4401-a1b8-a1bd3c6a84e4",
      "website": "https://example.com",
      "customer_id": "customer_123",
      "checks": ["non_operational_website", "high_risk_diligent_classification"],
      "frequency": "weekly",
      "expires_at": "2024-12-31T23:59:59.000Z",
      "is_active": true,
      "running_state": "IDLE",
      "next_run_at": "2024-06-10T10:46:00.000Z",
      "last_execution": "2024-06-03T10:46:00.000Z",
      "execution_results": [
        {
          "check": "non_operational_website",
          "status": "success",
          "method_used": "AI",
          "explanation": ""
        },
        {
          "check": "catalog_contain_loan_flipping_indicators",
          "status": "failed",
          "method_used": "AI",
          "explanation": "Catlog contains loan flipping indicators"
        }
      ],
      "created_at": "2024-05-01T10:00:00.000Z",
      "updated_at": "2024-06-03T10:46:00.000Z",
      "external_id": "external_id_123"
    }
  ],
  "next_token": "eyJjdXN0b21lcl9pZCI6ImN1c3RvbWVyXzEyMyIsImlkIjoiZDZlM2IyMTQtMzBiMS00NDAxLWExYjgtYTFiZDNjNmE4NGU0In0="
}
```

## 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
  * Example: `{ "error": "Failed to fetch monitorings", "items": [], "next_token": null }`

## 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`

### Example Pagination Flow

```javascript theme={null}
// First page
GET /monitorings?page_size=10

// Response includes next_token
{
  "items": [...],
  "next_token": "eyJjdXN0b21lcl9pZCI6ImN1c3RvbWVyXzEyMyIsImxhc3RfZXhlY3V0aW9uIjoiMjAyNC0wNi0wM1QxMDo0NjowMC4wMDBaIn0="
}

// Next page
GET /monitorings?page_size=10&next_token=eyJjdXN0b21lcl9pZCI6ImN1c3RvbWVyXzEyMyIsImxhc3RfZXhlY3V0aW9uIjoiMjAyNC0wNi0wM1QxMDo0NjowMC4wMDBaIn0=
```

## Filter Behavior

* **Mutually Exclusive Filters**: The `website` and `state` filters cannot be used together
* **Filter Precedence**: If both filters are provided, `website` takes precedence and `state` is ignored
* **No Pagination with Filters**: When using `website` or `state` filters, all matching results are returned and `next_token` is always `null`
* **Sorting with Filters**: Sorting parameters (`sort_by`, `sort_direction`) are ignored when using filters

## Notes

* When filtering by `website` or `state`, pagination is not supported (returns all matching results)
* The `next_token` is specific to the original query parameters and should not be reused with different filters
* Invalid `next_token` values are ignored and treated as if no token was provided


## OpenAPI

````yaml GET /monitorings
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:
  /monitorings:
    get:
      tags:
        - Monitorings
      summary: List monitorings
      description: Get a list of monitorings for a customer
      parameters:
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
          description: Number of items per page (1-100, default 10)
        - name: sort_by
          in: query
          required: false
          schema:
            type: string
            enum:
              - last_execution
              - next_run
              - state
              - website
            default: last_execution
          description: 'Field to sort by (default: last_execution)'
        - name: sort_direction
          in: query
          required: false
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
          description: Sort order (asc or desc, default desc)
        - name: next_token
          in: query
          required: false
          schema:
            type: string
          description: Pagination token for next page
        - name: state
          in: query
          required: false
          schema:
            type: string
          description: Filter by running state
        - name: website
          in: query
          required: false
          schema:
            type: string
          description: Filter by specific website URL
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Monitoring'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Internal Server Error
      security:
        - xApiKey: []
components:
  schemas:
    Monitoring:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique monitoring identifier
          example: d6e3b214-30b1-4401-a1b8-a1bd3c6a84e4
        website:
          type: string
          format: uri
          description: The monitored website URL
          example: https://example.com
        customer_id:
          type: string
          description: Customer identifier
        checks:
          type: array
          items:
            type: string
            enum:
              - non_operational_website
              - high_risk_diligent_classification
              - catalog_contain_loan_flipping_indicators
          description: Active monitoring checks
        frequency:
          type: string
          enum:
            - weekly
            - every_2_weeks
            - every_3_weeks
            - every_4_weeks
          description: Monitoring frequency
        is_active:
          type: boolean
          description: Whether monitoring is active
        running_state:
          type: string
          enum:
            - IDLE
            - RUNNING
            - FAILED
          description: Current execution state
        next_run_at:
          type: string
          format: date-time
          description: Next scheduled execution time
        expires_at:
          type: string
          format: date-time
          description: Monitoring expiration date
        last_execution:
          type: string
          format: date-time
          nullable: true
          description: Timestamp of last execution, null if never executed
        created_at:
          type: string
          format: date-time
          description: Creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
        execution_results:
          type: array
          items:
            type: object
          description: Results from the latest monitoring execution
        external_id:
          type: string
          description: External identifier for this monitoring
  securitySchemes:
    xApiKey:
      type: apiKey
      name: X-API-KEY
      in: header

````