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

400

Bad Request

500

Internal Server Error

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

400

Bad Request

500

Internal Server Error

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

404

Monitor not found

500

Internal Server Error

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

400

Bad Request

500

Internal Server Error

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-03-09T20:33:39.352Z",
      "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

404

Incident not found

500

Internal Server Error

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-03-09T20:33:39.352Z",
  "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

400

Bad Request

500

Internal Server Error

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

400

Bad Request

500

Internal Server Error

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 4 days ago

Was this helpful?

hashtagList Monitors

hashtagCreate a Monitor

hashtagGet Monitor

hashtagList Incidents

hashtagGet Incident

hashtagList Measurements

hashtagRun Monitors

List Monitors

Create a Monitor

Get Monitor

List Incidents

Get Incident

List Measurements

Run Monitors