REST API Endpoints

This section provides an overview of the available REST API endpoints. You can use these endpoints to query and update your configuration or retrieve information about the endpoints/servers you monitor. All endpoints use the message format described in Message Format. We also provide small API libraries for Python and PHP.

The REST API endpoints are broken down into a number of broad groups listed in Table 18.

The function provides by each group varies. A number of groups, such as Capabilities only provides a single endpoint with a single function. Other groups, such as Events provide multiple endpoints with different functions.

Table 18 REST API Groups

Group

Function

capabilities

You can use the endpoints in this group to determine the features that are available under your subscription.

regions

You can use the endpoints in this group to obtain information about a single geographic location your site or sites are being monitored from.

hosts

You can use the endpoints in this group to obtain details about each site being monitored.

monitors

You can use the endpoints in this group to obtain information about specific pages, slugs, or endpoints being monitored. You can also use the endpoints in this group to update your configuration.

events

You can use the endpoints in this group to obtain event history for your site. You can also generate custom events using the /v1/events/create endpoint in this group.

status

You can use the endpoints in this group to obtain the current status of the pages, slugs, or endpoints being monitored.

latency

You can use the endpoints in this group to obtain historical latency data for a given page, slug, endpoint, or site. You can also obtain plots as images, generated from collected data, through this group.

customer

You can use the customer group to pause and resume monitoring.

Capabilities Group

The capabilities group provides a single REST APIs that provides details about your subscription. The endpoint also reports whether monitoring is active or paused (maintenance mode) for your subscription.

v1/capabilities/get

The v1/capabilities/get endpoint returns a JSON encoded payload as shown below:

{
    "status": "OK",
    "capabilities": {
        "customer_active": true,
        "maximum_number_monitors": 50,
        "multi_region_checking": true,
        "paused": false,
        "polling_interval": 30,
        "supports_content_checking": true,
        "supports_keyword_checking": true,
        "supports_latency_tracking": true,
        "supports_maintenance_mode": true,
        "supports_ping_based_polling": true,
        "supports_post_method": true,
        "supports_rest_api": true,
        "supports_ssl_expiration_checking": true,
        "supports_wordpress": true,
        "supports_rollups" : true
    }
}

Most of the returned fields should be self explanatory; however, we briefly explain each in Table 19.

Table 19 /v1/capabilities/get/ Return Values

Field

Type

Provides

status

str

Holds a string containing OK on success. On error, this value will hold the error reason.

customer_active

bool

Holds true if you have verified your email address and/or other key requirements that gate the start of monitoring. If false, you can update settings but can-not perform monitoring.

maximum_number_monitors

int

Holds the maximum number of monitors that can be configured under your subscription.

multi_region_checking

bool

Holds true if your sites and pages will be checked from multiple geographic locations. Holds false if your sites and pages will be monitored from a single, randomly selected location.

paused

bool

Holds true if your subscription is in maintenance mode and monitoring is temporarily suspended. Holds false if your monitors are active. You should use the /v1/customer/pause/ REST API function to programmatically enable or disable maintenance mode.

polling_interval

int

Holds the per-site polling interval, in seconds.

supports_content_checking

bool

Holds true if your subscription allows you to use the SpeedSentry content checking feature.

supports_keyword_checking

bool

Holds true if your subscription allows you to use the SpeedSentry keyword checking feature.

supports_latency_tracking

bool

Holds true if latency will be measured, stored, and processed for every monitor. If false, you will not be able to retrieve latency information for your monitors.

supports_maintenance_mode

bool

Holds true if your subscription supports the maintenance mode function.

supports_ping_based_polling

bool

Holds true if your subscription includes using ICMP echo or ping messages on servers that support them to reduce response time.

supports_post_method

bool

Holds true if your subscription allows you to configure a monitor to use all HTTP methods. If false, only the HTTP GET method is supported.

supports_rest_api

bool

Holds true if the full REST API is supported. If false, only a limited number of REST API functions are available.

supports_ssl_expiration_checking

bool

Holds true if SSL certificate expiration checking is supported. If false, we do not check SSL certificate expiration.

supports_wordpress

bool

Holds true if you can use the WordPress plug-in. This value indicates whether a small subset of REST API functions are available. If false, then no REST API functions are available.

supports_rollups

bool

Holds true if you can receive weekly rollup emails.

