MetricBase Time Series API

Release version: Xanadu

Updated August 1, 2024

53 minutes to read

The MetricBase Time Series API provides endpoints to insert data into, retrieve information from, and to run transforms against a MetricBase database.

This API can only be used when the MetricBase plugin (com.snc.clotho) is installed and activated.

Role required to write to this API: clotho_rest_put.

The examples in this section were created using data in the MetricBase (com.snc.clotho) plugin.

MetricBase Time Series - GET /now/clotho/table/{table}/{subject}/{metric}

Retrieves specified time series data from the MetricBase database.

URL format

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

Supported request parameters

Table 1. Path parameters
Name	Description
api_version
metric	Name of the column in the table identified in the subject parameter to use as the metric. Data type: String
subject	Sys_id of the GlideRecord associated with this series. Data type: String
table	Name of the table containing the GlideRecord associated with this series. Data type: String

Table 2. Query parameters
Name	Description
sysparm_display_value	Flag that indicates whether to label the result data with the subject record display value if no other label is specified. Valid values: true: Result data is labeled with the subject record display value. false: Result data is not labeled with the subject record display value. Data type: Boolean Default: false
sysparm_end	Required. End time of the evaluation period. An empty or missing value is treated as the current time. Time values are inclusive of this end time. Data type: String Format: ISO 8601 (UTC), either: Absolute date format [YYYY-MM-DDThh:mm:ss], such as `2019-03-20T17:04:55`. Relative to current time duration format `[P(n)Y(n)M(n)DT(n)H(n)M(n)S]`, such as `P1M`.
sysparm_start	Required. Start time of the evaluation period. The special value `all` can be used to set the start time as the current time minus the maximum retention period for the specified metrics. An empty or missing value is treated as an implicit `all`. Time values are inclusive of this start time. Data type: String Format: ISO 8601 (UTC), either: Absolute date format [YYYY-MM-DDThh:mm:ss], such as `2019-03-20T17:04:55` Relative to current time duration format `[P(n)Y(n)M(n)DT(n)H(n)M(n)S]`, such as `P1M`.

Table 3. Request body parameters (XML or JSON)
Name	Description
None

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 4. Request headers
Header	Description
Accept	Data format of the response body. Only supports application/json.

Table 5. 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 API HTTP response codes.

Table 6. Status codes
Status code	Description
200	Successful. The request was successfully processed.
401	Unauthorized. The user credentials are incorrect or have not been passed.
500	Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

Response body parameters (JSON or XML)


Name	Description
label	The label used to identify this metric’s result set. Data type: String
seriesRef	Data series results. Data type: Array `"seriesRef": [ { "metric": "String", "subject": "String", "table": "String" } ]`
seriesRef.metric	The name of the metric from which the data series was obtained. Only appears if the metrics object is passed in the request. Data type: String
seriesRef.subject	The sys_id of the data series record. Located in the table specified in seriesRef.table. Data type: String
seriesRef.table	The name of the table from where the data series was obtained. Data type: String
values	The transformed series values. Data type: Array `"values": [ { "timestamp": "String", "value": Number } ]`
values.timestamp	The ISO 8601 timestamp of the value. Data type: String
values.value	The metric values. Data type: Number

cURL request

curl "https://instance.servicenow.com/api/now/v1/clotho/
  table/mb_demo_drone/626b051787333200a328c5b836cb0b99/
  mb_demo_mt_altitude?sysparm_start=2019-03-20T17%3A04%3A55
  &sysparm_end=2019-03-20T17%3A09%3A55" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

{
  "seriesRef": {
    "subject": "626b051787333200a328c5b836cb0b99",
    "table": "mb_demo_drone",
    "metric": "mb_demo_mt_altitude"
  },
  "label": "626b051787333200a328c5b836cb0b99:
            mb_demo_drone|mb_demo_mt_altitude",
  "values": [
    {
      "timestamp": "2019-03-20T17:05:00Z",
      "value": 83.150185
    },
    {
      "timestamp": "2019-03-20T17:06:00Z",
      "value": 83.46074
    },
    {
      "timestamp": "2019-03-20T17:07:00Z",
      "value": 83.83104
    },
    {
      "timestamp": "2019-03-20T17:08:00Z",
      "value": 84.260635
    },
    {
      "timestamp": "2019-03-20T17:09:00Z",
      "value": 84.749
    }
  ]
}

MetricBase Time Series - GET /now/clotho/transform/{table}/{metric}

Transforms the specified data based on the specified parameters.

URL format

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

Supported request parameters

Table 7. Path parameters
Name	Description
api_version
metric	Name of the column in the table identified in the subject parameter to use as the metric. Data type: String
table	Name of the table containing the GlideRecord associated with this series. Data type: String

Table 8. Query parameters
Name	Description
sysparm_display_value	Flag that indicates whether to label the result data with the subject record display value if no other label is specified. Valid values: true: Result data is labeled with the subject record display value. false: Result data is not labeled with the subject record display value. Data type: Boolean Default: false
sysparm_end	Required. End time of the evaluation period. An empty or missing value is treated as the current time. Time values are inclusive of this end time. Data type: String Format: ISO 8601 (UTC), either: Absolute date format [YYYY-MM-DDThh:mm:ss], such as `2019-03-20T17:04:55`. Relative to current time duration format `[P(n)Y(n)M(n)DT(n)H(n)M(n)S]`, such as `P1M`.
sysparm_query	Encoded query string for finding the subject records. Data type: String Default: None
sysparm_start	Required. Start time of the evaluation period. The special value `all` can be used to set the start time as the current time minus the maximum retention period for the specified metrics. An empty or missing value is treated as an implicit `all`. Time values are inclusive of this start time. Data type: String Format: ISO 8601 (UTC), either: Absolute date format [YYYY-MM-DDThh:mm:ss], such as `2019-03-20T17:04:55` Relative to current time duration format `[P(n)Y(n)M(n)DT(n)H(n)M(n)S]`, such as `P1M`.
sysparm_subject_limit	Limit size of the subject query result. Data type: Number Default: 10,000
sysparm_transforms	Comma separated list of transforms. Valid transforms: add avg label mul resample sum top Data type: String Default: None

Table 9. Request body parameters (XML or JSON)
Name	Description
None

Headers

Table 10. Request headers
Header	Description
Accept	Data format of the response body. Supported types: application/json or application/xml. Default: application/json

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 API HTTP response codes.

Table 12. Status codes
Status code	Description
200	Successful. The request was successfully processed.
401	Unauthorized. The user credentials are incorrect or have not been passed.
500	Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

Response body parameters (JSON or XML)


Name	Description
label	The label used to identify this metric’s result set. Data type: String
seriesRef	Data series results. Data type: Array `"seriesRef": [ { "metric": "String", "subject": "String", "table": "String" } ]`
seriesRef.metric	The name of the metric from which the data series was obtained. Only appears if the metrics object is passed in the request. Data type: String
seriesRef.subject	The sys_id of the data series record. Located in the table specified in seriesRef.table. Data type: String
seriesRef.table	The name of the table from where the data series was obtained. Data type: String
values	The transformed series values. Data type: Array `"values": [ { "timestamp": "String", "value": Number } ]`
values.timestamp	The ISO 8601 timestamp of the value. Data type: String
values.value	The metric values. Data type: Number

cURL request

curl "https://instance.servicenow.com/api/now/v1/clotho/
  transform/mb_demo_drone/mb_demo_mt_speed?
  sysparm_query=model%3DKingfisher%20Phantom&
  sysparm_start=2019-03-25T17%3A04%3A55&
  sysparm_end=2019-03-25T17%3A05%3A10" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

Output:

