Server Location


HLS Analyzer Monitoring API
Documentation Powered by ReDoc

HLS Analyzer Monitoring API (2.0)

URL: https://www.hlsanalyzer.com/contact Terms of Service

REST-APIs for interfacing with the HLS Analyzer monitoring service

HLSAnalyzer.com is an online HLS analyzer and monitoring service. We follow the official HTTP Live Streaming specification (RFC 8216) and check for a variety of error conditions as well as HLS conformance points. For any HLS stream, the monitoring engine initializes the playlist buffer with segment durations greater than three times the target duration. It maintains this buffer with the arrival of each new segment while accumulating the elapsed time in the playlist refresh cycle. In addition to stream monitoring, HLSAnalyzer.com also tracks and saves all advertisement cues (SCTE-35) appearing in HLS playlists.

Our monitoring service will recognize a variety of SCTE-35 marker formats (shown below). When a duration field is available, the analyzer will confirm that the individual segment lengths for the advertisement match the expected duration:

Supported SCTE-35 Formats

#EXT-X-CUE-OUT:DURATION=60

...

#EXT-X-CUE-IN

#EXT-X-CUE-OUT:120

...

#EXT-X-CUE-IN

#EXT-X-CUE-OUT

...

#EXT-X-CUE-IN

#EXT-X-DATERANGE:ID="22",START-DATE=START_DATE,SCTE35-OUT=...

...

#EXT-X-DATERANGE:ID="22",START-DATE=START_DATE,SCTE35-IN=...

The RESTful APIs documented here can add and remove HLS streams, configure stream-alerting features, and enable or disable alerts on individual streams. Our monitoring process will generate email and HTTP-based alarms when media streams encounter delivery problems or SCTE-35 cues disappear from the playlist. These APIs enable a high level of automation that help integrate our service into your production pipeline or a CICD development and testing environment.

All API-based streams are private and can only be accessed and monitored with a corresponding API key.

Alerts

Global Alert Configuration

Read the global alert configuration settings.

query Parameters
apikey
required
string

Unique API key

Responses

Response samples

Content type
application/json
{
  • "email": "noname@example.com",
  • "callback": "https://httpbin.org/post",
  • "enable": true,
  • "notifyclear": false,
  • "sensitivity": 3
}

Global Alert Configuration

Specify the global alert destinations, which will be used in case an alert is raised. When specified, the parameters will be tested for validity: a test email will be sent to the address provided, and the callback link will be confirmed via an HTTP POST. Alerts may also be enabled and disabled using this command.

The alert descriptions will be in JSON format, which will be emailed and POSTed when an alarm is triggered.

There are 3 sensitivty levels, increasing from least sensitive to most.Alerts are generated when 1) no data is being received (total outage), 2) when segments are slower than realtime and a specific outage duration has been accumulated (outage accumulation), or 3) when segments are delivered slower than realtime for a minimum amount of time (poor delivery).

To avoid excessive email communication, for any single stream only 10 email “STREAM Outage” alerts will be sent in 24 hours, with an additional 10 “Clear” email messages when enabled. No limits shall exist for HTTP callbacks or SCTE-35 outage alerts.

query Parameters
apikey
required
string

Unique API key

email
string

Email address to which alert messages will be sent, or “none” to remove an existing email address. Up to 3 email addresses (separated by commas) may be specified

callback
string

An HTTP address to which alert messages will be POSTed, or “none” to remove existing HTTP callback address

enable
string

enable or disable alerting [default: false]

notifyclear
string

enable or disable sending an email when an alert condition has cleared [default: false]

sensitivity
number

set alert sensitivity from 1 (least) to 3 (most)

Responses

Response samples

Content type
application/json
{}

Stream Outage Alert Thresholds

Specify alert limits for delivery outages in all streams. An outage condition is entered when the stream playback buffer reaches 0 seconds, or if the Media Playlist contains an “#EXT-X-ENDLIST” tag. If an outage condition continues for more than outage_seconds, an alert will be raised. The alert condition must be cleared for a contiguous clear_seconds, before a new alert may be raised for the same stream.

query Parameters
apikey
required
string

Unique API key

outage
required
integer

minimum seconds of the outage before an alert is raised [default: 120, minimum: 30; maximum: 3600]

clear
required
integer

minimum seconds for which an alert must be contiguously resolved, after which a new alert may be raised for the same outage stream [default, minimum: 300; maximum: 3600]

Responses

Response samples

Content type
application/json
{
  • "outage": 120,
  • "clear": 300
}

Stream Outage Alert Thresholds

Read the delivery outage alert parameters for all streams.

query Parameters
apikey
required
string

Unique API key