Regions Group

The regions group provides two REST APIs you can use to query information about a specific geographic region your site is being monitored from.

v1/regions/get

The v1/regions/get endpoint accepts a JSON dictionary containing a single region_id parameter:

{
    "region_id" : 1
}

The endpoint returns a JSON encoded response, shown below, with a status and information about the requested region.

{
    "status": "OK",
    "region": {
        "description": "US-Ohio",
        "region_id": 1
    }
}

Most of the returned fields should be self explanatory; however, we briefly explain each in Table 20.

Table 20 /v1/regions/get/ Return Values

Field

Type

Provides

status

str

Holds a string containing OK on success. On error, this value will hold the error reason.

description

str

Holds a textual description of the region.

region_id

int

The numeric ID used to identify the region.

v1/regions/list

The v1/regions/list endpoint sends information about every geographic were your sites may be or may have been monitored from. Note that some geographic regions may no longer be used.

{
    "status": "OK",
    "regions": {
        "1": {
            "description": "US-Ohio",
            "region_id": 1
        }
    },
}

Most of the returned fields should be self explanatory; however, we briefly explain each in Table 21.

Table 21 /v1/regions/list/ Return Values

Field

Type

Provides

status

str

Holds a string containing OK on success. On error, this value will hold the error reason.

regions

dict

Dictionary containing information about each region, keyed by region ID.

description

str

Holds a textual description of the region.

region_id

int

Holds the region ID for the region.

Hosts Group

The hosts group provides two REST APIs you can use to query information about a specific server we are monitoring.

Each server, or host, will have one or more monitors associated with it. You can use functions in the Monitors Group to query or modify specific monitors.

Note

The list of hosts will change as you add or remove monitors. You do not modify the list of hosts directly.

v1/hosts/get

The v1/hosts/get endpoint accepts a JSON dictionary containing a single host_scheme_id parameter as shown below:

{
    "host_scheme_id": 48
}

The returned data will be a JSON encoded array holding the status and data for the host/scheme:

{
    "status": "OK",
    "host_scheme": {
        "host_scheme_id": 48,
        "url": "https://www.inesonic.com",
        "ssl_expiration_timestamp": 1639365748
    }
}

Most of the returned fields should be self explanatory; however, we briefly explain each in Table 22.

Table 22 /v1/hosts/get/ Return Values

Field

Type

Provides

status

str

Holds a string containing OK on success. On error, this value will hold the error reason.

host_scheme_id

int

The numeric ID used to identify the host.

url

str

A string containing the authority used to communicate with the host. The authority will contain the scheme or protocol (http or https), and the domain/subdomain.

ssl_expiration_timestamp

int

A value indicating when the SSL certificate is going to expire. A value of 0 indicates that no SSL certificate is needed or that the SSL certificate has not been checked yet. The value is encoded as a Unix timestamp, that is, the number of seconds since January 1, 1970 UTC.

v1/hosts/list

The v1/hosts/list endpoint returns a list of all hosts associated with your subscription. The endpoint will return a JSON response as shown below:

{
    "status": "OK",
    "host_schemes": {
        "48": {
            "host_scheme_id": 48,
            "ssl_expiration_timestamp": 1639365748,
            "url": "https://www.inesonic.com"
        },
        "49": {
            "host_scheme_id": 49,
            "ssl_expiration_timestamp": 1642358351,
            "url": "https://redmine.inesonic.com"
        },
        "51": {
            "host_scheme_id": 51,
            "ssl_expiration_timestamp": 0,
            "url": "https://speedsentry.inesonic.com"
        }
    }
}

Most of the returned fields should be self explanatory; however, we briefly explain each in Table 23.

Table 23 /v1/hosts/list/ Return Values

Field

Type

Provides

status

str

Holds a string containing OK on success. On error, this value will hold the error reason.

host_schemes

dict

A dictionary of host/scheme data by host/scheme ID.

host_scheme_id

int

The numeric ID used to identify the host.

url

str

A string containing the authority used to communicate with the host. The authority will contain the scheme or protocol (http or https), and the domain/subdomain.

ssl_expiration_timestamp

int

A value indicating when the SSL certificate is going to expire. A value of 0 indicates that no SSL certificate is needed or that the SSL certificate has not been checked yet. The value is encoded as a Unix timestamp, that is, the number of seconds since January 1, 1970 UTC.

