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.
Group |
Function |
---|---|
|
You can use the endpoints in this group to determine the features that are available under your subscription. |
|
You can use the endpoints in this group to obtain information about a single geographic location your site or sites are being monitored from. |
|
You can use the endpoints in this group to obtain details about each site being monitored. |
|
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. |
|
You can use the endpoints in this group to obtain
event history for your site. You can also generate
custom events using the |
|
You can use the endpoints in this group to obtain the current status of the pages, slugs, or endpoints being monitored. |
|
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. |
|
You can use the |
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.
Field |
Type |
Provides |
---|---|---|
|
str |
Holds a string containing |
|
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. |
|
int |
Holds the maximum number of monitors that can be configured under your subscription. |
|
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. |
|
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 |
|
int |
Holds the per-site polling interval, in seconds. |
|
bool |
Holds true if your subscription allows you to use the SpeedSentry content checking feature. |
|
bool |
Holds true if your subscription allows you to use the SpeedSentry keyword checking feature. |
|
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. |
|
bool |
Holds true if your subscription supports the maintenance mode function. |
|
bool |
Holds true if your subscription includes using ICMP echo or ping messages on servers that support them to reduce response time. |
|
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. |
|
bool |
Holds true if the full REST API is supported. If false, only a limited number of REST API functions are available. |
|
bool |
Holds true if SSL certificate expiration checking is supported. If false, we do not check SSL certificate expiration. |
|
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. |
|
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.
Field |
Type |
Provides |
---|---|---|
|
str |
Holds a string containing |
|
str |
Holds a textual description of the region. |
|
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.
Field |
Type |
Provides |
|
---|---|---|---|
|
str |
Holds a string containing |
|
|
dict |
Dictionary containing information about each region, keyed by region ID. |
|
|
str |
Holds a textual description of the region. |
|
|
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.
Field |
Type |
Provides |
---|---|---|
|
str |
Holds a string containing |
|
int |
The numeric ID used to identify the host. |
|
str |
A string containing the authority used to communicate with the host.
The authority will contain the scheme or protocol ( |
|
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.
Field |
Type |
Provides |
|
---|---|---|---|
|
str |
Holds a string containing |
|
|
dict |
A dictionary of host/scheme data by host/scheme ID. |
|
|
int |
The numeric ID used to identify the host. |
|
|
str |
A string containing the authority used to communicate
with the host. The authority will contain the scheme
or protocol ( |
|
|
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.
Field |
Type |
Provides |
---|---|---|
|
str |
Holds a string containing |
|
int |
A numeric ID used to reference this monitor. |
|
int |
A zero based index indicating the relative ordering of the monitors in the “Account Settings” page of our website. |
|
str |
The path under the host/scheme to be checked. |
|
int |
The ID of the host/scheme that this monitor is operating under. For details, see Hosts Group. Between the |
|
str |
The HTTP method used to access the page or end point. Returned value will be “get”, “head”, “post”, “put”, “delete”, “options”, or “patch”. |
|
str |
The content check mode this monitor is using. Returned values will be one of:
|
|
list |
A list of keyword strings to be scanned for. The value is used only
if To support binary data and arbitrary character encodings, each entry will be base-64 encoded. |
|
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. |
|
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. |
|
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:
Value |
Provides |
---|---|
“monitor_id” |
Commands the |
“user_ordering” |
Commands the |
“url” |
Commands the |
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.
Field |
Type |
Provides |
|
---|---|---|---|
|
str |
Holds a string containing |
|
|
dict |
Holds a dictionary of monitor entries indexed by monitor ID, user ordering, or URL. |
|
|
int |
The monitor ID used to reference the monitor. |
|
|
int |
The ID of the server or authority this monitor will test. |
|
|
int |
The position of this monitor in the SpeedSentry Settings page. The first monitor by index will be 0. |
|
|
str |
The path in the URL that the monitor checks. |
|
|
str |
The full URL to be checked. This value combines the host/scheme and path entries. |
|
|
str |
The method used by the monitor to check the server. The value will be either “get”, “head”, “post”, “put”, “delete”, “options”, or “patch”. |
|
|
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”. |
|
|
list |
A list of base-64 encoded keywords to be checked. The value is only
meaningful if the |
|
|
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 |
|
|
str |
A value holding the “User-Agent” header value supplied with POST
content. The value is only used if the |
|
|
str |
A value holding the base-64 encoded body content. The value is only
used if the |
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.
Key |
Type |
Default |
Provides |
---|---|---|---|
|
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. |
|
|
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”. |
|
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”.
|
|
list |
empty list |
A list of base-64 encoded keywords to be checked. This parameter
will be ignored if the |
|
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. |
|
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. |
|
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.
Key |
Type |
Provides |
|
---|---|---|---|
|
str |
The request status. Will hold “OK” on success. |
|
|
dict |
Dictionary holding details on the event. |
|
|
int |
The event ID of the requested event. The value will match the value provided in the request. |
|
|
str |
The event type for this event. The value will be one of:
|
|
|
str |
A message provided with the event that provides additional details. |
|
|
int |
The monitor ID of the monitor that triggered this event. |
|
|
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.
Key |
Type |
Provides |
|
---|---|---|---|
|
str |
The request status. Will hold “OK” on success. |
|
|
list |
A list of dictionary entries. Each entry represents a single event. |
|
|
int |
The event ID of the requested event. The value will match the value provided in the request. |
|
|
str |
The event type for this event. The value will be one of:
|
|
|
str |
A message provided with the event that provides additional details. |
|
|
int |
The monitor ID of the monitor that triggered this event. |
|
|
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.
Key |
Type |
Provides |
---|---|---|
|
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. |
|
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. |
|
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.
|
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.
Dictionary Entry |
Returns |
---|---|
|
Holds “OK” on success. |
|
Holds a list of all monitors indexex by user order
as returned by |
|
Holds a list of all host/schemes as returned by
|
|
Holds a list of events in chronological order as
returned by |
|
Holds a dictionary of monitor status values
matching the format returned by |
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.
Parameter |
Function |
---|---|
|
The Unix timestamp of the first requested latency value. If not specified, the starting value will be 0. |
|
The Unix timestamp of the last requested latency value. If not specified, the current time will be used. |
|
The region ID of the region to limit values for. If not specified, then data for all regions will be supplied. |
|
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.
Parameter |
Type |
Function |
|
---|---|---|---|
|
str |
The return status value. Will contain “OK” on success. |
|
|
list |
List of dictionaries of raw latency values. All raw values will be over the past month. |
|
|
float |
The latency value in seconds. |
|
|
int |
The monitor ID of the monitor tied to this measurement. |
|
|
int |
The region ID of the polling server that took this measurement. |
|
|
int |
The Unix timestamp indicating when the measurement was recorded. |
|
|
list |
List of dictionaries of aggregated latency entries. Each entry was generated by aggregating raw values over one hour periods. |
|
|
float |
A randomly sampled latency value from the original raw data used to create the aggregation. Value is in seconds. |
|
|
int |
The monitor ID of the monitor tied to this aggregation. |
|
|
int |
The region ID of the polling server that took the measurements in this aggregation. |
|
|
int |
The Unix timestamp of the randomly sampled latency measurement. |
|
|
float |
The average or mean value of all the latency measurements taken over the time represented by this aggregation. Value is in seconds. |
|
|
float |
The population variance of all the latency measurements taken over the tiem represented by this aggregation. Value is in seconds-squared. |
|
|
float |
The minimum latency found over the aggregation. Value is in seconds. |
|
|
float |
The maximum latency found over the aggregation. Value is in seconds. |
|
|
int |
The number of raw samples that were used to make this aggregated entry. |
|
|
int |
The Unix timestamp of the first entry in this aggregation. |
|
|
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.
Parameter |
Default |
Type |
Function |
---|---|---|---|
|
“history” |
str |
The desired plot type. Accepted values are “history” and “histogram”. |
|
-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 |
|
-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 |
|
-all- |
int |
The region to limit data to. If excluded, then data from all regions will be used. |
|
0 |
int |
The starting Unix timestamp to limit data over. If omitted, then the starting time will not be used to limit data. |
|
now |
int |
The ending Unix timestamp to limit data over. If omitted then data will include everything up-to the curren ttime. |
|
“Latency Over Time” |
str |
The title to place on the plot. The string can be UTF-8 encoded. |
|
“Date/Time” |
str |
The X axis label to place on the plot. The string can be UTF-8 encoded. |
|
“Latency (seconds)” |
str |
The Y axis label to place on the plot. The string can be UTF-8 encoded. |
|
“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. |
|
-default- |
str |
The title font to be used. See Font Encoding for details. A reasonable font will be selected if omitted. |
|
-default- |
str |
The Axis title font to be used. See Font Encoding for details. A reasonable font will be selected if omitted. |
|
-default- |
str |
The axis label font to be used. See Font Encoding for details. A reasonable font will be selected if omitted. |
|
0 |
float |
The minimum latency value to be shown, in seconds. If omitted, then 0 is used. |
|
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. |
|
false |
false |
This value is only supported for history plots. If true Then the latency data will be presented using a logarithmic scale. |
|
1024 |
int |
The desired plot width, in pixels. |
|
768 |
int |
The desired plot height, in pixels. |
|
“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.
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.