Responses

Response samples

Content type
application/json
{
  • "outage": 120,
  • "clear": 300
}

SCTE-35 Outage Alert Thresholds

Read the SCTE-35 outage alert parameters for all streams.

query Parameters
apikey
required
string

Unique API key

Responses

Response samples

Content type
application/json
{
  • "outage": 15,
  • "clear": 30
}

SCTE-35 Outage Alert Thresholds

Specify alert limits for SCTE-35 outages in all streams. An outage condition is entered when consecutive SCTE-35 Cue-out and Cue-in playlist parameters have not been observed for outage_minutes. The alert condition must be cleared for a contiguous clear_minutes before a new alert may be raised for the same stream.

query Parameters
apikey
required
string

Unique API key

outage
required
integer

minimum minutes of the outage before an alert is raised [default: 30, minimum: 15, maximum:720]

clear
required
integer

minimum minutes of minutes for which an alert must be contiguously resolved, after which a new alert may be raised for the same outage stream [default, minimum: 30, maximum: 720]

Responses

Response samples

Content type
application/json
{
  • "outage": 15,
  • "clear": 30
}

Individual Stream Outage Alert Mode

Enable or disable the stream outage alert mode for an individual link. If alerts are globally disabled, individual alerts cannot be enabled. Once a link is removed, its alert state will also be erased.

query Parameters
apikey
required
string

Unique API key

mode
required
string

mode 0: alerts disabled, mode 1: alerts enabled [default]

m3u8
string

URI of the link being monitored

linkid
string

ID of the link being monitored

Responses

Response samples

Content type
application/json
{
  • "mode": "0",
  • "linkid": "d421d046"
}

Individual Stream Outage Alert Mode

Get the currently enabled or disabled stream outage alerts for individual streams.

query Parameters
apikey
required
string

Unique API key

Responses

Response samples

Content type
application/json
{
  • "mode": {
    }
}

Individual SCTE-35 Outage Alert Mode

Get the current individually enabled or disabled SCTE-35 outage alerts.

query Parameters
apikey
required
string

Unique API key

Responses

Response samples

Content type
application/json
{
  • "mode": {
    }
}

Individual SCTE-35 Outage Alert Mode

Enable or disable the SCTE-35 outage alert mode for an individual link. SCTE-35 alerts are disabled by default, so they must be enabled individually for each stream. If alerts are globally disabled, individual alerts will not be enabled. Once a link is removed, its alert state will also be reset.

query Parameters
apikey
required
string

Unique AP key

mode
required
string

mode 0: alerts disabled [default], mode 1: alerts enabled

m3u8
string

URI of the link being monitored

linkid
string

ID of the link being monitored

Responses

Response samples

Content type
application/json
{
  • "mode": "0",
  • "linkid": "d421d046"
}

Records

Alert Events

Get all alert records between the start and end timestamps for the specified LinkID. Timestamps are specified in Unix timestamp mode (UTC).

query Parameters
apikey
required
string

Unique API key

linkid
required
string

ID of the stream being monitored

start
required
string

UTC timestamp

end
required
string

UTC timestamp

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

SCTE-35 Cues

Get all SCTE-35 cue records between the start and end timestamps for the specified LinkID. Timestamps are specified in Unix timestamp mode (UTC).

query Parameters
apikey
required
string

Unique API key

linkid
required
string

ID of the stream being monitored

start
required
string

UTC timestamp

end
required
string

UTC timestamp

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Stream Errors

Retrieve all current errors associated with the specified LinkID and the duration between start and end UTC timestamps, for up to the 1000 most recent occurrences. LinkIDs may only be specified for both Master as well as Media playlists.

query Parameters
apikey
required
string

Unique API key

linkid
required
string

ID of the stream being monitored

start
required
string

UTC timestamp

end
required
string

UTC timestamp

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Stream Warnings

Retrieve all current warnings associated with the specified LinkID and the duration between start and end UTC timestamps, for up to the 1000 most recent occurrences. LinkIDs may only be specified for both Master as well as Media playlists.

query Parameters
apikey
required
string

Unique API key

linkid
required
string

ID of the stream being monitored

start
required
string

UTC timestamp

end
required
string

UTC timestamp

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Streams

Add Individual Streams

Add a Master or Media HLS playlist (.m3u8). Monitoring will start immediately after the HLS URI has been added. An internal LinkID will be generated, unless it has been specified on the query string (between 6 and 32 alphanumeric characters), in which case it will be applied to the Master playlist. All variants and their generated LinkIDs will be returned in the JSON response. The available monitoring quota for the API key will be updated.