Monitors Group

The monitors group provides three REST APIs you can use to:

  • query information about specific pages or REST API endpoints being monitored by SpeedSentry, or

  • to change what endpoints are being monitored and how those endpoints are being monitored.

v1/monitors/get

The v1/monitors/get endpoint accepts a JSON dictionary containing a single monitor_id parameter as shown below:

{
    "monitor_id" : 76
}

The response will be a JSON encoded array providing data on the monitor:

{
    "status": "OK",
    "monitor": {
        "path": "/product/",
        "host_scheme_id": 48,
        "method": "get",
        "content_check_mode": "no_check",
        "keywords": [],
        "post_content": "",
        "post_content_type": "text",
        "post_user_agent": "",
        "monitor_id": 76,
        "user_ordering": 1
    }
}

Most of the returned fields should be self explanatory; however, we briefly explain each in Table 24.

Table 24 /v1/monitors/get/ Return Values

Field

Type

Provides

status

str

Holds a string containing OK on success. On error, this value will hold the error reason.

monitor_id

int

A numeric ID used to reference this monitor.

user_ordering

int

A zero based index indicating the relative ordering of the monitors in the “Account Settings” page of our website.

path

str

The path under the host/scheme to be checked.

host_scheme_id

int

The ID of the host/scheme that this monitor is operating under. For details, see Hosts Group.

Between the host_scheme_id and the path field, you can determine the full URL being monitored. If the URL indicated by the host_scheme_id is “http://mysite.com” and the path is “/about-me”, then the full URL being checked is “http://mysite.com/about-me”.

method

str

The HTTP method used to access the page or end point. Returned value will be “get”, “head”, “post”, “put”, “delete”, “options”, or “patch”.

content_check_mode

str

The content check mode this monitor is using. Returned values will be one of:

  • “no_check” - SpeedSentry will confirm a HTTP 200 response but will not check the returned content.

  • “content_match” - SpeedSentry will compare the raw returned data against the last returned data and will report an issue if the returned content changed.

  • “all_keywords” - SpeedSentry will confirm that all supplied keywords are found in the returned content.

  • “any_keywords” - SpeedSentry will confirm that at least one of the supplied keywords are found in the returned content.

keywords

list

A list of keyword strings to be scanned for. The value is used only if content_check_mode is “all_keywords” or “any_keywords”.

To support binary data and arbitrary character encodings, each entry will be base-64 encoded.

post_content_type

str

Value indicating the string sent as the content type header. Supported values are “text”, “json”, “xml” which will cause the content types “text/plain”, “application/json”, and “application/xml” to be indicated in the “Content-Type” request header.

Note that Inesonic, LLC will add other types based on demand.

This value is only used if the HTTP method supports body content.

post_user_agent

str

A custom “User-Agent” string to be provided in the request headers. This value is only used if the HTTP method supports body content.

post_content

str

The body content to be sent to the remote website. To support binary data and arbitrary character sets, the data will be base-64 encoded.

v1/monitors/list

The v1/monitors/list endpoint provides you with a list of all your configured monitors. The endpoint accepts a JSON dictionary containing a single order_by parameter.

{
    "order_by": "monitor_id"
}

The order_by parameter accepts three possible values as listed in Table 25 as shown below:

Table 25 /v1/monitors/list/ Order-By Values

Value

Provides

“monitor_id”

Commands the /v1/monitors/list endpoint to return a dictionary of monitor values indexed by a monitor ID value.

“user_ordering”

Commands the /v1/monitors/list endpoint to return a dictionary of monitors indexed by the order as shown on the SpeedSentry Settings page. The first entry will have an index of 0.

“url”

Commands the /v1/monitors/list endpoint to return a dictionary of monitor values indexed by the full URL of the monitor.

The endpoint returns an array such as that shown below:

