Ctrlk
Start free trial
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Monitors

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

List Monitors

get
/api/v1/monitor/monitors

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

Authorizations
Responses
200

List of Monitors.

application/json
countintegerOptional

The total count of items returned.

Example: 315
total_pagesintegerOptional

The total number of pages.

Example: 7
get/api/v1/monitor/monitors
GET /api/v1/monitor/monitors HTTP/1.1
Host: api.secoda.co
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
/api/v1/monitor/monitors

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
idstringOptional

The unique identifier of the monitor.

Example: 886337a0-f298-4259-84dc-710879c826de
created_atstringOptional

The timestamp when the monitor was created.

Example: 2023-10-12T14:59:58.781935Z
updated_atstringOptional

The timestamp when the data was last updated.

Example: 2023-10-12T15:06:19.251573Z
integrationstringOptional

The identifier of the integration associated with the resource.

Example: 337c5803-b484-4128-a24d-dcc55dee2ea2
targetstringOptional

The identifier of the resource that the monitor is watching.

Example: 11db7782-4030-4acf-93e4-85aff3b860a1
workspacestringOptional

The identifier of the workspace.

Example: e051db43-cda6-42dc-8a69-12d1aefc3a91
metric_typestring · enumOptional

The type of metric.

Example: null_percentagePossible values:
metric_configstringOptional

Configuration for the metric.

frequencyintegerOptional

The frequency with which this monitor is run.

Example: 24
namestringOptional

The full name of the monitor, includes the metric type and target resource.

Example: Null percentage in amount
is_enabledbooleanOptional

Whether the monitor is enabled.

Example: true
last_attempted_atstringOptional

The timestamp of the last attempted monitor.

Example: 2023-10-12T15:03:40.693728Z
last_success_atstring · date-timeOptional

The timestamp of the last check on Secoda's access and ability to read the data source on which this monitor is set. This is connctivity check - not a data quality check.

Example: 2023-09-29T17:46:22.552345Z
last_error_atstringOptional

The timestamp of the last error, if any.

last_error_messagestringOptional

The message associated with the last error, if any.

condition_auto_sensitivityintegerOptional

The automatic sensitivity condition.

Example: 5
condition_manual_minintegerOptional

The manual minimum condition if set by the user.

condition_manual_maxintegerOptional

The manual maximum condition if set by the user.

statusstring · enumOptional

The status of the monitor.

Example: incidentPossible values:
last_measurement_valuenumberOptional

The last measured value if one is available.

Example: 1234.56
last_incidentstringOptional

The UUID of the last active incident. If there are no active incidents (if the last incident has been closed), the field is set to null.

Example: 102ac399-6e3a-42dd-a710-dbbb6b2addbe
last_measurementstringOptional

The identifier of the last measurement.

Example: 5d6ad413-5f74-41d6-b2f5-870b6f04de5c
next_run_atstringOptional

The timestamp for the next run. Note, the run may occur shortly after the time set, but never before.

Example: 2023-10-13T15:03:40.693728Z
post/api/v1/monitor/monitors
POST /api/v1/monitor/monitors HTTP/1.1
Host: api.secoda.co
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
/api/v1/monitor/monitors/{monitor_id}

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
idstringOptional

The unique identifier of the monitor.

Example: 886337a0-f298-4259-84dc-710879c826de
created_atstringOptional

The timestamp when the monitor was created.

Example: 2023-10-12T14:59:58.781935Z
updated_atstringOptional

The timestamp when the data was last updated.

Example: 2023-10-12T15:06:19.251573Z
integrationstringOptional

The identifier of the integration associated with the resource.

Example: 337c5803-b484-4128-a24d-dcc55dee2ea2
targetstringOptional

The identifier of the resource that the monitor is watching.

Example: 11db7782-4030-4acf-93e4-85aff3b860a1
workspacestringOptional

The identifier of the workspace.

Example: e051db43-cda6-42dc-8a69-12d1aefc3a91
metric_typestring · enumOptional

The type of metric.

Example: null_percentagePossible values:
metric_configstringOptional

Configuration for the metric.

frequencyintegerOptional

The frequency with which this monitor is run.

Example: 24
namestringOptional

The full name of the monitor, includes the metric type and target resource.

Example: Null percentage in amount
is_enabledbooleanOptional

Whether the monitor is enabled.

Example: true
last_attempted_atstringOptional

The timestamp of the last attempted monitor.

Example: 2023-10-12T15:03:40.693728Z
last_success_atstring · date-timeOptional

The timestamp of the last check on Secoda's access and ability to read the data source on which this monitor is set. This is connctivity check - not a data quality check.

Example: 2023-09-29T17:46:22.552345Z
last_error_atstringOptional

The timestamp of the last error, if any.

last_error_messagestringOptional