[
  {
    "seriesRef": {
      "subject": "2a6b051787333200a328c5b836cb0b92",
      "table": "mb_demo_drone",
      "metric": "mb_demo_mt_speed"
    },
    "label": "2a6b051787333200a328c5b836cb0b92:mb_demo_drone
             |mb_demo_mt_speed",
    "values": [
      {
        "timestamp": "2019-03-25T17:05:00Z",
        "value": 33.67892
      }
    ]
  },
  {
    "seriesRef": {
      "subject": "666b051787333200a328c5b836cb0b92",
      "table": "mb_demo_drone",
      "metric": "mb_demo_mt_speed"
    },
    "label": "666b051787333200a328c5b836cb0b92:mb_demo_drone
             |mb_demo_mt_speed",
    "values": [
      {
        "timestamp": "2019-03-25T17:05:00Z",
        "value": 41.94985
      }
    ]
  },
  {
    "seriesRef": {
      "subject": "a26b051787333200a328c5b836cb0b92",
      "table": "mb_demo_drone",
      "metric": "mb_demo_mt_speed"
    },
    "label": "a26b051787333200a328c5b836cb0b92:mb_demo_drone
             |mb_demo_mt_speed",
    "values": [
      {
        "timestamp": "2019-03-25T17:05:00Z",
        "value": 37.74187
      }
    ]
  },
  {
    "seriesRef": {
      "subject": "ea6b051787333200a328c5b836cb0b92",
      "table": "mb_demo_drone",
      "metric": "mb_demo_mt_speed"
    },
    "label": "ea6b051787333200a328c5b836cb0b92:mb_demo_drone
             |mb_demo_mt_speed",
    "values": [
      {
        "timestamp": "2019-03-25T17:05:00Z",
        "value": 34.914192
      }
    ]
  },
  {
    "seriesRef": {
      "subject": "ee6b051787333200a328c5b836cb0b91",
      "table": "mb_demo_drone",
      "metric": "mb_demo_mt_speed"
    },
    "label": "ee6b051787333200a328c5b836cb0b91:mb_demo_drone
             |mb_demo_mt_speed",
    "values": [
      {
        "timestamp": "2019-03-25T17:05:00Z",
        "value": 44.170887
      }
    ]
  }
]

MetricBase Time Series - POST /now/clotho/accumulate

Accumulates metric values at specified timestamp and saves the result to the database rather than overwriting the value.

Use this API to handle metrics that can be summed for an accumulation, such as kilowatt-hours (kWhs) of electricity. Accumulate makes a call for each metric at the provided timestamp. For example, collected kilowatts for a heater, electric kettle, and washing machine would result in three calls to accumulate.

URL format

Versioned URL: /api/now/{api_version}/clotho/accumulate

Supported request parameters

Table 13. Path parameters
Name	Description
api_version	Optional. Version of the endpoint to access. For example, `v1` or `v2`. Only specify this value to use an endpoint version other than the latest. Data type: String

Table 14. Query parameters
Name	Description
default_value	Default value for accumulation at a given timestamp. Used only during the first call to accumulate if a value is unavailable for a given timestamp. A use case could be accumulating a watts metric for a total_power. You want to accumulate watts for a router connected to an outlet without a power meter to measure it. If you know the consumption value and it is constant), you can use the constant value as a default value to accumulate total_power. For example, you would use 20 if the router is constantly plugged in and consumes 20 Watts. Data type: String Default: 0
sysparm_ignore_unknown_series	Flag that indicates whether to ignore an unknown series and continue the transaction without returning an error. Valid values: true: Ignore unknown series. false: Do not ignore unknown series. Default: true

Table 15. Request body parameters (XML or JSON)
Name	Description
seriesRef	List of strings representing data series information to update. Data type: Array `"seriesRef": [ { "metric": "String", "subject": "String", "table": "String" } ]`
seriesRef.metric	Required. The name of the accumulating metric to update. Data type: String
seriesRef.subject	Required. The sys_id of the record in which to update the data. Located in the table specified in seriesRef.table. Data type: String
seriesRef.table	Required. The name of the table in which to save the data. Data type: String
values	Required. The series values to accumulate and store. Values with the same timestamp are summed up with the default_value query parameter. Data type: Array `"values": [ { "timestamp": "String", "value": Number } ]`
values.timestamp	Required. The ISO 8601 timestamp of the value. Data type: String Format: YYYY-MM-ddTHH:mm:ddZ The character represented by 'Z' denotes the UTC time zone in an ISO-formatted timestamp. This portion of the timestamp format is optional. Example: `2019-03-21T17:05:00Z`
values.value	Required. The metric value. Data type: Number

Headers

Table 16. Request headers
Header	Description
Accept	Data format of the response body. Only supports application/json.
Content-Type	Data format of the request body. Only supports application/json.

Table 17. 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 API HTTP response codes.

Table 18. Status codes
Status code	Description
200	Successful. The request was successfully processed.
401	Unauthorized. The user credentials are incorrect or have not been passed.
500	Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

Response body parameters (JSON or XML)


Name	Description
message	Message indicating success (OK) or error.

cURL request

This example shows how to accumulate metric values at a given timestamp.

curl "https://instance.servicenow.com/api/now/v1/clotho/accumulate" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  \"seriesRef\": {
    \"subject\": \"3D666b051787333200a328c5b836cb0b92\",
    \"table\": \"power_monitoring\",
    \"metric\": \"total_power\"
  },
  \"values\": [
    {
      \"timestamp\": \"2019-03-21T17:05:00Z\",
      \"value\": 0.150185
    },
    {
      \"timestamp\": \"2019-03-21T17:05:00Z \",
      \"value\": 0.46074
    },
    {
      \"timestamp\": \"2019-03-21T17:05:00Z \",
      \"value\": 0.83104
    },
    {
      \"timestamp\": \"2019-03-21T17:05:00Z \",
      \"value\": 1.260635
    },
    {
      \"timestamp\": \"2019-03-21T17:05:00Z \",
      \"value\": 1.749
    }
  ]
}" \
--user "username":"password"

Output provided with successful results.

{
    "result": {
        "message": "ok"
    }
}

MetricBase Time Series - POST /now/clotho/transform

Retrieves and optionally groups time series data for one or more metrics after applying a specified list of transforms that form a linear pipeline.

URL format

Versioned URL: /api/now/{api_version}/clotho/transform

Supported request parameters

Table 19. Path parameters
Name	Description
api_version	Optional. Version of the endpoint to access. For example, `v1` or `v2`. Only specify this value to use an endpoint version other than the latest. Data type: String

Table 20. Query parameters
Name	Description
sysparm_display_value	Flag that indicates whether to label the result data with the subject record display value if no other label is specified. Valid values: true: Result data is labeled with the subject record display value. false: Result data is not labeled with the subject record display value. Data type: Boolean Default: false

Table 21. Request body parameters (XML or JSON)
Name	Description
end	Required. End time of the evaluation period. An empty or missing value is treated as the current time. Time values are inclusive of this end time. Data type: String Format: ISO 8601 (UTC), either: Absolute date format [YYYY-MM-DDThh:mm:ss], such as `2019-03-20T17:04:55`. Relative to current time duration format `[P(n)Y(n)M(n)DT(n)H(n)M(n)S]`, such as `P1M`.
limit	Maximum number of records to return. Unusually large values can impact system performance. Data type: Number Default: 10,000
metrics	List of metrics objects to use in the transform. For more information on metrics, see Metrics. Data type: Array `"metrics": [ { "groupBy": "String" "label": "String", "metric": "String", "transforms": [Array] } ]`
metrics.groupBy	Comma-separated list of fields, contained in the table specified in the table parameter, to group the series by before collecting or applying aggregated transformations. The order of the items in the list is the order in which the data is grouped by. For example, if there are two items in the list, "state, zip code", then the series is first grouped by state and then by zip code within the state. Data type: String Default: Data is not grouped.
metrics.label	Label to use for this metric’s result set. It replaces any labels generated by the transform chain. Data type: String Default: Generated default label.
metrics.metric	Required if metrics object is passed. Metric field to use in the transform. This field must be in the table specified in the table parameter. Data type: String
metrics.transforms	List of transforms (transform chain) to apply to the retrieved time series data. Each transform builds on the results of the previous transform. For a list of available transforms, see Supported Transforms below. Data type: Array `"transforms": [ { "arg": {Object}, "name": "String" } ]`
metrics.transforms.arg	Dependent on the transform. Parameter or parameters to pass into the transform. General guidelines: Do not use the arg parameter when specifying transformations that do not take a parameter. Use Number, String, or Boolean for transforms that take a single parameter. Use a JSON object, with the appropriate name-value pairs, for transforms that take more than one parameter. Data type: Number, String, Boolean, or JSON object, depending on transform. (For a list of available transforms, refer to the table Supported transforms below.)
metrics.transforms.name	Required if a transforms object is specified. Name of the transform. For a list of available transforms, refer to the table Supported transforms below. Data type: String
query	Encoded query to use to filter the result set. You can compose the query using the specified table’s filter editor. Once created, select Copy URL from the filter’s breadcrumbs context menu. Data type: String Default: None
start	Required. Start time of the evaluation period. The special value `all` can be used to set the start time as the current time minus the maximum retention period for the specified metrics. An empty or missing value is treated as an implicit `all`. Time values are inclusive of this start time. Data type: String Format: ISO 8601 (UTC), either: Absolute date format [YYYY-MM-DDThh:mm:ss], such as `2019-03-20T17:04:55` Relative to current time duration format `[P(n)Y(n)M(n)DT(n)H(n)M(n)S]`, such as `P1M`.
table	Required. Name of the table that contains the GlideRecord associated with this series. Data type: String