{
    "monitors": {
        "0": {
            "content_check_mode": "no_check",
            "host_scheme_id": 26,
            "keywords": [],
            "method": "get",
            "monitor_id": 57,
            "path": "/",
            "post_content": "",
            "post_content_type": "text",
            "post_user_agent": "",
            "url": "https://www.inesonic.com/",
            "user_ordering": 0
        },
        "1": {
            "content_check_mode": "no_check",
            "host_scheme_id": 26,
            "keywords": [],
            "method": "get",
            "monitor_id": 58,
            "path": "/pricing",
            "post_content": "",
            "post_content_type": "text",
            "post_user_agent": "",
            "url": "https://www.inesonic.com/pricing",
            "user_ordering": 1
        },
        "2": {
            "content_check_mode": "no_check",
            "host_scheme_id": 27,
            "keywords": [],
            "method": "get",
            "monitor_id": 56,
            "path": "",
            "post_content": "",
            "post_content_type": "text",
            "post_user_agent": "",
            "url": "https://documentation.inesonic.com",
            "user_ordering": 2
        }
    },
    "status": "OK"
}

Most of the returned fields should be self explanatory; however, we briefly explain each in Table 26.

Table 26 /v1/monitors/list/ Return Values

Field

Type

Provides

status

str

Holds a string containing OK on success. On error, this value will hold the error reason.

data

dict

Holds a dictionary of monitor entries indexed by monitor ID, user ordering, or URL.

monitor_id

int

The monitor ID used to reference the monitor.

host_scheme_id

int

The ID of the server or authority this monitor will test.

user_ordering

int

The position of this monitor in the SpeedSentry Settings page. The first monitor by index will be 0.

path

str

The path in the URL that the monitor checks.

url

str

The full URL to be checked. This value combines the host/scheme and path entries.

method

str

The method used by the monitor to check the server. The value will be either “get”, “head”, “post”, “put”, “delete”, “options”, or “patch”.

content_check_mode

str

The content check mode to be employed by this monitor. The value will be one of “no_check”, “content_match”, “all_keywords”, or “any_keywords”.

keywords

list

A list of base-64 encoded keywords to be checked. The value is only meaningful if the content_check_mode value is “all_keywords” or “any_keywords”.

post_content_type

str

A value holding the “Content-Type” header value supplied with POST content. The supplied value will be one of “text”, “json”, or “xml”. The value is only meaningful if the method supports body content.

post_user_agent

str

A value holding the “User-Agent” header value supplied with POST content. The value is only used if the method supports body content.

post_content

str

A value holding the base-64 encoded body content. The value is only used if the method supports body content.

v1/monitors/update

You can use the v1/monitors/update endpoint to change monitor settings, including the host/schemes associated with your account.

The request message format for this endpoint is more involved than most other endpoints. Below is a simple example request message:

[
    { "uri" : "https://inesonic.com" },
    {
        "uri" : "/pricing",
        "content_check_mode" : "content_match"
    },
    {
        "uri" : "/product",
        "content_check_mode" : "all_keywords",
        "keywords" : [
            "Q29tcGlsZWQ=",
            "U2VsZiBEb2N1bWVudGluZw==",
            "SW50ZWdyYXRpb24=",
            "U3BlZWQ="
        ]
    },
    {
        "uri" : "/rest",
        "method" : "post",
        "post_content_type" : "json",
        "post_content" : "eyAiY3VzdG9tZXJfaWQiIDogMSwgI........8iIH0="
        "post_user_agent" : "Inesonic, LLC"
    }
]

The request should be a JSON array containing a dictionary for each monitor in the order they would be presented on the SpeedSentry Settings page.

Each entry must include a uri entry. All other values are optional and will take on default values if not specified. Table 27 explains each parameter.

Table 27 /v1/monitors/update/ Parameters

Key

Type

Default

Provides

uri

str

A full URL, including the scheme (“http:” or :https:”) and host, collectively called the authority to be monitors.

You can also provide a path on a server. If a path is provided then the path will be relative to the authority used by the previous entry.

The first entry in the array must always be a full URL. Note that this parameter is required.

method

str

“get”

A value indicates if the monitor should use HTTP GET or HTTP POST to check the endpoint. Supported values are “get”, “head”, “post”, “put”, “options”, “delete”, and “patch”.

content_check_mode

str

“no_check”

A value indicating if and how the monitored content should be checked. Supported values are “no_check”, “content_match”, “all_keywords”, and “any_keywords”.

  • “no_check” - Indicates that no content checking should be performed for this monitor.

  • “content_match” - Indicates that the content should be compared against the last returned content. Note that for performance reasons, content is checked by comparing salted cryptographic hashes.

  • “all_keywords” - Indicates that the content is scanned to confirm that all supplied keywords are present in the returned content. A keyword event will be reported if any keyword is missing.

  • “any_keywords” - Indicates that the content is scanned to confirm that at least one keyword is present in the returned content. A keyword event will be reported only if all keywords are missing.

