Get Started

Monitors

Monitors allow Secoda admins to have insight into the health of the data stack. Learn more about monitors here.

List Monitors

get

This endpoint allows you to retrieve a list of all the monitors in your workspace.

Authorizations
Responses
200
List of Monitors.
application/json
Responseall of
get
GET /api/v1/monitor/monitors HTTP/1.1
Host: api.secoda.co
Authorization: Bearer string
Accept: */*

{
  "links": {
    "next": "https://api.secoda.co/resource/all/?page=2",
    "previous": "None"
  },
  "meta": {
    "page": 1,
    "previous_page": "None",
    "next_page": 2
  },
  "count": 315,
  "total_pages": 7,
  "results": [
    {
      "id": "886337a0-f298-4259-84dc-710879c826de",
      "created_at": "2023-10-12T14:59:58.781935Z",
      "updated_at": "2023-10-12T15:06:19.251573Z",
      "integration": "337c5803-b484-4128-a24d-dcc55dee2ea2",
      "target": "11db7782-4030-4acf-93e4-85aff3b860a1",
      "workspace": "e051db43-cda6-42dc-8a69-12d1aefc3a91",
      "metric_type": "null_percentage",
      "metric_config": "text",
      "frequency": 24,
      "name": "Null percentage in amount",
      "is_enabled": true,
      "last_attempted_at": "2023-10-12T15:03:40.693728Z",
      "last_success_at": "2023-09-29T17:46:22.552345Z",
      "last_error_at": null,
      "last_error_message": "",
      "condition_auto_sensitivity": 5,
      "condition_manual_min": null,
      "condition_manual_max": null,
      "status": "incident",
      "display_metadata": {
        "target": {
          "icon": null,
          "label": "amount",
          "entity_type": "column",
          "integration": "337c5803-b484-4128-a24d-dcc55dee2ea2",
          "integration_type": "redshift"
        }
      },
      "last_measurement_value": 1234.56,
      "last_incident": "102ac399-6e3a-42dd-a710-dbbb6b2addbe",
      "last_measurement": "5d6ad413-5f74-41d6-b2f5-870b6f04de5c",
      "next_run_at": "2023-10-13T15:03:40.693728Z"
    }
  ]
}

Create a Monitor

post

This endpoint allows you to create a monitor in your workspace.

Authorizations
Body
targetstring · uuidOptional

The UUID of the column or table to be monitored.

Example: 49de2499-72f8-4a7d-96d6-73cf4fb345fa
metric_typestring · enumOptional

Type of metric to monitor, e.g., percentage of null values.

Example: null_percentagePossible values:
is_enabledbooleanOptional

Flag to enable or disable the monitor.

Example: true
condition_auto_sensitivityintegerOptional

Auto sensitivity level for learning thresholds. Set to 5 if using the auto threshold, otherwise set to null if manual thresholds are used.

Example: 5
condition_manual_minnumberOptional

Manually set minimum threshold value, applicable only if auto sensitivity is null.

condition_manual_maxnumberOptional

Manually set maximum threshold value, applicable only if auto sensitivity is null.

notify_slack_channelstringOptional

The Slack channel ID where monitor incident notifications will be sent. To find a channel ID, right-click the channel in Slack, select "View channel details", and copy the Channel ID from the bottom of the popup. The channel must be joined by the Secoda Slack app.

Example: C01KNKA6J9G
Responses
201
Created
application/json
post
POST /api/v1/monitor/monitors HTTP/1.1
Host: api.secoda.co
Authorization: Bearer string
Content-Type: application/json
Accept: */*
Content-Length: 442

{
  "target": "49de2499-72f8-4a7d-96d6-73cf4fb345fa",
  "metric_type": "null_percentage",
  "metric_config": {
    "query_select": "SELECT COUNT(*) as number_of_customers FROM public.customers WHERE type = 'external' AND DATE(created_at) = CURRENT_DATE;"
  },
  "is_enabled": true,
  "condition_auto_sensitivity": 5,
  "condition_manual_min": null,
  "condition_manual_max": null,
  "notify_slack_channel": "C01KNKA6J9G",
  "schedule": {
    "day": 2,
    "hour": 3,
    "cadence": "daily",
    "frequency": 1
  }
}
{
  "id": "886337a0-f298-4259-84dc-710879c826de",
  "created_at": "2023-10-12T14:59:58.781935Z",
  "updated_at": "2023-10-12T15:06:19.251573Z",
  "integration": "337c5803-b484-4128-a24d-dcc55dee2ea2",
  "target": "11db7782-4030-4acf-93e4-85aff3b860a1",
  "workspace": "e051db43-cda6-42dc-8a69-12d1aefc3a91",
  "metric_type": "null_percentage",
  "metric_config": "text",
  "frequency": 24,
  "name": "Null percentage in amount",
  "is_enabled": true,
  "last_attempted_at": "2023-10-12T15:03:40.693728Z",
  "last_success_at": "2023-09-29T17:46:22.552345Z",
  "last_error_at": null,
  "last_error_message": "",
  "condition_auto_sensitivity": 5,
  "condition_manual_min": null,
  "condition_manual_max": null,
  "status": "incident",
  "display_metadata": {
    "target": {
      "icon": null,
      "label": "amount",
      "entity_type": "column",
      "integration": "337c5803-b484-4128-a24d-dcc55dee2ea2",
      "integration_type": "redshift"
    }
  },
  "last_measurement_value": 1234.56,
  "last_incident": "102ac399-6e3a-42dd-a710-dbbb6b2addbe",
  "last_measurement": "5d6ad413-5f74-41d6-b2f5-870b6f04de5c",
  "next_run_at": "2023-10-13T15:03:40.693728Z"
}

