Take a moment to complete our quick CSAT survey.Fill the survey

Retrieve metric time series (MTS) latest

API for retrieving data points from a metric times series (MTS) for a given time window

Requirements

  • You must have an organization access token with the API permission or a session token to use the API.
API Base URL
https://api.{REALM}.signalfx.com/v1
Copy to clipboard

MTS retrieval for time window API endpoint URL

 
GET
/timeserieswindow
Copy full endpoint URL to clipboard

Retrieves data points for a MTS specified by text search or a time window or both. The request uses the following query parameters:

  • query: A query that searches metrics, dimensions, custom properties, and tags. The query language lets you use wildcards for names and values.
  • startMS: The starting point of a time window for the data points in the MTS.
  • endMS: The end point of a time window for the data points in the MTS.

Another query parameter, resolution, specifies the resolution that you want the system to use when returning data points. Because Splunk Observability Cloud stores MTS for a specified length of time according to resolution, it can return data points at a resolution of 1 second, 1 minute, 5 minutes, and 1 hour, regardless of the incoming data resolution.

This endpoint only returns default rollup values, which depend on the type of metric in the requested MTS. You can't override these values. The following list shows metric types and their corresponding rollup values:

  • Gauge: Average
  • Counter: Sum
  • Cumulative counter: Maximum

Note: Splunk Observability Cloud returns a maximum of 10,000 MTS, even if your organization contains more than 10,000. To learn more, see the Considerations for retrieve operations section in the developer guide.

Headers
Name
Description
X-SF-Token
Required
string

Authentication token. You can use a session token (User API access token) or an access token (org token) if the access token has the API authorization scope (authScope)

Query Parameters
Name
Description
endMS
integer <int64>
Example: 1557271830000

End point of the time window within which you want the system to search for matching MTS. Specify the value in *nix time in milliseconds.

query
string
Example: ((sf_metric:cpu.utilization AND _exists_:host_machine) OR region:us-east-1)

Search criteria that specifies the MTS that you want the API to return. You can search for the following:

  • Metric names
  • Dimension names
  • Specific values of a dimension
  • Custom properties
  • Specific values of a custom property
  • Tags

Search criteria have the following rules:

  • To search for a metric, use the field sf_metric. For example, sf_metric:<metric_name>. You may use wildcards in the metric name. This returns data points for all MTS that match the metric name.
  • To search for data points that have a dimension or property, regardless of the value, specify <name>:*
  • To search for specific values of a dimension or property, specify the name and value as <name>:<value>. If <value> contains non-alphanumeric characters, encode the non-alphanumeric characters and surround the value with double quotes. For example, the region custom property value US East must be passed in the parameter as region:"US%20East".
  • To search for names or values using wildcards, use * as the wildcard character. For example, to search for all values of the region dimension, use region:*.
  • You can do range searches on metrics, dimensions or properties using the syntax <name>:[<lower> to <upper>] (The value of <lower> must be less than or equal to <upper>). This works for numeric and alphabetic values.
  • To search MTS for the existence of dimensions or properties, use _exists_ and _missing_. For example, to search for MTS that have the host_machine dimension, specify _exists_:host_machine.
  • A single property name and value (or wildcards) make up a predicate that implicitly returns a Boolean.
  • Join predicates with the NOT, AND, and OR Boolean operators.
  • Use parentheses '(' and ')' to change the evaluation order.
resolution
integer <int32>

Resolution that the API should use for data points it returns.

Allowed values are 1000 (1 second), 60000 (1 minute), 300000 (5 minutes), and 3600000 (1 hour).

startMs
integer <int64>
Example: 1557264630000

Starting time of the time window within which you want the system to search for matching MTS. Specify the value in *nix time in milliseconds.

Code Examples
cURL
HTTP
curl -X GET "https://api.{REALM}.signalfx.com/v1/timeserieswindow" \
    -H "Content-Type: application/json" \
    -H "X-SF-Token: <value>"
Copy to clipboard
Response Body
Content Type: application/json

Successful MTS data point retrieval request

Name
Description
data
object

The data points for the MTS that match the search criteria and have timestamps within the specified time window. The number of data points is controlled by the resolution you request.

The data points are sorted in ascending order of timestamp (older data points appear first). Each data point is an array containing two values: the timestamp and the value itself.

errors
array[string]

Errors associated with the request. This array is always empty. If an error occurs, the API returns an error (non-200) status code.

Response Examples
Content Type: application/json
Collapse children
Copy to clipboard
{
  code: 200,
  data: {
    AAAAAAAAAAA: [
      [
        1705449600000,
        227.07710813246499
      ]
    ]
,
    AAAAAAAAAAE: [
      [
        1705449600000,
        122.4751087329639
      ]
    ]
  }
,
  errors: []
}