keywords

list

empty list

A list of base-64 encoded keywords to be checked. This parameter will be ignored if the content_check_mode is “no_check” or “content_match”.

post_content_type

str

“text”

A value indicating the request Content-Type header value to be sent. Supported values are “text”, “json”, and “xml” corresponding to “text/plain”, “application/json”, and “application/xml” respectively.

The value will be ignored if the HTTP method does not support body content.

post_user_agent

str

“”

A string holding the request User-Agent header value to be sent. An empty string will cause the Inesonic, LLC default user agent string to be used.

The value will be ignored if the GET HTTP method does not support body content.

post_content

str

“”

A base-64 encoded string holding the HTTP POST content to be sent. The value will be ignored if the HTTP method does not support body content.

On success, the /v1/monitors/update endpoint will return the JSON response below:

{
    "status" : "OK"
}

On failure, the /v1/monitors/update endpoint will return a failed status and an errors parameter with a list of errors.

v1/events/get

You can use the v1/events/get endpoint to obtain information about a specific event.

The request message includes a single event_id parameter providing the numeric ID of the event.

{
    "event_id" : 3465
}

The response will be a JSON encoded dictionary containing the fields listed in Table 28.

Table 28 /v1/events/gets/ Parameters

Key

Type

Provides

status

str

The request status. Will hold “OK” on success.

event

dict

Dictionary holding details on the event.

event_id

int

The event ID of the requested event. The value will match the value provided in the request.

event_type

str

The event type for this event. The value will be one of:

  • working

  • no_response

  • content_changed

  • keywords

  • ssl_certificate_expiring

  • ssl_certificate_renewed

  • custom_1

  • custom_2

  • custom_3

  • custom_4

  • custom_5

  • custom_6

  • custom_7

  • custom_8

  • custom_9

  • custom_10

message

str

A message provided with the event that provides additional details.

monitor_id

int

The monitor ID of the monitor that triggered this event.

timestamp

int

The Unix timestamp indicating when this event was reported.

An example response payload is shown below:

{
    "event": {
        "event_id": 57,
        "event_type": "no_response",
        "message": "Host requires authentication",
        "monitor_id": 107,
        "timestamp": 1639199208
    },
    "status": "OK"
}

v1/events/list

You can use the v1/events/list endpoint to obtain a list of events. You can also request events over a specific timeframe.

The request message payload must be a JSON encoded dictionary. You can include an optional start_timestamp and/or end_timestamp parameter to obtain events over a specific timeframe.

The response will be a JSON encoded dictionary containing the fields listed in Table 29.

Table 29 /v1/events/list/ Parameters

Key

Type

Provides

status

str

The request status. Will hold “OK” on success.

events

list

A list of dictionary entries. Each entry represents a single event.

event_id

int

The event ID of the requested event. The value will match the value provided in the request.

event_type

str

The event type for this event. The value will be one of:

  • working

  • no_response

  • content_changed

  • keywords

  • ssl_certificate_expiring

  • ssl_certificate_renewed

  • custom_1

  • custom_2

  • custom_3

  • custom_4

  • custom_5

  • custom_6

  • custom_7

  • custom_8

  • custom_9

  • custom_10

message

str

A message provided with the event that provides additional details.

monitor_id

int

The monitor ID of the monitor that triggered this event.

timestamp

int

The Unix timestamp indicating when this event was reported.

An example response is shown below:

{
    "events": [
        {
            "event_id": 758,
            "event_type": "custom_2",
            "message": "Disk storage below 1GB",
            "monitor_id": 115,
            "timestamp": 1639279265
        },
        {
            "event_id": 859,
            "event_type": "no_response",
            "message": "Host defunct.inesonic.com not found",
            "monitor_id": 118,
            "timestamp": 1639285184
        },
        {
            "event_id": 860,
            "event_type": "no_response",
            "message": "Host requires authentication",
            "monitor_id": 117,
            "timestamp": 1639285222
        }
    ],
    "status": "OK"
}

v1/events/create

You can use the v1/events/create endpoint to trigger a custom event. When you issue a custom event, you will trigger notifications like other events.

Note