Custom HTTP Headers can be specified by adding "#http-custom-header=HeaderName:HeaderValue" to the end of any playlist URIs. The custom header will be stripped from the URI link and automatically added as an HTTP header when requesting the URIs and associated segments.

query Parameters
apikey
required
string

Unique API key

m3u8
required
string

HLS URI accessible over the public internet

linkid
string

Specify an identifier for this stream (between 6 and 32 alphanumeric characters)

Responses

Response samples

Content type
application/json
Example
example-1
example-1
example-2
{}

Remove Individual Streams

Remove a stream by specifying either the URI or the LinkID of the stream being monitored. Removing a stream will completely delete all its log and alert history from the system. Removing a Master playlist will also affect all of its variants. Only the top-level LinkID for a stream can be specified (individual variants within a Master playlist cannot be removed).

query Parameters
apikey
required
string

Unique API key

m3u8
string

The URI of the stream to be removed

linkid
string

The identifier of the link to be removed

Responses

Response samples

Content type
application/json
{}

Reset Individual Stream Statistics

Reset stream statistics by specifying either the URI or the LinkID of the stream being monitored. Resetting a stream will initialize all monitoring parameters and alerts. Similar to the remove process, reseting a Master playlist will also affect all of its variants. Only the top-level LinkID for a stream can be specified (individual variants within a Master playlist cannot be reset).

query Parameters
apikey
required
string

Unique API key

m3u8
string

The URI of the link to be reset

linkid
string

The identifier of the link to be reset

Responses

Response samples

Content type
application/json
{}

Remove All Streams

Remove all streams and their associated log and alert records from the system. This API will not wait for the completion status. Use the stream status API to determine all streams have been successfully removed.

query Parameters
apikey
required
string

Unique API key

Responses

Response samples

Content type
application/json
{}

Individual Stream Status

Get the current status of individual Master or Media playlists. LinkIDs for individual Media playlists, or the top-level Master playlist can be specified. If no parameters are specified, the status for all streams will be returned.

query Parameters
apikey
required
string

Unique API key

m3u8
string

The URI of the link

linkid
string

The identifier of the link

Responses

Response samples

Content type
application/json
{
  • "link": "https://bitdash-a.akamaihd.net/content/sintel/hls/video/250kbit.m3u8",
  • "status": {
    }
}

Segment Download Enable

Enable or disable downloading of segments for all streams of the specified API key. When disabled, only HLS playlists are monitored for outages and underflows. Segment downloading is enabled by default and is required to monitor VOD streams.

query Parameters
apikey
required
string

Unique API key

enable
required
string

enable (true) or disable (false) segment downloads [default: disabled]

Responses

Response samples

Content type
application/json
{
  • "enable": true
}

Segment Download Enable

Read the current segment download mode.

query Parameters
apikey
required
string

Unique API key

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "enable": true
}

Response samples

Content type
application/json
{
  • "enable": true
}

System

Global API Status

List all associated information about the API, such as the number of variants being monitored, API key expiration, remaining variant quota, etc.

query Parameters
apikey
required
string

Unique API key

Responses

Response samples

Content type
application/json
{
  • "StreamLimit": 120,
  • "TimeRemaining": "30 days",
  • "ActiveStreams": 12
}

System Health Status

Check the health status of the various system services, in addition to information about the number of streams being monitored and the aggregate download rate of all segments in kilobits per second (KBPS). This API can be called at most once every 30 seconds.

query Parameters
apikey
required
string

Unique API Key

Responses

Response samples

Content type
application/json
{
  • "StatusAlertService": "OK",
  • "StatusEmailService": "OK",
  • "StatusMonitorService": "OK",
  • "InfoDownloadRate": 11016,
  • "InfoStreamCount": 8,
  • "InfoStreamErrors": 0,
  • "InfoMonitoringTime": 108413,
  • "InfoCPUPercentage": 30.6
}

HTTP Post Test

Post Data

Use as an endpoint for testing HTTP POST alerts. All post data lengths will be limited to a maximum of 1500 characters, and the system will only keep the most recent 250 POSTs.

query Parameters
apikey
required
string

Unique API Key

Responses

Clear All Posts

Clear all HTTP POST entires from the system.

query Parameters
apikey
required
string

Unique API Key

Responses

Total Post Count

Get the total HTTP POST counts send to the system.

query Parameters
apikey
required
string

Unique API Key

Responses

Response samples

Content type
application/json
{
  • "count": 0
}

Get All Posts

Get all of the HTTP POST data that are available in the system (limited to the most recent 250 POSTs).

query Parameters
apikey
required
string

Unique API Key

Responses

Response samples

Content type
application/json
{
  • "posts": [
    ]
}