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 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)

NameDescription
label Label used to identify this metric’s result set.

Data type: String
seriesRef Data series results.

Data type: Array of Objects

"seriesRef": [
  {
    "metric": "String",
    "subject": "String",
    "table": "String"
  }
]
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
seriesRef.subject Sys_id of the data series record. Located in the table specified in seriesRef.table.

Data type: String
seriesRef.table Name of the table from where the data series was obtained.

Data type: String
values Transformed series values.

Data type: Array of Objects

"values": [
  {
    "timestamp": "String",
    "value": Number
  }
]
values.timestamp Timestamp of the value.

Data type: String

Format: ISO 8601
values.value Metric values.

Data type: Number

Example: 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 9. 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 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)

NameDescription
label Label used to identify this metric’s result set.

Data type: String
seriesRef Data series results.

Data type: Array of Objects

"seriesRef": [
  {
    "metric": "String",
    "subject": "String",
    "table": "String"
  }
]
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
seriesRef.subject Sys_id of the data series record. Located in the table specified in seriesRef.table.

Data type: String
seriesRef.table Name of the table from where the data series was obtained.

Data type: String
values Transformed series values.

Data type: Array of Objects

"values": [
  {
    "timestamp": "String",
    "value": Number
  }
]
values.timestamp Timestamp of the value.

Data type: String

Format: ISO 8601
values.value Metric values.

Data type: Number

Example: 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: Don't ignore unknown series.

Default: 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 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.

Example: 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

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 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.

Response body parameters (JSON or XML)

Supported transforms

Table 25. Transform data types
TransformDescription
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:
  1. -IQR: The median of all entries below Q1 - (1.5 * IQR).
  2. Q1: The median of the smallest half of entries.
  3. Q3: The median of the largest half of entries.
  4. +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.
  • 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.

  • window (Duration data type): The duration of the non-overlapping window to apply the aggregator.
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 typeDescription
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.

Example: 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

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 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.

Response body parameters (Octet-stream or JSON)

Supported transforms

Table 32. Transform data types
TransformDescription
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:
  1. -IQR: The median of all entries below Q1 - (1.5 * IQR).
  2. Q1: The median of the smallest half of entries.
  3. Q3: The median of the largest half of entries.
  4. +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.
  • 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.

  • window (Duration data type): The duration of the non-overlapping window to apply the aggregator.
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 typeDescription
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.

Example: 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
  }
]

Example

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

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 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.

Example: 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"
    }
}