Headers

Table 22. Request headers
Header	Description
Accept	Data format of the response body. Only supports application/json.
Content-Type	Data format of the request body. Only supports application/json.

Table 23. 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 API HTTP response codes.

Table 24. Status codes
Status code	Description
200	Successful. The request was successfully processed.
400	Bad Request. A bad request type or malformed request was detected.
401	Unauthorized. The user credentials are incorrect or have not been passed.
404	Not found. The requested item wasn't found.
405	Invalid method. The functionality is disabled.
500	Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

Response body parameters (JSON or XML)


Name	Description
results	Zero or more return result objects that satisfy the query. Contains either a series array or a grouped array. Data type: Array `"results":[ { "grouped": [Array], "marker": "String", "series": [Array] } ]`
results.grouped	List of grouped result objects where each grouped result object corresponds to a specific group. This format is returned when the metrics.groupBy parameter is passed in the request body. Data type: Array `"grouped": [ { "groupingBy": "String", "groups": [Array] } ]`
results.grouped.groupingBy	Value passed in the metrics.groupBy parameter in the request. Data type: String
results.grouped.groups	List of generated groups based on the content of the metrics.groupBy parameter in the request. Data type: Array `"groups": [ { "group": "String", "label": "String", "series": {Object} } ]`
results.grouped.groups.group	Name of the group. Data type: String
results.grouped.groups.label	Label of the group. Data type: String
results.grouped.groups.series	Transformed values for the group's result. Data type: Array `"series": [ { "label": "String", "seriesRef": {Object}, "values": [Array] } ]`
results.grouped.groups.series.label	Label of the series. Data type: String
results.grouped.groups.series.seriesRef	Results of a single data series. Does not appear if there are multiple data series in the response. Data type: Object `"seriesRef": { "metric": "String", "subject": "String", "table": "String" }`
results.grouped.groups.series.seriesRef.metric	Name of the metric from which the data series was obtained. Only appears if the metrics object is passed in the request. Data type: String
results.grouped.groups.series.seriesRef.subject	Sys_id of the data series record. Located in the table specified in results.series.seriesRef.table. Data type: String
results.grouped.groups.series.seriesRef.table	Name of the table from where the data series was obtained. Data type: String
results.grouped.groups.series.values	List of result values for the group. Data type: Array `"values": [ { "timestamp": "String", "value": Number } ]`
results.grouped.groups.series.values.timestamp	ISO 8601 timestamp of the value. Data type: String
results.grouped.groups.series.values.value	Transformed value. Data type: Number
results.marker	Unique identifier for the corresponding results. Data type: String
results.series	List of ungrouped series of result objects. Data type: Array `"series": [ { "label": "String", "seriesRef": {Object}, "values": [Array] } ]`
results.series.label	Data series label. This value is either generated by the endpoint or is the value passed in the metrics.label parameter. Data type: String
results.series.seriesRef	Results of a single data series. Does not appear if there are multiple data series in the response. Data type: Object `"seriesRef": { "metric": "String", "subject": "String", "table": "String" }`
results.series.seriesRef.metric	Name of the metric from which the data series was obtained. Only appears if the metrics object is passed in the request. Data type: String
results.series.seriesRef.subject	Sys_id of the data series record. Located in the table specified in results.series.seriesRef.table. Data type: String
results.series.seriesRef.table	Name of the table from where the data series was obtained. Data type: String
results.series.values	Transformed series values. Data type: Array `"values": [ { "timestamp": "String", "value": Number } ]`
results.series.values.timestamp	ISO 8601 timestamp of the value. Data type: String
results.series.values.value	Transformed value. Data type: Number

Supported transforms