Get Monitor

get

This endpoint allows you to retrieve a monitors by it's ID. You can find the ID in the URL of the monitor when accessing it from the Secoda UI.

Authorizations
Path parameters
monitor_idstringRequired

The unique identifier of the monitor

Example: 871fc00d-828b-4348-9353-c635313ee459
Responses
200
Monitor retrieved successfully
application/json
get
GET /api/v1/monitor/monitors/{monitor_id} HTTP/1.1
Host: api.secoda.co
Authorization: Bearer string
Accept: */*

{
  "id": "886337a0-f298-4259-84dc-710879c826de",
  "created_at": "2023-10-12T14:59:58.781935Z",
  "updated_at": "2023-10-12T15:06:19.251573Z",
  "integration": "337c5803-b484-4128-a24d-dcc55dee2ea2",
  "target": "11db7782-4030-4acf-93e4-85aff3b860a1",
  "workspace": "e051db43-cda6-42dc-8a69-12d1aefc3a91",
  "metric_type": "null_percentage",
  "metric_config": "text",
  "frequency": 24,
  "name": "Null percentage in amount",
  "is_enabled": true,
  "last_attempted_at": "2023-10-12T15:03:40.693728Z",
  "last_success_at": "2023-09-29T17:46:22.552345Z",
  "last_error_at": null,
  "last_error_message": "",
  "condition_auto_sensitivity": 5,
  "condition_manual_min": null,
  "condition_manual_max": null,
  "status": "incident",
  "display_metadata": {
    "target": {
      "icon": null,
      "label": "amount",
      "entity_type": "column",
      "integration": "337c5803-b484-4128-a24d-dcc55dee2ea2",
      "integration_type": "redshift"
    }
  },
  "last_measurement_value": 1234.56,
  "last_incident": "102ac399-6e3a-42dd-a710-dbbb6b2addbe",
  "last_measurement": "5d6ad413-5f74-41d6-b2f5-870b6f04de5c",
  "next_run_at": "2023-10-13T15:03:40.693728Z"
}

List Incidents

get

This endpoint allows you to retrieve a list of all the incidents in your workspace.

Authorizations
Responses
200
List of Incidents.
application/json
Responseall of
get
GET /api/v1/monitor/incidents HTTP/1.1
Host: api.secoda.co
Authorization: Bearer string
Accept: */*

{
  "links": {
    "next": "https://api.secoda.co/resource/all/?page=2",
    "previous": "None"
  },
  "meta": {
    "page": 1,
    "previous_page": "None",
    "next_page": 2
  },
  "count": 315,
  "total_pages": 7,
  "results": [
    {
      "acknowledged_at": "2023-11-10T19:20:44.975657Z",
      "actions": [
        {
          "type": "notification_initial",
          "user_id": "e1250ab7-c4dc-4b9c-8963-105fa73d4ba5",
          "user_name": "John Doe"
        }
      ],
      "created_at": "2023-10-10T19:20:44.975657Z",
      "display_metadata": {
        "monitor": {
          "label": "Unique percentage on extraction_completed_at"
        },
        "target": {
          "entity_type": "column",
          "icon": "text",
          "integration": "0c6f8b1a-0c8f-4fdf-b95d-57da8f80ef82",
          "integration_type": "snowflake",
          "label": "text"
        }
      },
      "first_seen_at": "2023-10-10T19:20:44.973632Z",
      "id": "6ac1bff0-b85f-47e8-84fb-8dca29614785",
      "last_notified_at": "2023-10-10T19:20:45.047056Z",
      "last_seen_at": "2023-10-10T19:20:45.047056Z",
      "monitor": "b45bc798-763d-4ca5-863a-c12a882967c9",
      "name": "Unique percentage incident",
      "resolved_at": "2025-06-26T06:10:38.824Z",
      "status": "active",
      "summary": "Unique percentage incident",
      "target": "c332407c-cfa4-47c9-8d83-31df72b30c20",
      "updated_at": "2023-10-10T19:20:45.047238Z",
      "value": 86.4081806
    }
  ]
}

