Monitors API¶

The Monitors API allows you to programmatically manage data quality monitors for specific assets. You can create, update, list, and delete monitors to track metrics, predefined data quality indicators, or custom business rules.

Create a New Monitor¶

POST {config_endpoint}/{tenant}/configuration/assets/{assetId}/monitors

Use this endpoint to create a new monitor. The structure of the monitor object changes based on the type selected.

Request Body Schema¶

The request body is a JSON object containing the high-level configuration for the monitor.

`type`	String	Yes	The category of monitor. Options: `PREDEFINED_METRIC`, `METRIC`, or `RULE`.
`name`	String	Yes	A unique, descriptive name for the monitor.
`enabled`	Boolean	Yes	Whether the monitor is active and running.
`description`	String	No	Additional context about the monitor's purpose.
`impact`	String	No	Severity level of an incident. Options: `LOW`, `MEDIUM`, `HIGH`.
`monitor`	Object	Yes	The specific logic/expression (schema varies by type). See below.
`threshold`	Object	Yes	Defines when an alert is triggered (ML or Static).
`ticketing`	Object	No	Integration settings for external tools like JIRA.
`notification`	Object	No	Settings for alert delivery (e.g., email, Slack).

The "monitor" Object Detail¶

The internal structure of the monitor field depends on the type defined in the root of the request:

Type: PREDEFINED_METRIC

Used for out-of-the-box metrics.

"monitor": {
    "predefined_metric": "COMPLETENESS",
    "attributes": ["ACCOUNT_ID"]
}

Type: METRIC

Used for custom SQL-based calculations across an asset.

"monitor": {
    "expression": "avg(`LATEST_YEAR_ANNUAL_RETURN`) group by `COMPANY_CATEGORY`",
    "options": { "ignore_nulls": true },
    "raw_sql": false
}

Type: RULE

Used for row-level validations. Can be defined via a custom DSL expression or a Template ID.

// Example using DSL Expression
"monitor": {
    "expression": "validate a1 expect is_date_time",
    "options": { "ignore_nulls": false, "empty_values": [] },
    "variables": [{ "name": "a1", "type": "REFERENCE", "value": ["DUE_DATE"] }]
}

// Example using Template
"monitor": {
    "template_id": 46,
    "variables": [{ "name": "a1", "type": "REFERENCE", "value": ["DUE_DATE"] }]
}

Threshold Object¶

The threshold object determines the logic used to trigger an incident. Data Observability supports both Machine Learning (ML) based anomaly detection, relative and static thresholding.

`threshold_type`	String	The threshold type. Options: `ML` (anomaly detection), `STATIC` (specific bounds) `RELATIVE` (relative change by %) Learn more about thresholds.
`threshold1`	Number	The lower bound for static or relative thresholds
`threshold2`	Number	The upper bound for static or relative thresholds
`extrapolation_strategy`	String	How to handle missing data points. Options: `IGNORE`, `ZERO`, `AVERAGE`.
`history_limit`	Integer	The number of historical data points the ML model or relative should consider (20 for default).

Notification Object¶

The notification object defines whether alerts should be pushed to external communication channels.

`send_notifications`	Boolean	If `true`, notifications will be triggered when an incident is created.
`notification_channel_names`	Array	List of pre-configured channel names (e.g., `["Slack-Data-Engineering", "Email-Alerts"]`).

Ticketing Object¶

The ticketing object manages the automatic creation of tasks in external project management tools like JIRA.

`type`	String	The ticketing system type. Currently supports `JIRA` only
`create_ticket`	Boolean	If `true`, a ticket is automatically generated upon incident detection.
`ticket_template_id`	Integer	The ID of the specific template to use for the ticket structure.

Example Request Body¶

{
    "type": "METRIC", // Options: PREDEFINED_METRIC, METRIC, RULE
    "enabled": true,
    "name": "metricPol2",
    "description": "Monitor description here",
    "impact": "LOW",
    "tags": null,
    "monitor": {
        "expression": "avg(`LATEST_YEAR_ANNUAL_RETURN`) group by `COMPANY_CATEGORY`",
        "options": {
           "ignore_nulls": true
         },
        "raw_sql": false
    },
    "threshold": {
      "threshold_type": "ML",
      "threshold1": null,
      "threshold2": null,
      "extrapolation_strategy": "IGNORE",
      "history_limit": 0
    },
    "ticketing": {
      "type": "JIRA",
      "ticket_template_id": null,
      "create_ticket": null
    },
    "notification": {
      "send_notifications": false,
      "notification_channel_names": null
    }
}

Warning

IMPORTANT

Immutable Field: The monitor type cannot be changed after creation. The request body for an update is identical to the creation body but must omit the type field.the creation body but must omit the type field.

Update Monitor¶

PUT {config_endpoint}/{tenant}/configuration/assets/{assetId}/monitors/{monitorId}

Updates an existing monitor's configuration. Payload will be same as the Create New Monitor payload with exception to type as it's immutable.

List Monitors¶

GET {config_endpoint}/{tenant}/configuration/assets/{assetId}/monitors

Returns an array of all monitors associated with the specified asset.

Response Object Definition¶

Each item in the returned array is a Monitor Object containing:

Identification: id (unique integer), name, and description.
Configuration: The full monitor logic, type (METRIC, RULE, etc.), and enabled status.
Incident Management: threshold, ticketing, and notification settings.
Audit Metadata: created_by (email) and created_at (ISO timestamp).

Response Example:

[
  {
    "id": 3419,
    "type": "RULE",
    "enabled": true,
    "name": "corrPol2",
    "monitor": { ... },
    "created_by": "user@actian.ai",
    "created_at": "2025-11-07T07:27:05.730Z"
  }
]

Get Monitor Details¶

GET {config_endpoint}/{tenant}/configuration/assets/{assetId}/monitors/{monitorId}

Retrieves the full configuration, metadata, and audit trail (created/modified) for a specific monitor.

Response Object Definition¶

This returns a comprehensive Monitor Object which includes all fields found in the "List" response, plus additional audit fields:

modified_by: The email of the last user to update the monitor.
modified_at: The ISO timestamp of the last modification.
impact: The severity level assigned to the monitor (e.g., LOW, MEDIUM, HIGH).
tags: Any user-defined metadata tags associated with the monitor.

Delete Monitor¶

DELETE {config_endpoint}/{tenant}/configuration/assets/{assetId}/monitors/{monitorId}

Permanently removes a monitor from the asset configuration.

Response:

{
    "message": "Monitor successfully deleted"
}

Error Codes¶

The API uses standard HTTP status codes to indicate the success or failure of requests.

Status Code	Description	Possible Causes
`400 Bad Request`	The request was invalid or cannot be served.	Missing required fields, invalid SQL/DSL expression, or attempting to change the `type` in a PUT request.
`401 Unauthorized`	Authentication failed.	Invalid or expired API token.
`403 Forbidden`	Permissions error.	The user does not have access to the specified tenant or asset.
`404 Not Found`	Resource not found.	The `assetId` or `monitorId` does not exist.