List Monitorings

​

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

• pageSize (integer, optional) - Number of items per page
  • Default: 10
  • Range: 1-100
  • Must be a positive integer
• sortBy (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
    • "id" - Sort by monitoring ID
• sortDirection (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?pageSize=20&sortBy=next_run&sortDirection=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

{
  "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": [
        {
          "executionTime": "2024-06-03T10:46:00.000Z",
          "status": "success",
          "alerts": []
        }
      ],
      "created_at": "2024-05-01T10:00:00.000Z",
      "updated_at": "2024-06-03T10:46:00.000Z"
    }
  ],
  "next_token": "eyJjdXN0b21lcl9pZCI6ImN1c3RvbWVyXzEyMyIsImlkIjoiZDZlM2IyMTQtMzBiMS00NDAxLWExYjgtYTFiZDNjNmE4NGU0In0="
}

​

Error Handling

• 400 Bad Request
  • Invalid query parameter values
  • Example: { "error": "pageSize 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

​

Example Pagination Flow

// First page
GET /monitorings?pageSize=10

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

// Next page
GET /monitorings?pageSize=10&next_token=eyJjdXN0b21lcl9pZCI6ImN1c3RvbWVyXzEyMyIsImxhc3RfZXhlY3V0aW9uIjoiMjAyNC0wNi0wM1QxMDo0NjowMC4wMDBaIn0=

​

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