Inesonic, LLC limits voice phone calls to critical events such as a no response event or a content event. Less critical events such as a server working event will not generate voice calls. Custom events are included in the set of less critical events and thus will not generate voice calls.

The v1/events/create endpoint accepts a JSON encoded payload containing information about the event to be created. The JSON payload should contain the parameters listed in Table 30.

Table 30 /v1/events/create/ Parameters

Key

Type

Provides

type

int

The event type for this event. The value should be an integer value between 1 and 10 to custom event 1 through custom event 10 respecively.

monitor_id

int

The monitor ID of the monitor this event should be associated with. If excluded, the first monitor associated with the user will be used.

message

int

An optional message to be tied to this event.

Below is an example JSON encoded request.

{
    "type" : 2,
    "monitor_id" : 115,
    "message" : "Disk storage below 1GB"
}

The endpoint will return a JSON encoded response containing a status value. On success, status will contain “OK”.

v1/status/get

You can use the v1/status/get endpoint to determine the current status of a monitor. The endpoint accepts a single monitor_id parameter that holds the ID of the monitor to determine the status of.

{
    "monitor_id" : 118
}

The endpoint returns a dictionary holding a status value and a monitor_status value. On success, status will hold “OK” and the monitor_status endpoint will hold one fo the values in Table 31.

Table 31 /v1/status/get/ Parameters

monitor_status

Meaning

“working”

Indicates the monitor is working normally.

“unknown”

Indicates that no event for this monitor has been reported and either the monitor hasn’t been tested yet or has been tested and is working.

“failed”

Indicates that the end point tested by this monitor is returning an error status.

v1/status/list

You can use the v1/status/list endpoint to determine the current status of all monitors. The endpoint should receive an empty JSON dictionary.

The endpoint returns a dictionary containing a status value and a monitor_status value.

{
    "monitor_id" : 118
}

The endpoint returns a dictionary holding a status value and a monitor_status value. A status value will hold “OK” on success. The monitor_status value is a dictionary of monitor status values by monitor ID with status values listed in Table 31.

v1/multiple/list

The v1/multiple/list endpoint is intended primarily for use by the SpeedSentry WordPress plug-in. The endpoint accepts an empty JSON dictionary in the request and returns a dictionary containing the entries listed in Table 32.

Table 32 /v1/multiple/list Parameters

Dictionary Entry

Returns

status

Holds “OK” on success.

monitors

Holds a list of all monitors indexex by user order as returned by v1/monitors/list.

host_schemes

Holds a list of all host/schemes as returned by v1/hosts/lists.

events

Holds a list of events in chronological order as returned by v1/events/list.

monitor_status

Holds a dictionary of monitor status values matching the format returned by v1/status/list.

v1/latency/list

The v1/latency/list endpoint can be used to obtain raw latency values from a single monitor, all monitors tied to a given server, or all monitors under your account. You can also limit the returned data to be over a specific time span.

The v1/latency/list endpoint accepts a JSON encoded payload with the parameters listed in Table 33. All parameters have a default value so it is valid to provide an empty dictionary in the request.

Table 33 /v1/latency/list Parameters

Parameter

Function

start_timestamp

The Unix timestamp of the first requested latency value. If not specified, the starting value will be 0.

end_timestamp

The Unix timestamp of the last requested latency value. If not specified, the current time will be used.

region_id

The region ID of the region to limit values for. If not specified, then data for all regions will be supplied.

monitor_id

The monitor ID of the monitor to obtain latency data for. If not specified, then latency for all monitors will be supplied.

An example request message is shown below, requesting latency data for monitor 124, region 2 only and over the month of January 2022.

{
    "start_timestamp" : 1641020400,
    "end_timestamp" : 1643698800,
    "region_id" : 2,
    "monitor_id" : 124
}

On success, the v1/latency/list endpoint returns a message containing three values, a status value holding “OK”, a recent value holding a JSON list of recent latency values, and an aggregated value holding a JSON list of older, aggregated, values. On failure, only the status value is returned and will contain the failure reason.

The returned fields will be as documented in Table 34.

Table 34 /v1/latency/list Recent Return Values

Parameter

Type

Function

status

str

The return status value. Will contain “OK” on success.

recent

list

List of dictionaries of raw latency values. All raw values will be over the past month.

latency

float

The latency value in seconds.

monitor_id

int

The monitor ID of the monitor tied to this measurement.

