Clotho Time Series API

Use the Clotho Time Series API to insert data into, retrieve information from, and to run transforms against a MetricBase database.

These APIs can only be used when the MetricBase application is installed and activated.

Clotho Time Series API - GET now/v1/clotho/table/{table}/{subject}/{metric}

Retrieve time series data from the MetricBase database.

URL format

Versioned URL: api/now/v1/clotho/table/{table}/{subject}/{metric}

The URL parameters.
  • table - Name of the table containing the GlideRecord associated with this series.
  • subject - The sys_id of the GlideRecord associated with this series.
  • metric - The field name of the metric.

Supported request parameters

Table 1. Parameters
Parameter Description
sysparm_start The start time of the evaluation period in UTC. The value must be in ISO date format up to seconds. For example, 2017-03-20T17:04:55.
sysparm_end The end time of the evaluation period in UTC. The value must be in ISO date format up to seconds. For example, 2017-03-20T17:04:55.
sysparm_display_value Optional. If true, the result data is labeled with the subject record display value.

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 2. Request headers
Header Description
None
Table 3. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST response codes .

Table 4. Status codes
Status code Description
None

Response body

The API returns a JSON object or an array of JSON objects. The format of the JSON object is in this form, where
  • seriesRef- defines the table, record, and metric.
  • subject- the sys_id of the specific record in the table.
  • table- the name of the table containing the record.
  • metric- the metric field name.
  • values- the individual data points, consisting of a time and value.
{"seriesRef":{"subject":"xxx","table:"yyy","metric":"zzz"}, 
"values":[{"timestamp":"2016-10-14T10:30:00", "value":1.23},
          {"timestamp":"2016-10-14T10:31:00", "value":6.45}]}

Clotho Time Series API - GET now/v1/clotho/transform/{table}/{metric}

This method performs the specified transform on the selected data.

URL format

Versioned URL: /api/now/v1/clotho/transform/{table}/{metric}

The URL parameters:
  • table- Name of the table containing the GlideRecord associated with this series.
  • metric- The field name of the metric.

Supported request parameters

Table 5. Parameters
Parameter Description
sysparm_query An encoded query string for finding the subject records.
sysparm_start The start time of the evaluation period in UTC. The value must be in ISO date format up to seconds. For example, 2017-03-20T17:04:55.
sysparm_end The end time of the evaluation period in UTC. The value must be in ISO date format up to seconds. For example, 2017-03-20T17:04:55.
sysparm_transforms Optional. A comma separated list of transforms. Supported transforms are avg, sum, add, mul, resample, top, label.
sysparm_subject_limit Optional. Limit the size of the subject query result. The default is 10,000.
sysparm_display_value Optional. When true, the result data will be labeled with the subject record display value if no other label is specified in the transform. The default is false.

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 6. Request headers
Header Description
None
Table 7. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST response codes .

Table 8. Status codes
Status code Description
None

Response body

The API returns a JSON object or an array of JSON objects. The format of the JSON object is in this form, where
  • seriesRef- defines the table, record, and metric.
  • subject- the sys_id of the specific record in the table.
  • table- the name of the table containing the record.
  • metric- the metric field name.
  • values- the individual data points, consisting of a time and value.
{"seriesRef":{"subject":"xxx","table:"yyy","metric":"zzz"}, 
"values":[{"timestamp":"2016-10-14T10:30:00", "value":1.23},
          {"timestamp":"2016-10-14T10:31:00", "value":6.45}]}

Clotho Time Series API - POST now/v1/clotho/put

Adds a data series to the MetricBase database.

URL format

Versioned URL: api/now/v1/clotho/put

Supported request parameters

Table 9. Parameters
Parameter Description
sysparm_ignore_unknown_series Optional. If true, ignore unknown series and continue the transaction without returning an error. The default is true.

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 10. Request headers
Header Description
None
Table 11. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST response codes .

Table 12. Status codes
Status code Description
None

Request body

The API returns a JSON object or an array of JSON objects. The format of the JSON object is in this form, where
  • seriesRef- defines the table, record, and metric.
  • subject- the sys_id of the specific record in the table.
  • table- the name of the table containing the record.
  • metric- the metric field name.
  • values- the individual data points, consisting of a time and value.
{"seriesRef":{"subject":"xxx","table:"yyy","metric":"zzz"}, 
"values":[{"timestamp":"2016-10-14T10:30:00", "value":1.23},
          {"timestamp":"2016-10-14T10:31:00", "value":6.45}]}
An example of an array of JSON objects.
[{"seriesRef":{"subject":"xxx","table:"yyy","metric":"zzz"}, 
"values":[{"timestamp":"2016-10-14T10:30:00", "value":1.23},
          {"timestamp":"2016-10-14T10:31:00", "value":6.45}]},
 ...]