The message associated with the last error, if any.

condition_auto_sensitivityintegerOptional

The automatic sensitivity condition.

Example: 5
condition_manual_minintegerOptional

The manual minimum condition if set by the user.

condition_manual_maxintegerOptional

The manual maximum condition if set by the user.

statusstring · enumOptional

The status of the monitor.

Example: incidentPossible values:
last_measurement_valuenumberOptional

The last measured value if one is available.

Example: 1234.56
last_incidentstringOptional

The UUID of the last active incident. If there are no active incidents (if the last incident has been closed), the field is set to null.

Example: 102ac399-6e3a-42dd-a710-dbbb6b2addbe
last_measurementstringOptional

The identifier of the last measurement.

Example: 5d6ad413-5f74-41d6-b2f5-870b6f04de5c
next_run_atstringOptional

The timestamp for the next run. Note, the run may occur shortly after the time set, but never before.

Example: 2023-10-13T15:03:40.693728Z
get/api/v1/monitor/monitors/{monitor_id}
GET /api/v1/monitor/monitors/{monitor_id} HTTP/1.1
Host: api.secoda.co
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
/api/v1/monitor/incidents

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

Authorizations
Responses
200

List of Incidents.

application/json
countintegerOptional

The total count of items returned.

Example: 315
total_pagesintegerOptional

The total number of pages.

Example: 7
get/api/v1/monitor/incidents
GET /api/v1/monitor/incidents HTTP/1.1
Host: api.secoda.co
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": "2026-01-01T00:00:00.000Z",
      "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
/api/v1/monitor/incident/{incident_id}

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
acknowledged_atstring · date-timeOptional

The time that the incident was acknowledged at. This will be null if an incident hasn't been acknowledged yet.

Example: 2023-11-10T19:20:44.975657Z
created_atstring · date-timeOptional

When the incident was created.

Example: 2023-10-10T19:20:44.975657Z
first_seen_atstring · date-timeOptional

The first time this incident was observed.

Example: 2023-10-10T19:20:44.973632Z
idstringOptional

The UUID of the incident.

Example: 6ac1bff0-b85f-47e8-84fb-8dca29614785
last_notified_atstring · date-timeOptional

The time of the last notification sent about this incident.

Example: 2023-10-10T19:20:45.047056Z
last_seen_atstring · date-timeOptional

The most recent occurence about this incident.

Example: 2023-10-10T19:20:45.047056Z
monitorstringOptional

The UUID of the associated monitor.

Example: b45bc798-763d-4ca5-863a-c12a882967c9
namestringOptional

The name of the incident, which indicates the type of metric set for the monitor.

Example: Unique percentage incident
resolved_atstring · date-timeOptional

The time that the incident was resolved. Will be null if the incident has not yet been resolved.

statusstring · enumOptional

The status of the incident.

Example: activePossible values:
summarystringOptional

An automatically generated short summary of the incident.

Example: Unique percentage incident
targetstringOptional

The UUID of the target resource being monitored for anomolies.

Example: c332407c-cfa4-47c9-8d83-31df72b30c20
updated_atstring · date-timeOptional

The last updated time for the incident.

Example: 2023-10-10T19:20:45.047238Z
valuenumberOptional

The value of the measurement at the time of incident creation.

Example: 86.4081806
get/api/v1/monitor/incident/{incident_id}
GET /api/v1/monitor/incident/{incident_id} HTTP/1.1
Host: api.secoda.co
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": "2026-01-01T00:00:00.000Z",
  "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
/api/v1/monitor/measurements

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
countintegerOptional

The total count of items returned.

Example: 315
total_pagesintegerOptional

The total number of pages.

Example: 7
get/api/v1/monitor/measurements
GET /api/v1/monitor/measurements HTTP/1.1
Host: api.secoda.co
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
/api/v1/monitor/monitors/run

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
idstring · uuidOptional

Unique identifier for the background job.

Example: 4a17b8f6-d01d-4e0f-8c8d-c702dab3f4a2
userstringOptional

ID of the user who initiated the background job.

Example: 12345
failedbooleanOptional

Indicates whether the job failed.

Example: false
startedstring · date-timeOptional

Timestamp when the job started.

Example: 2024-11-28T12:34:56Z
completedstring · date-timeOptional

Timestamp when the job completed, or null if still in progress.

logsstringOptional

Logs generated during the execution of the job.

Example: Job started successfully. Processing monitors...
titlestringOptional

Title of the job for tracking.

Example: Run Monitors
has_artifactbooleanOptional

Indicates if the job has an associated artifact (e.g., a result file).

Example: false
post/api/v1/monitor/monitors/run
POST /api/v1/monitor/monitors/run HTTP/1.1
Host: api.secoda.co
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
}

Last updated

Was this helpful?