region_id

int

The region ID of the polling server that took this measurement.

timestamp

int

The Unix timestamp indicating when the measurement was recorded.

aggregated

list

List of dictionaries of aggregated latency entries. Each entry was generated by aggregating raw values over one hour periods.

latency

float

A randomly sampled latency value from the original raw data used to create the aggregation. Value is in seconds.

monitor_id

int

The monitor ID of the monitor tied to this aggregation.

region_id

int

The region ID of the polling server that took the measurements in this aggregation.

timestamp

int

The Unix timestamp of the randomly sampled latency measurement.

average

float

The average or mean value of all the latency measurements taken over the time represented by this aggregation. Value is in seconds.

variance

float

The population variance of all the latency measurements taken over the tiem represented by this aggregation. Value is in seconds-squared.

minimum

float

The minimum latency found over the aggregation. Value is in seconds.

maximum

float

The maximum latency found over the aggregation. Value is in seconds.

number_samples

int

The number of raw samples that were used to make this aggregated entry.

start_timestamp

int

The Unix timestamp of the first entry in this aggregation.

end_timestamp

int

The Unix timestamp of the last entry in this aggregation.

A sample returned payload would look as shown below:

{
    "status" : "OK",
    "recent" : [
        {
             "latency" : 0.5521079999999999,
             "monitor_id" : 126,
             "region_id" : 2,
             "timestamp" : 1639867671
         },
         {
             "latency" : 0.489197,
             "monitor_id" : 116,
             "region_id" : 1,
             "timestamp" : 1639867701
         },
         {
             "latency" : 1.297456,
             "monitor_id" : 128,
             "region_id" : 1,
             "timestamp" : 1639867761
         },
         {
             "latency" : 0.9766819999999999,
             "monitor_id" : 126,
             "region_id" : 1,
             "timestamp" : 1639867821
         },
         ...
     ],
     "aggregated" : [
        {
             "latency" : 0.657468,
             "monitor_id" : 116,
             "region_id" : 1,
             "timestamp" : 1637933271
             "average" : 0.524765999999999,
             "variance" : 0.025743841,
             "start_timestamp" : 1637935071,
             "end_timestamp" : 1637936871
             "number_samples" : 119,
             "minimum" : 0.1476375,
             "maximum" : 1.247653825
         },
         {
             "latency" : 0.5247533,
             "monitor_id" : 126,
             "region_id" : 2,
             "timestamp" : 1637933314
             "average" : 0.4276538,
             "variance" : 0.01784256,
             "start_timestamp" : 1637935070,
             "end_timestamp" : 1637936869
             "number_samples" : 118,
             "minimum" : 0.12176548,
             "maximum" : 1.049675281
         },
         ...
     ]
}

v1/latency/plot

The v1/latency/plot endpoint can be used to generate both latency histogram plots and latency over time plots from latency data.

The endpoint accepts a JSON encoded request payload with parameters used to define the plot. On success the endpoint returns raw binary data in the requested format. On failure, the endpoint returns JSON encoded data. You can look at the response header “Content-Type” value to determine the type of the returned data.

Table Table 35 lists the parameters accepted in the JSON request. Note that most parameters have default values so, in many cases, only a few parameters are needed to create a presentable plot.

Table 35 /v1/latency/Plot Parameters

Parameter

Default

Type

Function

plot_type

“history”

str

The desired plot type. Accepted values are “history” and “histogram”.

host_scheme_id

-all-

int

The host/scheme ID to limit the source data to. All host/schemes (sites) will be used if this value is omitted. Do not include this parameter if monitor_id is used.

monitor_id

-all-

int

The monitor ID of the monitor to limit the source data to. If omitted, then all monitors will be used. Do not include this parameter if host_scheme_id is used.

region_id

-all-

int

The region to limit data to. If excluded, then data from all regions will be used.

start_timestamp

0

int

The starting Unix timestamp to limit data over. If omitted, then the starting time will not be used to limit data.

end_timestamp

now

int

The ending Unix timestamp to limit data over. If omitted then data will include everything up-to the curren ttime.

title

“Latency Over Time”

str

The title to place on the plot. The string can be UTF-8 encoded.

x_axis_label

“Date/Time”

str

The X axis label to place on the plot. The string can be UTF-8 encoded.

y_axis_label

