> For the complete documentation index, see [llms.txt](https://docs.decube.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decube.io/public-api/overview/index/monitors/examples.md).

# Examples of Monitor Creation

This page provides comprehensive examples for creating monitors using the Decube Public API. All examples follow the validation rules and constraints documented in the [Create, Manage & Delete](/public-api/overview/index/monitors/create-manage-and-delete.md) guide.

{% hint style="info" %}
Before using these examples, make sure you understand the [Monitor Validation & Constraints](/public-api/overview/index/monitors/create-manage-and-delete.md#monitor-validation-and-constraints) to ensure your monitors are configured correctly.
{% endhint %}

## Prerequisites

### Authentication

All API requests require authentication via the `X-Decube-Api-Key` header:

```bash
# Set your API key as an environment variable
export DECUBE_API_KEY="your-api-key-here"

# Include in curl requests
curl -H "X-Decube-Api-Key: $DECUBE_API_KEY" ...
```

### Base URL

Replace `<REGION>` with your Decube region (e.g., `us`, `eu`):

```
https://connect.<REGION>.decube.io/api/v1/data/monitors
```

## Basic Examples

### Example 1: Minimal Scheduled Volume Monitor

A basic scheduled monitor for dataset-level volume monitoring with hourly frequency.

```bash
curl -X POST \
  "https://connect.<REGION>.decube.io/api/v1/data/monitors" \
  -H "Content-Type: application/json" \
  -H "X-Decube-Api-Key: $DECUBE_API_KEY" \
  -d '{
    "asset": { "type": "dataset", "id": 123 },
    "test_type": "volume",
    "mode": "scheduled",
    "name": "hourly-volume-monitor",
    "description": "Hourly volume monitoring for dataset 123",
    "notify": true,
    "incident_level": "warning",
    "frequency": { "frequency": "1H" },
    "row_creation": {
      "filter_mode": "all_records"
    }
  }'
```

**Expected Response:**

```json
{ "monitor_id": 1 }
```

**Key Points:**

* `row_creation` is required for volume tests
* Hourly frequency doesn't require timezone or time\_of\_day
* `all_records` row creation mode processes the entire dataset

### Example 2: Daily Freshness Monitor with Timezone

A scheduled freshness monitor running daily at a specific time with timestamp-based row creation.

```bash
curl -X POST \
  "https://connect.<REGION>.decube.io/api/v1/data/monitors" \
  -H "Content-Type: application/json" \
  -H "X-Decube-Api-Key: $DECUBE_API_KEY" \
  -d '{
    "asset": { "type": "dataset", "id": 456 },
    "test_type": "freshness",
    "mode": "scheduled",
    "name": "daily-freshness-monitor",
    "description": "Daily freshness monitor running at 3:00 UTC",
    "notify": true,
    "custom_alerts": {
      "email": ["data-team@example.com"],
      "slack": [],
      "teams_webhook": []
    },
    "incident_level": "critical",
    "frequency": {
      "frequency": "1D",
      "time_of_day": 3,
      "timezone": "UTC"
    },
    "row_creation": {
      "filter_mode": "timestamp",
      "metric_column_id": 789,
      "enable_smart_training": true
    }
  }'
```

**Key Points:**

* Daily frequency requires `time_of_day` (0-23) and `timezone`
* `metric_column_id` must reference an existing timestamp/datetime column
* `enable_smart_training` enables automatic threshold learning

### Example 3: On-Demand Field Health Monitor

An on-demand monitor for validating email format using regex matching.

```bash
curl -X POST \
  "https://connect.<REGION>.decube.io/api/v1/data/monitors" \
  -H "Content-Type: application/json" \
  -H "X-Decube-Api-Key: $DECUBE_API_KEY" \
  -d '{
    "asset": { "type": "property", "id": 987 },
    "test_type": "regex_match",
    "mode": "on_demand",
    "name": "email-format-validation",
    "description": "Validate email field format using regex",
    "notify": false,
    "incident_level": "info",
    "row_creation": {
      "filter_mode": "all_records"
    },
    "threshold": {
      "type": "value",
      "value": "^[\\w.-]+@[\\w.-]+\\.[a-zA-Z]{2,}$"
    },
    "lookback_period": 7
  }'
```

**Key Points:**

* `frequency` is omitted for on-demand monitors
* `regex_match` uses `value` threshold type with regex pattern
* `lookback_period` is required for on-demand monitors with all\_records row creation

## Advanced Examples

### Example 4: Custom SQL Monitor

A scheduled monitor using custom SQL that defines its own pass/fail logic.

```bash
curl -X POST \
  "https://connect.<REGION>.decube.io/api/v1/data/monitors" \
  -H "Content-Type: application/json" \
  -H "X-Decube-Api-Key: $DECUBE_API_KEY" \
  -d '{
    "asset": { "type": "source", "id": 1 },
    "test_type": "custom_sql",
    "mode": "scheduled",
    "name": "custom-sql-quality-check",
    "description": "Custom SQL monitor for data quality validation",
    "notify": true,
    "custom_alerts": {
      "email": ["dqa@example.com"],
      "slack": [],
      "teams_webhook": []
    },
    "incident_level": "warning",
    "frequency": {
      "frequency": "1D",
      "time_of_day": 2,
      "timezone": "UTC"
    },
    "custom_sql": "SELECT CASE WHEN COUNT(*) > 100 THEN 1 ELSE 0 END as has_issues FROM {{table}} WHERE status NOT IN ('"'"'ok'"'"','"'"'pending'"'"')"
  }'
```

**Key Points:**

* Custom SQL monitors don't use `row_creation` or `threshold`
* The query itself contains the validation logic and thresholds
* When submitting the custom\_sql payload, ensure that the SQL is valid. If the SQL is invalid, the API will return an error.

## Common Errors and Solutions

### Missing Required Fields

❌ **Incorrect**: Missing `row_creation` for volume test

```json
{
  "asset": { "type": "dataset", "id": 123 },
  "test_type": "volume",
  "mode": "scheduled",
  "name": "invalid-monitor",
  "notify": true,
  "incident_level": "warning",
  "frequency": { "frequency": "1H" }
}
```

✅ **Correct**: Include required `row_creation`

```json
{
  "asset": { "type": "dataset", "id": 123 },
  "test_type": "volume",
  "mode": "scheduled",
  "name": "valid-monitor",
  "notify": true,
  "incident_level": "warning",
  "frequency": { "frequency": "1H" },
  "row_creation": { "filter_mode": "all_records" }
}
```

### Incorrect Frequency Format

❌ **Incorrect**: Daily frequency missing required fields

```json
{
  "frequency": { "frequency": "1D" }
}
```

✅ **Correct**: Include `time_of_day` and `timezone`

```json
{
  "frequency": {
    "frequency": "1D",
    "time_of_day": 9,
    "timezone": "UTC"
  }
}
```

### Invalid Threshold Types

❌ **Incorrect**: Wrong threshold type for range-based test

```json
{
  "test_type": "average",
  "threshold": { "type": "value", "value": "100" }
}
```

✅ **Correct**: Use range threshold for numeric tests

```json
{
  "test_type": "average",
  "threshold": { "type": "range", "min": 50, "max": 150 }
}
```

## Quick Reference

### Required Fields for All Monitors

* `asset` (with valid type and id)
* `test_type`
* `mode` (`"scheduled"` or `"on_demand"`)
* `name` (max 100 characters)
* `notify` (boolean)
* `incident_level`

### Additional Required Fields by Mode

* **Scheduled**: `frequency`
* **On-demand**: `lookback_period` (for timestamp/sql\_expression row creation)

### Row Creation Requirement by Test Type

* **Required**: All field health tests, volume, freshness
* **Not applicable**: Custom SQL, schema drift, job failure

### Frequency Requirements

* **Hourly**: Just `frequency` field
* **Daily**: `frequency`, `time_of_day`, `timezone`
* **Weekly**: `frequency`, `time_of_day`, `day_of_week`, `timezone`
* **Monthly**: `frequency`, `time_of_day`, `day_of_month`, `timezone`

For more detailed validation rules, see the [Monitor Validation & Constraints](/public-api/overview/index/monitors/create-manage-and-delete.md#monitor-validation-and-constraints) section.