AI Alerts API User Guide

AI alerts is an advanced feature that eliminates the need to determine the thresholds, identify the relevant dimensions needed for monitoring data, and set alerts to notify related individuals and groups.

Each AI alert is assigned an alert severity (Info, Warning, Critical) that can help in determining the impact of the alert condition. By default, all alerts are of severity Info until the thresholds for Warning and Critical are set.

When an alert condition returns to the accepted range of variation and sensitivity control limits, the AI alert ends and is listed in the Alert Ended totals to indicate that the alert condition has been cleared.

The alert totals show the alerts for the last 30 days.

For more information see, AI Alerts.

API Endpoints

To retrieve a list of Alerts:

for alerts based on the content metrics
https://api.conviva.com/insights/2.6/ai-alerts/content-metrics
for alerts based on the ad metrics
https://api.conviva.com/insights/2.6/ai-alerts/ad-metrics

To retrieve details of a specific alert event, where {alert_id} denotes the identifier of an alert event:

https://api.conviva.com/insights/2.6/ai-alerts/content-metrics/{alert_id}
https://api.conviva.com/insights/2.6/ai-alerts/ad-metrics/{alert_id}

Query Parameters

Filtering by Time Range

Use one of the following pairs of time-range query parameters:

start_date / end_date (in ISO 8601 format)
start_epoch / end_epoch (in seconds)
start_epoch_ms / end_epoch_ms (in milliseconds)

Specify one type of time range per request. A request cannot have a mixed type of start / end parameters.

Note: The maximum allowed length of an interval is 30 days.

The API retrieves only alerts that have status changes, such as, from "active" to "ended", within the specified time range.

Example

Copy

GET /insights/2.6/ai-alerts/content-metrics?start_epoch=1640851000&end_epoch=1640861709

Filtering by Severity

You can filter alerts by the severity query parameter, and the value is a comma-separated list of critical, warning, and info.

For example, to get only the warning level of alerts, use ?severity=warning.

If the query parameter is omitted, the default is equivalent of filtering with all severities ?severity=critical,warning,info

Example

Copy

GET /insights/2.6/ai-alerts/content-metrics?severity=critical,info

Filtering by Status

You can filter alerts by the status query parameter, and the status values are either active or ended (active means the alert is still on-going).

If omitted, the default is an equivalent of filtering with both statuses ?status=ended,active

Example

Copy

GET /insights/2.6/ai-alerts/content-metrics?status=ended,active

Filtering by Alert Metric

Filter alerts by the alert_metric query parameter, where the options are:

Alerts based on content metrics	Alerts based on ad metrics
`BUFFERINGRATIO` (Rebuffering Ratio) `EBVS` (Exits Before Video Start) `PCP` (Peak Concurrent Plays) `VPF` (Video Playback Failures) `VSF` (Video Start Failures) `VST` (Video Start Time)	`BITRATE` (Bitrate) `BUFFERINGRATIO` (Rebuffering Ratio) `VSF` (Video Start Failures)

If omitted, the default is an equivalent of including all options, such as ?alert_metric=BUFFERINGRATIO,EBVS,PCP,VPF,VSF,VST for content-based alerts.

Example

Copy

GET /insights/2.6/ai-alerts/content-metrics?alert_metric=BUFFERINGRATIO,VPF,VST

Response Format

Listing Alerts

The response consists of an alerts array attribute, which contains a list of alert summary objects, and each summary object consists of the following attributes:

id the alert event identifier
severity (critical, warning or info)
alert_metric the metric that triggered the alert (BUFFERINGRATIO, EBVS, VPF, VSF, VST)
root_causes a list of dimensions
status (ended or active)
timeline of the start and end timestamps (note: active alerts are on-going events, so they do not have an end time)

Example

Copy

GET /insights/2.6/ai-alerts/content-metrics

Response

Copy

{
  "alerts": [
    {
      "id": "192610695",
      "alert_type": "content",
      "severity": "info",
      "alert_metric": {
        "name": "BUFFERINGRATIO",
        "description": "Rebuffering Ratio"
      },
      "root_causes": [
        {
          "entity": "a Network Channel",
          "dimension": "CHANNEL"
        },
        {
          "entity": "a CDN name",
          "dimension": "CURRENT_CDN"
        }
      ],
      "status": "ended",
      "timeline": {
        "start": {
          "timestamp": {
            "epoch_sec": 1638772140,
            "iso_date": "2021-12-06T06:29:00.000Z"
          }
        },
        "end": {
          "timestamp": {
            "epoch_sec": 1638773340,
            "iso_date": "2021-12-06T06:49:00.000Z"
          }
        }
      }
    },
    
    /// more alerts

  ]
}

Retrieving a Specific Alert

The response consists of all alert summary information, and a timeline object that includes trigger points of various severities:

start
info
warning
critical
end

Each timeline object also includes the impact of unique and cumulative measurements at the trigger timestamp.

Note: start does not have impact measurements, and end is not available for active alerts.

Example

Copy

GET /insights/2.6/ai-alerts/content-metrics/192610695

Response

Copy

{
  "id": "192610695",
  "alert_type": "content",
  "severity": "info",
  "alert_metric": {
    "name": "BUFFERINGRATIO",
    "description": "Rebuffering Ratio"
  },
  "root_causes": [
    {
      "entity": "a Network Channel",
      "dimension": "CHANNEL"
    },
    {
      "entity": "a CDN name",
      "dimension": "CURRENT_CDN"
    }
  ],
  "status": "ended",
  "timeline": {
    "start": {
      "timestamp": {
        "epoch_sec": 1638772140,
        "iso_date": "2021-12-06T06:29:00.000Z"
      }
    },
    "info": {
      "metric_value": 0.006,
      "impacted_uniques": 833,
      "cumulative_impacted_uniques": 1539,
      "cumulative_sessions": 36355,
      "total_uniques": 6249,
      "cumulative_total_uniques": 7860,
      "timestamp": {
        "epoch_sec": 1638773280,
        "iso_date": "2021-12-06T06:48:00.000Z"
      }
    },
    "end": {
      "metric_value": 0.006,
      "impacted_uniques": 833,
      "cumulative_impacted_uniques": 1539,
      "cumulative_sessions": 36355,
      "total_uniques": 6249,
      "cumulative_total_uniques": 7860,
      "timestamp": {
        "epoch_sec": 1638773340,
        "iso_date": "2021-12-06T06:49:00.000Z"
      }
    }
  }
}

Response Codes

Status	Description
200	Successfully retrieved alert data
400 / 422	Error in query parameters
404	An `alert_id` event is not found

AI Alerts API AI Alerts API AI Alerts API