“Latency (seconds)”

str

The Y axis label to place on the plot. The string can be UTF-8 encoded.

date_format

“MMM dd yyyy - hh:mm”

str

The format to use for date values. See Date Format Codes for information on how to encode date strings.

title_font

-default-

str

The title font to be used. See Font Encoding for details. A reasonable font will be selected if omitted.

axis_title_font

-default-

str

The Axis title font to be used. See Font Encoding for details. A reasonable font will be selected if omitted.

axis_label_font

-default-

str

The axis label font to be used. See Font Encoding for details. A reasonable font will be selected if omitted.

minimum_latency

0

float

The minimum latency value to be shown, in seconds. If omitted, then 0 is used.

maximum_latency

auto-scale

float

The maximum latency value to be shown, in seconds. If omitted, then the maximum value will be determined from the raw data.

log_scale

false

false

This value is only supported for history plots. If true Then the latency data will be presented using a logarithmic scale.

width

1024

int

The desired plot width, in pixels.

height

768

int

The desired plot height, in pixels.

format

“PNG”

str

The desired plot format. Supported values are “PNG” and “JPG”.

An example request message is shown below, this message will request a latency histogram plot for monitor 112 for measurements taken from region 2.

{
    "plot_type" : "histogram",
    "title" : "Latency For Monitor /products",
    "monitor_id" : 112,
    "region_id" : 2
}

On success the v1/latency/plot endpoint will return the plot in the requested format as raw binary data. On failure, the v1/latency/plot endpoint will return a JSON encoded payload with a single status field. The status field will give the reason for the failure.

Date Format Codes

The v1/latency/plot endpoint allows you to customize how date/time values are shown in “history” plots. You can describe a date field using the markers listed in Table 36 below.

Table 36 Date Format Parameters

Parameter

Converts To

d

The day of the month without a leading zero, e.g. 1, 2, …, 31.

dd

The day of the month with a leading zero, e.g. 01, 02, …, 31.

ddd

The abbreviated day name: Mon, Tue, Wed, …, Sun.

dddd

The long day name: Monday, Tuesday, Wedneday, …, Sunday.

M

The month number without a leading zero, e.g. 1, 2, …, 12.

MM

The month number with a leading zero, e.g. 01, 02, … 12.

MMM

The abbreviated month name: Jan, Feb, Mar, …, Dec.

MMMM

The long month name: January, February, March, …, December.

yy

The last two digits of the year., e.g.: 21, 22, etc.

yyyy

The year as a four digit number, e.g: 2021, 2022, etc.

h

The hour in 12 hour format without a leading zero., e.g. 1, 2, …, 12.

hh

The hour in 12 hour format with a leading zero., e.g. 01, 02, …, 12.

H

The hour in 24 hour format without a leading zero., e.g. 0, 1, 2, …, 23.

HH

The hour in 24 hour format with a leading zero., e.g. 00, 01, 02, …, 23.

m

The minute without a leading zero, e.g. 0, 1, 2, …, 59.

mm

the minute with a leading zero, e.g. 00, 01, 02, …, 59.

s

The whole seconds without a leading zero, e.g. 0, 1, 2, …, 59.

ss

The whole seconds with a leading zero, e.g. 00, 01, 02, …, 59.

AP

AM or PM.

ap

am or pm.

As an example, For 3:56:24 PM March 3, 2022, the date format string “dd-MMM-yyyy HH:mm:ss” would display “03-Mar-2022 15:56:24”.

Font Encoding

You can control the font used for several plot elements using a font string. The font string accepts 2 or 3 comma separated parameters.

The first parameter should be the font family. We support a number of common open-source fonts and can identify close equivalents for generic fonts such as “Arial” or “Helvetica”.

The second parameter is the font size in points.

The third parameter is optional and can be used to specify a font weight. Supported values are “light”, “normal”, and “bold”.

As an example, to select a Courier 10 point boldfaced font, you would use the font string “Courier,10,bold”. A normal 12 point Helvetica font would be “Helvetica,12”.

v1/customer/pause

The v1/customer/pause endpoint can be used to pause and resume monitoring, placing your account into and out of maintenance mode. The endpoint accepts a single pause parameter that can be true to pause monitoring or false to resume monitoring.

The endpoint returns a JSON response containing a single status field. A status of “OK” is returned on success or “failed” on failure.