Get Incident

get

This endpoint allows you to retrieve an incident by it's ID.

Authorizations
Path parameters
incident_idstringRequired

The unique identifier of the incident

Example: 871fc00d-828b-4348-9353-c635313ee459
Responses
200
Monitor retrieved successfully
application/json
get
GET /api/v1/monitor/incident/{incident_id} HTTP/1.1
Host: api.secoda.co
Authorization: Bearer string
Accept: */*

{
  "acknowledged_at": "2023-11-10T19:20:44.975657Z",
  "actions": [
    {
      "type": "notification_initial",
      "user_id": "e1250ab7-c4dc-4b9c-8963-105fa73d4ba5",
      "user_name": "John Doe"
    }
  ],
  "created_at": "2023-10-10T19:20:44.975657Z",
  "display_metadata": {
    "monitor": {
      "label": "Unique percentage on extraction_completed_at"
    },
    "target": {
      "entity_type": "column",
      "icon": "text",
      "integration": "0c6f8b1a-0c8f-4fdf-b95d-57da8f80ef82",
      "integration_type": "snowflake",
      "label": "text"
    }
  },
  "first_seen_at": "2023-10-10T19:20:44.973632Z",
  "id": "6ac1bff0-b85f-47e8-84fb-8dca29614785",
  "last_notified_at": "2023-10-10T19:20:45.047056Z",
  "last_seen_at": "2023-10-10T19:20:45.047056Z",
  "monitor": "b45bc798-763d-4ca5-863a-c12a882967c9",
  "name": "Unique percentage incident",
  "resolved_at": "2025-06-26T06:10:38.824Z",
  "status": "active",
  "summary": "Unique percentage incident",
  "target": "c332407c-cfa4-47c9-8d83-31df72b30c20",
  "updated_at": "2023-10-10T19:20:45.047238Z",
  "value": 86.4081806
}

List Measurements

get

This endpoint allows you to retrieve a list of all the measurements in your workspace filtered by a Monitor or Incident. A query param of either the Monitor ID or Incident ID is required.

If using monitoring in automatic mode, thresholds will take some time to populate as the system learnins the appropriate range for your data.

Authorizations
Query parameters
monitorstringOptional

The unique identifier of the monitor

Example: 871fc00d-828b-4348-9353-c635313ee459
incident_idstringOptional

The unique identifier of the incident

Example: 40b3e4d3-3bf8-4ec4-ae87-56d1e738ca76
Responses
200
List of Measurements.
application/json
Responseall of
get
GET /api/v1/monitor/measurements HTTP/1.1
Host: api.secoda.co
Authorization: Bearer string
Accept: */*

{
  "links": {
    "next": "https://api.secoda.co/resource/all/?page=2",
    "previous": "None"
  },
  "meta": {
    "page": 1,
    "previous_page": "None",
    "next_page": 2
  },
  "count": 315,
  "total_pages": 7,
  "results": [
    {
      "id": "6ac1bff0-b85f-47e8-84fb-8dca29614785",
      "created_at": "2023-10-03T04:46:24.290765Z",
      "updated_at": "2023-10-03T04:46:24.290765Z",
      "incident": "102ac399-6e3a-42dd-a710-dbbb6b2addbe",
      "incident_metadata": "text",
      "monitor": "102ac399-6e3a-42dd-a710-dbbb6b2addbe",
      "upper_threshold": 90.64496791804484,
      "lower_threshold": 87.83219024929676,
      "value": 90.81823317519981
    }
  ]
}

Run Monitors

post

This endpoint allows you to trigger one or more monitors to run immediately through the API. A background job is created to process the monitors.

Authorizations
Body
monitorsstring · uuid[]Optional

A list of UUIDs for the monitors to run.

Example: ["49de2499-72f8-4a7d-96d6-73cf4fb345fa","871fc00d-828b-4348-9353-c635313ee459"]
Responses
200
Monitors triggered successfully. The response includes details of the background job processing the request.
application/json
post
POST /api/v1/monitor/monitors/run HTTP/1.1
Host: api.secoda.co
Authorization: Bearer string
Content-Type: application/json
Accept: */*
Content-Length: 92

{
  "monitors": [
    "49de2499-72f8-4a7d-96d6-73cf4fb345fa",
    "871fc00d-828b-4348-9353-c635313ee459"
  ]
}
{
  "id": "4a17b8f6-d01d-4e0f-8c8d-c702dab3f4a2",
  "user": "12345",
  "failed": false,
  "started": "2024-11-28T12:34:56Z",
  "completed": null,
  "logs": "Job started successfully. Processing monitors...",
  "title": "Run Monitors",
  "has_artifact": false
}

Was this helpful?