Table 25. Transform data types
Transform	Description
add	Adds the specified number to each timestamp value. Argument: arg (Decimal data type) – Number to add. For example: `"transforms": [ { "name": "add", "arg": 8 } ]`
autocorrelate	Calculates the correlation between timestamp values separated by an increasing number of periods starting at 1.
avg	Aggregates the time series into one series containing the average value for each corresponding timestamp across the input.
bottom	Returns the specified number of series that have the lowest values. Argument: `arg` (Integer) – The number of series to return. For example, the following returns the two time series that contain the lowest sets of values. `"transforms": [ { "name": "bottom", "arg": 2 } ]`
ceil	Rounds the value in each timestamp up to the specified precision: `ceil(value / <arg>) * <arg>)` Argument: arg (Decimal data type) – Decimal precision to round up to.
collect	Displays the transform results of the transform chain up to the point of the collect transform call. Collect transform results contain a unique marker, but you may want to also define a label. For example: `{ "start": "PT1H", "end": "", "table": "mb_demo_drone", "limit": 5000, "metrics": [ { "metric": "mb_demo_mt_altitude", "transforms": [ { "name": "label", "arg": "Series Timestamp Values" }, { "name": "collect" }, { "name": "avg" }, { "name": "label", "arg": "Average Timestamp Values" } ] } ] }`
constrainValues	Replaces any value outside the specified range with the corresponding maximum or minimum value. For example, if you specified the following, the transform replaces any value that is less than 0 with 0, and any value that is more than 100 with 100. `"transforms": [ { "name": "constrainValues", "val1": 0, "val2": 100 } ]` Arguments: val1 (Decimal data type): Minimum or maximum value. val2 (Decimal data type): Minimum or maximum value.
count	Aggregates the time series into one series. The new series contains the number of values that are not NaN (Not a Number) for each corresponding timestamp across the series.
derivative	Determines the rate of change between timestamps. Divides the difference between the value in each timestamp and the value in the next timestamp by the timestamp’s period. Note: This transform returns one less value than the number of values in the series.
div	Divides the value in each timestamp by the specified number (arg). Argument: arg (Decimal – The number by which to divide the value of each timestamp.
envelope	Returns two time series, where, at any point in time, one contains the largest value and the other contains the smallest value. Note: NaNs are ignored, but are returned if there are no other return values.
exp	Raises the value of the specified base to the power of the value in each timestamp. Argument: arg (Decimal data type) – The base value.
filter	Applies an aggregator to the contents of a sliding window, such as producing a moving average. Arguments: aggregator (Aggregator data type): Type of aggregation to perform. window (Duration data type): The duration of the sliding window.
floor	Rounds the value in each timestamp down to the specified precision: `floor(value / <arg>) * <arg>` Argument: arg (Decimal data type) – The decimal precision to round down to.
fractiles	Returns a time series for each fraction in the specified array. Each timestamp value is the value at which the specified fraction of values, for the corresponding timestamp across the input series, is below the specified percentage. For example, if the fraction is 0.5, then the value in the timestamp is the value where half the values in the input series are below 0.5. Argument: arg (Array of Decimal) – The fractions to use on the input series. For example: `"transforms": [ { "name": "fractiles", "arg": [0.25, 0.5, 0.75, 1] } ]`
groupBy	Groups data by the specified fields before collecting or applying aggregated transformations. Argument: arg (String) - A comma separated list of fields in the table to use to group the transform results. For example: `"transforms": [ { "name": "groupBy", "arg": "model" }, { "name": "avg" }, { "name": "label", "arg": "Model: %g" } ]`
integrate	Multiplies the value in each timestamp by its period.
interpolate	Creates a data value for a NaN data item by interpolating from adjacent data values. Argument: arg (Integer) – Number of data samples in each direction to check for a non-NaN value. If a non-NaN value is not found, then NaN is used.
inverse	Computes the inverse of each timestamp value.
iqr	Performs an interquartile range transform and creates a result set that contains four series: -IQR: The median of all entries below `Q1 - (1.5 * IQR)`. Q1: The median of the smallest half of entries. Q3: The median of the largest half of entries. +IQR: The median of all entries above `Q3 + (1.5 * IQR)`. Note: `IQR = Q3 - Q1`
label	Labels a transformation chain. Note: Subsequent transformations may modify or replace the label. Argument: arg (String) – Text of the label. Can contain the following formatting expressions: %%: Escape a "%" literal. %l: Current label that is being replaced. %s: Series subject. %g: Value of the group by field. If this is a referenced record, then the value of the record’s name field. If multiple groups are specified in the groupBy transform, labels are comma separated. %G: Value of the group by field. If this is a referenced record, then the record’s sys_id. If multiple groups are selected, values are comma separated. For example: `"transforms": [ { "name": "label", "arg": "Series Timestamp Values" }, ]` `"transforms": [ { "name": "groupBy", "arg": "model" }, { "name": "avg" }, { "name": "label", "arg": "Model: %g" } ]`
limit	Returns, at most, the specified duration or number of values, starting with the most recently saved value. Arguments: arg (Integer): Number of timestamp values to return for each time series. OR arg (Duration data type): Duration to limit each time series to.
log	Runs a logarithm on the value in each timestamp where the result is the log of the specified base for the timestamp value. Argument: arg (Decimal data type) – Base for the logarithm calculation.
mapValues	Replaces any values within the specified range (inclusive) with the specified value. If both lowerBound and upperBound are specified as NaN, then it replaces any NaN value with the targetValue. Arguments: lowerBound (Decimal data type): The lowest value in the range. upperBound (Decimal data type): The highest value in the range. targetValue (Decimal data type): Replacement value. For example, the following changes all values in the time series that are between .1 and .9 to 1: `"transforms": [ { "name": "mapValues", "lowerBound": .1, "upperBound": .9, "targetValue": 1 } ]`
max	Returns a series that contains the maximum value for each corresponding timestamp across the input.
median	Creates a series that contains the median of values for each timestamp across a set of series. If there are `n` series: If `n` is odd, the median is the `(n / 2 + 1)` value for a timestamp. If `n` is even, the median is the average of the `(n / 2)` and `(n / 2 + 1)` values for a timestamp.
min	Returns a series that contains the minimum value for each corresponding timestamp across the input.
mul	Multiplies the value in each timestamp by the specified number. Argument: arg (Decimal data type) – Number by which to multiply the value of each timestamp.
partition	Produces a new series with values filtered by applying a specified aggregator to a non-overlapping window. Arguments: aggregator (Aggregator data type): Type of aggregation to perform. window (Duration data type): The duration of the non-overlapping window to apply the aggregator. base (DateTime data type): The zero offset to use for partitioning. For example, to partition by day (24h), set this value to Monday at midnight in your time zone. To partition by a 30-day period, set this value to the first day of the most recent month. Default: Beginning of the EPOCH.
pow	Raises each timestamp value to the specified power. Argument: arg (Decimal data type) – Power to which to raise each value.
product	Aggregates the selected metric series into a single series that contains the product of all values for each timestamp. NaNs are excluded. If all numbers in the series are NaN, the output is also NaN.
resample	Resamples a time series to either a fixed number of points or from one frequency to another. Use the resample transformation to reduce the number of samples in the result set to more closely match the number of samples that you want to display. Arguments: You can pass various arguments for this transform. Below is a list of each of the possible argument groups. Only one of these argument groups can be passed within a single transform. The following argument groups are delineated by AND/OR. AND meaning the argument is part of the current group; OR meaning it is the start of a new argument group. arg (Integer): Number of samples to include in the result set. If available samples are less than this number, the endpoint uses interpolation to create additional samples. If there are more samples than this number, they are reduced by averaging them. OR arg (Duration data type): The frequency at which to resample. If available samples are less than this number, the endpoint uses interpolation to create additional samples. If there are more samples than this number, they are reduced by averaging them. OR minValues (Integer): The minimum number of samples to include in the result set. If available samples are less than this number, the endpoint uses interpolation to create additional samples. AND maxValues (Integer): The maximum number of samples to include in the result set. If there are more samples than this number, they are reduced by averaging them. OR aggregator (Aggregator data type): The aggregator to use when resampling. AND values (Integer): The number of samples to include in the result set. If available samples are less than this number, the endpoint uses interpolation to create additional samples. If there are more samples than this number, they are reduced by applying the specified aggregator to them. OR aggregator (Aggregator data type): The aggregator to use when resampling. AND period (Duration data type): The frequency at which to resample. If available samples are less than this number, the endpoint uses interpolation to create additional samples. If there are more samples than this number, they are reduced by applying the specified aggregator to them. OR aggregator (Aggregator data type): The aggregator to use when resampling. AND minValues (Integer): The minimum number of samples to include in the result set. If available samples are less than this number, the endpoint uses interpolation to create additional samples. AND maxValues (Integer): The maximum number of samples to include in the result set. If there are more samples than this number, they are reduced by averaging them.
round	Rounds the value in each timestamp up to the specified precision: `(value / <arg>) * <arg>` Argument: arg (Decimal data type) – The decimal precision to round up to.
root	Calculates the root of each timestamp value using the specified index. Argument: arg (Decimal data type) – The index of the root. For example, the following returns the square root of each timestamp: `"transforms": [ { "name": "root", "arg": "2" }, ]`
stddev	Creates a series that contains the standard deviation of values for each timestamp across a set of series.
sub	Subtracts the specified number from the value in each timestamp. Argument: arg (Number) – The number to subtract from the value in each timestamp.
sum	Aggregates the selected metric series into one series that contains the sum of all values for each timestamp, excluding any NaNs. If all numbers in the series are NaN, the output is NaN.
timeshift	Shifts the time range by adding the specified offset to a value’s timestamp without modifying the value. Use this transform to shift timestamps to another timezone. Argument: arg (Duration data type) – The amount of time to shift by.
top	Returns the specified number of series that have the highest values. Argument: arg (Integer) – The number of series to return. For example, the following returns the two time series that contain the highest sets of values. `"transforms": [ { "name": "top", "arg": 2 } ]`


Data type	Description
Aggregator	Available aggregators to use within the transform. AVG: Calculates the arithmetic mean of all currently selected series. CHISQUARE: Shows how well a statistical model fits the metric dataset. LAST: Returns the last defined value in the period window. MAX: Shows the largest value for the metric dataset, at each point in time. MEDIAN: Shows the median of the metric dataset. The median separates the higher values of the metric dataset from the lower values. MIN: Shows the smallest value for the metric dataset, at each point in time. STDDEV: Calculates the standard deviation across the underlying data. Used to quantify the variation or dispersion of a set of data values in the metric dataset. SUM: Calculates the sum across all currently selected series.
DateTime	Absolute date/time values are specified by the ISO 8601 date and time format: `YYYY-MM-DDThh:mm:ss`. For example: 2020-02-28T13:10:42. Where: [YYYY]: Four-digit year. [MM]: Zero-padded month between 01 and 12. [DD]: Zero-padded day between 01 and 31. T: Represents time and is mandatory before any of the time components are specified. [hh]: Zero-padded hour between 00 and 23. [mm]: Zero-padded minutes between 00 and 59. [ss]: Zero-padded seconds between 00 and 59. Note that leap seconds are spread out evenly across the previous 1,000 seconds. Relative date/time values are specified using a duration (Duration data type), which is subtracted from the current time. For example: P7D = seven days ago.
Decimal	Decimal value that can either be: A signed decimal number of arbitrary precision that can use exponential notation. Such as: 2 1.7 -3.47 1.0E+2 A string representation of: A signed decimal number that may use exponential notation and is guaranteed to be a double-precision 64-bit IEEE 754 floating-point number. "NaN" "-Infinity" "+Infinity"
Duration	Amount of time in a time interval. Duration values are specified by the ISO 8601 duration format: `P[n]Y[n]M[n]DT[n]H[n]M[n]S` Where: P: Duration designator, referred to as "period", and is always placed at the beginning of the duration. [n]Y: Number of years. [n]M: Number of months. [n]D: Number of days. T: Time designator and is mandatory before any of the time components are specified. [n]H: Number of hours. [n]M: Number of minutes. [n]S: Number of seconds. For example: P7D: Period of seven days. P1M: Period of one month. PT15M: Period of 15 minutes. P1DT12H: Period of one day and twelve hours.

cURL request

curl "https://instance.servicenow.com/api/now/v1/clotho/transform \
--request POST \
--header "Accept:application/json", "Content-Type:application/json" \
--user "username":"password"
-d {\
  "start": "PT15M",\
  "end": "",\
  "table": "mb_demo_drone",\
  "query": "fleet.nameSTARTSWITHB",\
  "limit": 5000,\
  "metrics": [\
    {\
      "metric": "mb_demo_mt_altitude",\
      "label": "Series - Avg",\
      "transforms": [\
        {\
          "name": "partition",\
          "arg": {\
            "aggregator": "AVG",\
            "window": "PT5M"\
          }\
        },
        {\
          "name": "avg"\
        }\
      ]\
    },
    {\
      "metric": "mb_demo_mt_altitude",\
      "groupBy": "fleet",\
      "label": "Fleet - AVG",\
      "transforms": [\
        {\
          "name": "partition",\
          "arg": {\
            "aggregator": "AVG",\
            "window": "PT5M"\
          }\
        },
        {\
          "name": "avg"\
        }\
      ]\
    }\
  ]\
} \

Output:

"results:" [
  {
    "marker": "674d86ba-a810-4065-942b-0b7ca2f95db2",
    "series": [
      {
        "label": "Series - Avg",
        "values": [
          {
            "timestamp": "2020-05-01T21:05:00Z",
            "value": 157.43086
          },
          {
            "timestamp": "2020-05-01T21:10:00Z",
            "value": 162.92278
          }
        ]
      }
    ]
  },
  {
    "marker": "846aa334-232a-4015-b033-d18ebc4b1d23",
    "grouped": [
      {
        "groupingBy": "fleet",
        "groups": [
          {
            "group": "86fac11787333200a328c5b836cb0b4e",
            "label": "Bantams",
            "series": {
              "label": "Fleet - AVG",
              "values": [
                {
                  "timestamp": "2020-05-01T21:05:00Z",
                  "value": 159.70201
                },
                {
                  "timestamp": "2020-05-01T21:10:00Z",
                  "value": 165.1136
                }
              ]
            }
          },
          {
            "group": "4afac11787333200a328c5b836cb0b4e",
            "label": "Bumble Untd",
            "series": {
              "label": "Fleet - AVG",
              "values": [
                {
                  "timestamp": "2020-05-01T21:05:00Z",
                  "value": 154.5403
                },
                {
                  "timestamp": "2020-05-01T21:10:00Z",
                  "value": 160.13445
                }
              ]
            }
          }
        ]
      }
    ]
  }
]

MetricBase Time Series - POST /now/clotho/transform/stream

Returns a stream of transformed time series data for one or more metrics after applying the specified list of transforms.

Streaming data in this manner allows you to process the data as individual transforms are completed and returned, rather than waiting for all transform results to be completed and downloaded. If large amounts of data need to be processed by the client, this type of processing reduces the end-to-end processing time and potentially reduces the memory usage on the client.

By setting the corresponding Accept header value in your request, you can:

Specify the streamed data to be encoded in a binary format,
Serialize streamed data into a JSON array, or
Stream data back to the client in a wide or narrow CSV format.

The endpoint streams the data as transforms are completed on the MetricBase server, without groupings or a predetermined ordering. Data streamed in binary format is smaller in size than the JSON representation returned by the MetricBase Time Series - POST /now/clotho/transform endpoint.

URL format

Versioned URL: /api/now/{api_version}/clotho/transform/stream

Supported request parameters

Table 26. Path parameters
Name	Description
api_version	Optional. Version of the endpoint to access. For example, `v1` or `v2`. Only specify this value to use an endpoint version other than the latest. Data type: String

Table 27. Query parameters
Name	Description
sysparm_display_value	Flag that indicates whether to label the result data with the subject record display value if no other label is specified. Valid values: true: Result data is labeled with the subject record display value. false: Result data is not labeled with the subject record display value. Data type: Boolean Default: false

Table 28. Request body parameters (XML or JSON)
Name	Description
end	Required. End time of the evaluation period. An empty or missing value is treated as the current time. Time values are inclusive of this end time. Data type: String Format: ISO 8601 (UTC), either: Absolute date format [YYYY-MM-DDThh:mm:ss], such as `2019-03-20T17:04:55`. Relative to current time duration format `[P(n)Y(n)M(n)DT(n)H(n)M(n)S]`, such as `P1M`.
limit	Maximum number of records to return. Unusually large values can impact system performance. Data type: Number Default: 10,000
metrics	List of metrics objects to use in the transform. For more information on metrics, see Metrics. Data type: Array `"metrics": [ { "label": "String", "metric": "String", "transforms": [Array] } ]`
metrics.label	Label to use for this metric’s result set. It replaces any labels generated by the transform chain. Data type: String Default: Generated default label.
metrics.metric	Required if metrics object is passed. Metric field to use in the transform. This field must be in the table specified in the table parameter. Data type: String
metrics.transforms	List of transforms (transform chain) to apply to the retrieved time series data. Each transform builds on the results of the previous transform. For a list of available transforms, see Supported Transforms below. Data type: Array `"transforms": [ { "arg": {Object}, "name": "String" } ]`
metrics.transforms.arg	Dependent on the transform. Parameter or parameters to pass into the transform. General guidelines: Do not use the arg parameter when specifying transformations that do not take a parameter. Use Number, String, or Boolean for transforms that take a single parameter. Use a JSON object, with the appropriate name-value pairs, for transforms that take more than one parameter. Data type: Number, String, Boolean, or JSON object, depending on transform. (For a list of available transforms, refer to the table Supported transforms below.)
metrics.transforms.name	Required if a transforms object is specified. Name of the transform. For a list of available transforms, refer to the table Supported transforms below. Data type: String
query	Encoded query to use to filter the result set. You can compose the query using the specified table’s filter editor. Once created, select Copy URL from the filter’s breadcrumbs context menu. Data type: String Default: None
start	Required. Start time of the evaluation period. The special value `all` can be used to set the start time as the current time minus the maximum retention period for the specified metrics. An empty or missing value is treated as an implicit `all`. Time values are inclusive of this start time. Data type: String Format: ISO 8601 (UTC), either: Absolute date format [YYYY-MM-DDThh:mm:ss], such as `2019-03-20T17:04:55` Relative to current time duration format `[P(n)Y(n)M(n)DT(n)H(n)M(n)S]`, such as `P1M`.
table	Required. Name of the table that contains the GlideRecord associated with this series. Data type: String

Headers

Table 29. Request headers
Header	Description
Accept	Data format of the response body. Supports the following: application/json application/octet-stream or text/csv To specify the CSV format, use `text/csv;format=narrow` or `text/csv;format=wide`.
Content-Type	Data format of the request body. Only supports application/json.

Table 30. Response headers
Header	Description
None	Data format of the response body. Based on the specified Accept values of the request, use: application/json application/octet-stream or text/csv If multiple Accept types are specified, the first supported type is returned.

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 API HTTP response codes.

Table 31. Status codes
Status code	Description
200	Successful. The request was successfully processed and data will begin streaming. Note: A 200 response can still incur a processing error midstream as the transforms are computed.
400	Bad Request. A bad request type or malformed request was detected.
401	Unauthorized. The user credentials are incorrect or have not been passed.
404	Not found. The requested item wasn't found.
405	Invalid method. The functionality is disabled.
500	Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

Response body parameters (Octet-stream or JSON)


Name	Description
Output Stream (Octet-Stream)	If the Accept request header is set to application/octet-stream, the matching MetricBase data is returned as a binary serialized stream. The Clotho-Util for Java applications provide a deserializer that enables you to parse this data. The stream consists of a binary serialization of each datum, preceded by an integer representing its length. The following entries describe the data within the binary representation and the order of that data.
CSV Stream (UTF-8 Stream)	If the Accept request header is set to text/csv, the matching MetricBase data is returned as UTF-8 encoded CSV data in wide or narrow formats. A narrow format returns subject and time stamp columns and a column for each returned metric. A wide format returns a time stamp column with a separate column for each metric-subject pair.
Subject	Source of the data. For example, if the metric for the data is drone altitudes, this value may be the ID of a specific drone. If a colon is included in the value, the parts after the subject represent the metric that the data is a part of. Null values are represented by an encoded empty string. Size: 2+ bytes Data type: Java Modified UTF String
Dimension	Metric that the data is from. Null values are represented by an encoded empty string. Size: 2+ bytes Data type: Java Modified UTF String
Label	Label of the data. Null values are represented by an encoded empty string. Size: 2+ bytes Data type: Java Modified UTF String
Type	Type of data encoded into a byte. Possible values: Float Signal Double Signal Float Mode Double Model Size: 1 byte Data type: Byte
Flags	Encoded serializeFlags variable. If serializeTags is true and the data contains tags, the value is 2, otherwise it is 0. Size: 1 byte Data type: Byte
Period	Period associated with the data. Size: 4 bytes Data type: Integer
Number of Tags	If serializeTags is true, then this is the number of tags stored in the data. Size: 4 bytes Data type: Integer
Tags	If serializeTags is true, each tag is stored in the data. Size: Depends on number of tags (2+ bytes). Data type: Java modified UTF Strings
Start Epoch Second	Epoch UTC time representing the start time of this data series. Size: 8 bytes Data type: Long
Number of Values	Number of values stored in this data. Size: 4 bytes Data type: Integer
Values	If Type is `Float Signal`, then the remainder consists of float values. Size: Number of Values * 4 Data type: Floats
Values	If Type is `Double Signal`, then the remainder consists of double values. Size: Number of Values * 4 bytes Data type: Doubles
Model Json (Model)	If Type is `Float Model` or `Double Model`, the remainder is a Java Modified UTF String representing the model as JSON. Size: 2+ bytes Data type: JSON (Java Modified UTF String)
Big Model Marker (Big Model)	If the length of the model’s JSON is greater than 65,535 bytes, then this field is written instead of the Model Json. Size: 5 Data type: Java Modified UTF String
Big Model Size (Big Model)	Length of the JSON representation of the big model. Size: 4 bytes Data type: Integer
Big Model Json (Big Model)	JSON representation of the model as a series of UTF characters, The size is dictated by the Big Model Size field. Size: 65535-256000 bytes Data type: UTF chars
JSON Stream (JSON)	If the Accept request header is set to application/json, the matching MetricBase data is returned as a stream of new line separated JSON objects. The following entries describe the possible elements in each returned object.
label	Data’s label. This value is either generated by the endpoint or is the value passed in the metrics.label parameter. Data type: String
period	Amount of time between each value. For example, a period of 60 would mean that each value is a minute apart. Unit: Seconds Data type: Number
range	Start and end times of the data in ISO 8601 (UTC) format. Data type: Array
series	Identifies the individual data. If present, is typically in the form of `[glide record id]:[metric]`. This may not be present when using transforms. Data type: String
species	Type of return data. For a series of either float or double values, this is either FLOAT_SIGNAL or DOUBLE_SIGNAL. For a model meant to analyze float or double data, this is either FLOAT_MODEL or DOUBLE_MODEL. Data type: String
tags	Tags associated with the data. Data type: Array of String
value	Float or Double values for the data. Data type: Array of Numbers
error	Error message if the transformation of the specified data series fails. Data type: String

Supported transforms

Table 32. Transform data types
Transform	Description
add	Adds the specified number to each timestamp value. Argument: arg (Decimal data type) – Number to add. For example: `"transforms": [ { "name": "add", "arg": 8 } ]`
autocorrelate	Calculates the correlation between timestamp values separated by an increasing number of periods starting at 1.
avg	Aggregates the time series into one series containing the average value for each corresponding timestamp across the input.
bottom	Returns the specified number of series that have the lowest values. Argument: `arg` (Integer) – The number of series to return. For example, the following returns the two time series that contain the lowest sets of values. `"transforms": [ { "name": "bottom", "arg": 2 } ]`
ceil	Rounds the value in each timestamp up to the specified precision: `ceil(value / <arg>) * <arg>)` Argument: arg (Decimal data type) – Decimal precision to round up to.
collect	Displays the transform results of the transform chain up to the point of the collect transform call. Collect transform results contain a unique marker, but you may want to also define a label. For example: `{ "start": "PT1H", "end": "", "table": "mb_demo_drone", "limit": 5000, "metrics": [ { "metric": "mb_demo_mt_altitude", "transforms": [ { "name": "label", "arg": "Series Timestamp Values" }, { "name": "collect" }, { "name": "avg" }, { "name": "label", "arg": "Average Timestamp Values" } ] } ] }`
constrainValues	Replaces any value outside the specified range with the corresponding maximum or minimum value. For example, if you specified the following, the transform replaces any value that is less than 0 with 0, and any value that is more than 100 with 100. `"transforms": [ { "name": "constrainValues", "val1": 0, "val2": 100 } ]` Arguments: val1 (Decimal data type): Minimum or maximum value. val2 (Decimal data type): Minimum or maximum value.
count	Aggregates the time series into one series. The new series contains the number of values that are not NaN (Not a Number) for each corresponding timestamp across the series.
derivative	Determines the rate of change between timestamps. Divides the difference between the value in each timestamp and the value in the next timestamp by the timestamp’s period. Note: This transform returns one less value than the number of values in the series.
div	Divides the value in each timestamp by the specified number (arg). Argument: arg (Decimal – The number by which to divide the value of each timestamp.
envelope	Returns two time series, where, at any point in time, one contains the largest value and the other contains the smallest value. Note: NaNs are ignored, but are returned if there are no other return values.
exp	Raises the value of the specified base to the power of the value in each timestamp. Argument: arg (Decimal data type) – The base value.
filter	Applies an aggregator to the contents of a sliding window, such as producing a moving average. Arguments: aggregator (Aggregator data type): Type of aggregation to perform. window (Duration data type): The duration of the sliding window.
floor	Rounds the value in each timestamp down to the specified precision: `floor(value / <arg>) * <arg>` Argument: arg (Decimal data type) – The decimal precision to round down to.
fractiles	Returns a time series for each fraction in the specified array. Each timestamp value is the value at which the specified fraction of values, for the corresponding timestamp across the input series, is below the specified percentage. For example, if the fraction is 0.5, then the value in the timestamp is the value where half the values in the input series are below 0.5. Argument: arg (Array of Decimal) – The fractions to use on the input series. For example: `"transforms": [ { "name": "fractiles", "arg": [0.25, 0.5, 0.75, 1] } ]`
groupBy	Groups data by the specified fields before collecting or applying aggregated transformations. Argument: arg (String) - A comma separated list of fields in the table to use to group the transform results. For example: `"transforms": [ { "name": "groupBy", "arg": "model" }, { "name": "avg" }, { "name": "label", "arg": "Model: %g" } ]`
integrate	Multiplies the value in each timestamp by its period.
interpolate	Creates a data value for a NaN data item by interpolating from adjacent data values. Argument: arg (Integer) – Number of data samples in each direction to check for a non-NaN value. If a non-NaN value is not found, then NaN is used.
inverse	Computes the inverse of each timestamp value.
iqr	Performs an interquartile range transform and creates a result set that contains four series: -IQR: The median of all entries below `Q1 - (1.5 * IQR)`. Q1: The median of the smallest half of entries. Q3: The median of the largest half of entries. +IQR: The median of all entries above `Q3 + (1.5 * IQR)`. Note: `IQR = Q3 - Q1`
label	Labels a transformation chain. Note: Subsequent transformations may modify or replace the label. Argument: arg (String) – Text of the label. Can contain the following formatting expressions: %%: Escape a "%" literal. %l: Current label that is being replaced. %s: Series subject. %g: Value of the group by field. If this is a referenced record, then the value of the record’s name field. If multiple groups are specified in the groupBy transform, labels are comma separated. %G: Value of the group by field. If this is a referenced record, then the record’s sys_id. If multiple groups are selected, values are comma separated. For example: `"transforms": [ { "name": "label", "arg": "Series Timestamp Values" }, ]` `"transforms": [ { "name": "groupBy", "arg": "model" }, { "name": "avg" }, { "name": "label", "arg": "Model: %g" } ]`
limit	Returns, at most, the specified duration or number of values, starting with the most recently saved value. Arguments: arg (Integer): Number of timestamp values to return for each time series. OR arg (Duration data type): Duration to limit each time series to.
log	Runs a logarithm on the value in each timestamp where the result is the log of the specified base for the timestamp value. Argument: arg (Decimal data type) – Base for the logarithm calculation.
mapValues	Replaces any values within the specified range (inclusive) with the specified value. If both lowerBound and upperBound are specified as NaN, then it replaces any NaN value with the targetValue. Arguments: lowerBound (Decimal data type): The lowest value in the range. upperBound (Decimal data type): The highest value in the range. targetValue (Decimal data type): Replacement value. For example, the following changes all values in the time series that are between .1 and .9 to 1: `"transforms": [ { "name": "mapValues", "lowerBound": .1, "upperBound": .9, "targetValue": 1 } ]`
max	Returns a series that contains the maximum value for each corresponding timestamp across the input.
median	Creates a series that contains the median of values for each timestamp across a set of series. If there are `n` series: If `n` is odd, the median is the `(n / 2 + 1)` value for a timestamp. If `n` is even, the median is the average of the `(n / 2)` and `(n / 2 + 1)` values for a timestamp.
min	Returns a series that contains the minimum value for each corresponding timestamp across the input.
mul	Multiplies the value in each timestamp by the specified number. Argument: arg (Decimal data type) – Number by which to multiply the value of each timestamp.
partition	Produces a new series with values filtered by applying a specified aggregator to a non-overlapping window. Arguments: aggregator (Aggregator data type): Type of aggregation to perform. window (Duration data type): The duration of the non-overlapping window to apply the aggregator. base (DateTime data type): The zero offset to use for partitioning. For example, to partition by day (24h), set this value to Monday at midnight in your time zone. To partition by a 30-day period, set this value to the first day of the most recent month. Default: Beginning of the EPOCH.
pow	Raises each timestamp value to the specified power. Argument: arg (Decimal data type) – Power to which to raise each value.
product	Aggregates the selected metric series into a single series that contains the product of all values for each timestamp. NaNs are excluded. If all numbers in the series are NaN, the output is also NaN.
resample	Resamples a time series to either a fixed number of points or from one frequency to another. Use the resample transformation to reduce the number of samples in the result set to more closely match the number of samples that you want to display. Arguments: You can pass various arguments for this transform. Below is a list of each of the possible argument groups. Only one of these argument groups can be passed within a single transform. The following argument groups are delineated by AND/OR. AND meaning the argument is part of the current group; OR meaning it is the start of a new argument group. arg (Integer): Number of samples to include in the result set. If available samples are less than this number, the endpoint uses interpolation to create additional samples. If there are more samples than this number, they are reduced by averaging them. OR arg (Duration data type): The frequency at which to resample. If available samples are less than this number, the endpoint uses interpolation to create additional samples. If there are more samples than this number, they are reduced by averaging them. OR minValues (Integer): The minimum number of samples to include in the result set. If available samples are less than this number, the endpoint uses interpolation to create additional samples. AND maxValues (Integer): The maximum number of samples to include in the result set. If there are more samples than this number, they are reduced by averaging them. OR aggregator (Aggregator data type): The aggregator to use when resampling. AND values (Integer): The number of samples to include in the result set. If available samples are less than this number, the endpoint uses interpolation to create additional samples. If there are more samples than this number, they are reduced by applying the specified aggregator to them. OR aggregator (Aggregator data type): The aggregator to use when resampling. AND period (Duration data type): The frequency at which to resample. If available samples are less than this number, the endpoint uses interpolation to create additional samples. If there are more samples than this number, they are reduced by applying the specified aggregator to them. OR aggregator (Aggregator data type): The aggregator to use when resampling. AND minValues (Integer): The minimum number of samples to include in the result set. If available samples are less than this number, the endpoint uses interpolation to create additional samples. AND maxValues (Integer): The maximum number of samples to include in the result set. If there are more samples than this number, they are reduced by averaging them.
round	Rounds the value in each timestamp up to the specified precision: `(value / <arg>) * <arg>` Argument: arg (Decimal data type) – The decimal precision to round up to.
root	Calculates the root of each timestamp value using the specified index. Argument: arg (Decimal data type) – The index of the root. For example, the following returns the square root of each timestamp: `"transforms": [ { "name": "root", "arg": "2" }, ]`
stddev	Creates a series that contains the standard deviation of values for each timestamp across a set of series.
sub	Subtracts the specified number from the value in each timestamp. Argument: arg (Number) – The number to subtract from the value in each timestamp.
sum	Aggregates the selected metric series into one series that contains the sum of all values for each timestamp, excluding any NaNs. If all numbers in the series are NaN, the output is NaN.
timeshift	Shifts the time range by adding the specified offset to a value’s timestamp without modifying the value. Use this transform to shift timestamps to another timezone. Argument: arg (Duration data type) – The amount of time to shift by.
top	Returns the specified number of series that have the highest values. Argument: arg (Integer) – The number of series to return. For example, the following returns the two time series that contain the highest sets of values. `"transforms": [ { "name": "top", "arg": 2 } ]`


Data type	Description
Aggregator	Available aggregators to use within the transform. AVG: Calculates the arithmetic mean of all currently selected series. CHISQUARE: Shows how well a statistical model fits the metric dataset. LAST: Returns the last defined value in the period window. MAX: Shows the largest value for the metric dataset, at each point in time. MEDIAN: Shows the median of the metric dataset. The median separates the higher values of the metric dataset from the lower values. MIN: Shows the smallest value for the metric dataset, at each point in time. STDDEV: Calculates the standard deviation across the underlying data. Used to quantify the variation or dispersion of a set of data values in the metric dataset. SUM: Calculates the sum across all currently selected series.
DateTime	Absolute date/time values are specified by the ISO 8601 date and time format: `YYYY-MM-DDThh:mm:ss`. For example: 2020-02-28T13:10:42. Where: [YYYY]: Four-digit year. [MM]: Zero-padded month between 01 and 12. [DD]: Zero-padded day between 01 and 31. T: Represents time and is mandatory before any of the time components are specified. [hh]: Zero-padded hour between 00 and 23. [mm]: Zero-padded minutes between 00 and 59. [ss]: Zero-padded seconds between 00 and 59. Note that leap seconds are spread out evenly across the previous 1,000 seconds. Relative date/time values are specified using a duration (Duration data type), which is subtracted from the current time. For example: P7D = seven days ago.
Decimal	Decimal value that can either be: A signed decimal number of arbitrary precision that can use exponential notation. Such as: 2 1.7 -3.47 1.0E+2 A string representation of: A signed decimal number that may use exponential notation and is guaranteed to be a double-precision 64-bit IEEE 754 floating-point number. "NaN" "-Infinity" "+Infinity"
Duration	Amount of time in a time interval. Duration values are specified by the ISO 8601 duration format: `P[n]Y[n]M[n]DT[n]H[n]M[n]S` Where: P: Duration designator, referred to as "period", and is always placed at the beginning of the duration. [n]Y: Number of years. [n]M: Number of months. [n]D: Number of days. T: Time designator and is mandatory before any of the time components are specified. [n]H: Number of hours. [n]M: Number of minutes. [n]S: Number of seconds. For example: P7D: Period of seven days. P1M: Period of one month. PT15M: Period of 15 minutes. P1DT12H: Period of one day and twelve hours.

cURL request

The following example shows how to call this endpoint to return a JSON stream for metrics on the mb_demo_drone table. Note: While the objects in this example are expanded to multiple lines for legibility, in an actual result each returned object is on its own line. You can make the same call and return an octet stream by setting --header "Accept:application/octet-stream" \.

curl "localhost:8080/api/now/v1/clotho/transform/stream" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--user "username":"password" \
-d "{\
  \"start\": \"PT5M\",\
  \"end\": \"\",\
  \"table\": \"mb_demo_drone\",\
  \"query\": \"fleet.nameSTARTSWITHB\",\
  \"limit\": 5000,\
  \"metrics\": [\
    {\
      \"metric\": \"mb_demo_mt_altitude\",\
      \"label\": \"Series - Avg\",\
      \"transforms\": [\
        {\
          \"name\": \"partition\",\
          \"arg\": {\
            \"aggregator\": \"AVG\",\
            \"window\": \"PT5M\"\
          }\
        },
        {\
          \"name\": \"avg\"\
        }\
      ]\
    },
    {\
      \"metric\": \"mb_demo_mt_altitude\",\
      \"groupBy\": \"fleet\",\
      \"label\": \"Fleet - AVG\",\
      \"transforms\": [\
        {\
          \"name\": \"partition\",\
          \"arg\": {\
            \"aggregator\": \"AVG\",\
            \"window\": \"PT5M\"\
          }\
        },
        {\
          \"name\": \"avg\"\
        }\
      ]\
    }\
  ]\
}"

Response:

[
  {
    "label": "Series - Avg",
    "tags": [
      "#4fb1114f-2426-4acb-8e3e-6435dd62134c"
    ],
    "species": "DOUBLE_SIGNAL",
    "range": [
      "2022-06-16T17:50:00Z",
      "2022-06-16T17:50:00Z"
    ],
    "values": [
      132.86805196126303
    ],
    "period": 300
  },
  {
    "label": "Fleet - AVG",
    "tags": [
      ":fleet:86fac11787333200a328c5b836cb0b4e:Bantams",
      "#6641aab4-c55f-4d11-8846-26b0b706ec1c"
    ],
    "species": "DOUBLE_SIGNAL",
    "range": [
      "2022-06-16T17:50:00Z",
      "2022-06-16T17:50:00Z"
    ],
    "values": [
      134.3775875908988
    ],
    "period": 300
  },
  {
    "label": "Fleet - AVG",
    "tags": [
      "#6641aab4-c55f-4d11-8846-26b0b706ec1c",
      ":fleet:4afac11787333200a328c5b836cb0b4e:Bumble Untd"
    ],
    "species": "DOUBLE_SIGNAL",
    "range": [
      "2022-06-16T17:50:00Z",
      "2022-06-16T17:50:00Z"
    ],
    "values": [
      129.02530271356756
    ],
    "period": 300
  }
]

The following cURL example uses the CSV format option to stream back the altitude values (stored in the database as "mb_demo_mt_altitude") of the last day for each drone stored in the mb_demo_drone [Drones] table of the Metricbase Demo plugin. In the example, the data is returned in a narrow table format with three columns: the Sys_id of the subject identifying the drone, the time stamp of value, and the altitude value.

curl "https://instance.servicenow.com/api/now/v1/clotho/transform/stream" \
--request POST \
--header "Accept:text/csv;format=narrow" \
--header "Content-Type:application/json" \
--user "user name":"password" \
-d "{\
  \"start\": \"P1D\",\
  \"end\": \"\",\
  \"table\": \"mb_demo_drone\",\
  \"metrics\": [\
    {\
      \"metric\": \"mb_demo_mt_altitude\",\
      \"transforms\": []\
    }]\
}"

Output:

Subject, Timestamp,"mb_demo_drone|mb_demo_mt_altitude"
"a66b051787333200a328c5b836cb0b97",2022-11-07T22:35:00Z,92.84400939941406
"a66b051787333200a328c5b836cb0b94",2022-11-07T22:35:00Z,92.2428970336914
"6a6b051787333200a328c5b836cb0b97",2022-11-07T22:35:00Z,92.0076904296875
"ea6b051787333200a328c5b836cb0b92",2022-11-07T22:35:00Z,97.3113021850586
"a66b051787333200a328c5b836cb0b91",2022-11-07T22:35:00Z,108.49791717529297
"6a6b051787333200a328c5b836cb0b94",2022-11-07T22:35:00Z,109.04239654541016
"6a6b051787333200a328c5b836cb0b91",2022-11-07T22:35:00Z,93.72159576416016
"ee6b051787333200a328c5b836cb0b91",2022-11-07T22:35:00Z,107.69989776611328
"ee6b051787333200a328c5b836cb0b97",2022-11-07T22:35:00Z,100.86473083496094
"ee6b051787333200a328c5b836cb0b94",2022-11-07T22:35:00Z,95.77774047851562
"666b051787333200a328c5b836cb0b92",2022-11-07T22:35:00Z,105.19712829589844
"666b051787333200a328c5b836cb0b95",2022-11-07T22:35:00Z,105.92308807373047
"6e6b051787333200a328c5b836cb0b99",2022-11-07T22:35:00Z,93.59339141845703
"666b051787333200a328c5b836cb0b98",2022-11-07T22:35:00Z,94.51266479492188
"e26b051787333200a328c5b836cb0b94",2022-11-07T22:35:00Z,105.4367904663086
"6e6b051787333200a328c5b836cb0b96",2022-11-07T22:35:00Z,94.64836883544922
"6e6b051787333200a328c5b836cb0b93",2022-11-07T22:35:00Z,94.78523254394531
"e26b051787333200a328c5b836cb0b97",2022-11-07T22:35:00Z,96.99283599853516
"aa6b051787333200a328c5b836cb0b96",2022-11-07T22:35:00Z,106.67017364501953
"e26b051787333200a328c5b836cb0b91",2022-11-07T22:35:00Z,94.2446517944336
"aa6b051787333200a328c5b836cb0b93",2022-11-07T22:35:00Z,91.659912109375
"226b051787333200a328c5b836cb0b94",2022-11-07T22:35:00Z,99.5401840209961
"226b051787333200a328c5b836cb0b97",2022-11-07T22:35:00Z,98.13501739501953
"226b051787333200a328c5b836cb0b91",2022-11-07T22:35:00Z,92.2428970336914
"226b051787333200a328c5b836cb0b90",2022-11-07T22:35:00Z,106.41876983642578
"aa6b051787333200a328c5b836cb0b99",2022-11-07T22:35:00Z,107.69989776611328
"626b051787333200a328c5b836cb0b93",2022-11-07T22:35:00Z,92.96666717529297
"e66b051787333200a328c5b836cb0b99",2022-11-07T22:35:00Z,93.85079193115234
"e66b051787333200a328c5b836cb0b93",2022-11-07T22:35:00Z,96.07303619384766
"e66b051787333200a328c5b836cb0b96",2022-11-07T22:35:00Z,98.47595977783203
"2a6b051787333200a328c5b836cb0b92",2022-11-07T22:35:00Z,95.9247055053711
"226b051787333200a328c5b836cb0b9a",2022-11-07T22:35:00Z,99.5401840209961
"2a6b051787333200a328c5b836cb0b98",2022-11-07T22:35:00Z,103.1417465209961
"2a6b051787333200a328c5b836cb0b95",2022-11-07T22:35:00Z,96.99283599853516
"ae6b051787333200a328c5b836cb0b95",2022-11-07T22:35:00Z,94.64836883544922
"ae6b051787333200a328c5b836cb0b98",2022-11-07T22:35:00Z,101.8689956665039
"ae6b051787333200a328c5b836cb0b92",2022-11-07T22:35:00Z,107.4388198852539
"a26b051787333200a328c5b836cb0b98",2022-11-07T22:35:00Z,94.78523254394531
"266b051787333200a328c5b836cb0b93",2022-11-07T22:35:00Z,94.51266479492188
"2e6b051787333200a328c5b836cb0b97",2022-11-07T22:35:00Z,108.49791717529297
"2e6b051787333200a328c5b836cb0b91",2022-11-07T22:35:00Z,97.15129852294922
"2e6b051787333200a328c5b836cb0b94",2022-11-07T22:35:00Z,103.36128997802734
"a26b051787333200a328c5b836cb0b92",2022-11-07T22:35:00Z,100.47681427001953
"266b051787333200a328c5b836cb0b96",2022-11-07T22:35:00Z,103.5830078125
"266b051787333200a328c5b836cb0b99",2022-11-07T22:35:00Z,97.3113021850586
"a26b051787333200a328c5b836cb0b95",2022-11-07T22:35:00Z,105.92308807373047
"ea6b051787333200a328c5b836cb0b98",2022-11-07T22:35:00Z,95.34477996826172
"ea6b051787333200a328c5b836cb0b95",2022-11-07T22:35:00Z,100.47681427001953
"626b051787333200a328c5b836cb0b99",2022-11-07T22:35:00Z,100.86473083496094
"626b051787333200a328c5b836cb0b96",2022-11-07T22:35:00Z,106.9239730834961

MetricBase Time Series - POST /now/clotho/put

Adds time series data to the MetricBase database.

URL format

Versioned URL: /api/now/{api_version}/clotho/put

Supported request parameters

Table 33. Path parameters
Name	Description
api_version	Version of the endpoint to access. For example, `v1` or `v2`. Only specify this value to use an endpoint version other than the latest. Data type: String

Table 34. Query parameters
Name	Description
sysparm_ignore_unknown_series	Flag that indicates whether to ignore unknown series and continue the transaction without returning an error. Valid values: true: Ignore unknown series. false: Do not ignore unknown series. Default: true

Table 35. Request body parameters (XML or JSON)
Name	Description
seriesRef	Required. Information to update. Data type: Array `"seriesRef": [ { "metric": "String", "subject": "String", "table": "String" } ]`
seriesRef.metric	Required. The name of the metric to update. Data type: String
seriesRef.subject	Required. The sys_id of the record in which to update the data. Located in the table specified in seriesRef.table. Data type: String
seriesRef.table	Required. The name of the table in which to save the data. Data type: String
values	Required. The series values to store. Data type: Array `"values": [ { "timestamp": "String", "value": Number } ]`
values.timestamp	Required. The ISO 8601 timestamp of the value. Data type: String Format: `YYYY-MM-ddTHH:mm:ddZ` The ending ‘Z’, which denotes the UTC time zone in an ISO-formatted timestamp, is optional.
values.value	Required. The metric value. Data type: Number

Headers

Table 36. Request headers
Header	Description
Accept	Data format of the response body. Only supports application/json.
Content-Type	Data format of the request body. Only supports application/json.

Table 37. 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 API HTTP response codes.

Table 38. Status codes
Status code	Description
200	Successful. The request was successfully processed.
401	Unauthorized. The user credentials are incorrect or have not been passed.
500	Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

Response body parameters (JSON or XML)


Name	Description
message	Message that indicates the status of the request, such as `ok` if the request processed successfully.

cURL request

curl "https://instance.servicenow.com/api/now/v1/clotho/put" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  \"seriesRef\": {
    \"subject\": \"3D666b051787333200a328c5b836cb0b92\",
    \"table\": \"mb_demo_drone\",
    \"metric\": \"mb_demo_mt_altitude\"
  },
  \"values\": [
    {
      \"timestamp\": \"2019-03-21T17:05:00Z\",
      \"value\": 0.150185
    },
    {
      \"timestamp\": \"2019-03-21T17:06:00Z\",
      \"value\": 0.46074
    },
    {
      \"timestamp\": \"2019-03-21T17:07:00Z\",
      \"value\": 0.83104
    },
    {
      \"timestamp\": \"2019-03-21T17:08:00Z\",
      \"value\": 1.260635
    },
    {
      \"timestamp\": \"2019-03-21T17:09:00Z\",
      \"value\": 1.749
    }
  ]
}" \
--user "username":"password"

{
    "result": {
        "message": "ok"
    }
}