Splunk Observability Cloud Retrieve metric time series (MTS)
API for retrieving data points from a metric times series (MTS) for a given time window
OpenAPI Specification
openapi: 3.0.3
info:
title: Splunk Observability Cloud — Retrieve metric time series (MTS)
version: 4.0.0
description: '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.'
x-provenance:
method: reconstructed
authored_by: Splunk (content) / API Evangelist (assembly)
reconstructed_by: API Evangelist
reconstructed_on: '2026-08-19'
first_party: false
provider_published: false
note: Splunk's own OpenAPI objects, extracted from the React Server Component payload embedded in each of the 48 API reference
pages at dev.splunk.com. The operations and schemas are Splunk's; the assembly into standalone documents is API Evangelist's.
Splunk serves no fetchable spec file — dev.splunk.com answers 200 with an identical 6,638-byte shell for every asset
path, including invented control paths — so this is NOT first-party publication and is not graded as such.
x-evidence:
- type: source
url: https://dev.splunk.com/observability/reference/
- type: source
url: https://dev.splunk.com/observability/docs/apibasics/api_list/
servers:
- url: https://api.{REALM}.observability.splunkcloud.com/v1
description: MTS retrieval for time window API endpoint URL
variables:
REALM:
default: us0
description: Splunk Observability Cloud realm the organization is provisioned in (for example us0, us1, eu0, jp0, au0).
security:
- SessionToken: []
components:
securitySchemes:
SessionToken:
type: apiKey
in: header
name: X-SF-Token
description: Splunk Observability Cloud session token or org access token.
paths:
/timeserieswindow:
get:
summary: Retrieve MTS
description: '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.'
parameters:
- name: query
in: query
description: '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.'
schema:
type: string
- name: startMs
in: query
description: '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.'
schema:
type: integer
format: int64
- name: endMS
in: query
description: '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.'
schema:
type: integer
format: int64
- name: resolution
in: query
description: '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).'
schema:
type: integer
format: int32
- name: X-SF-Token
in: header
description: '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)'
required: true
schema:
type: string
responses:
'200':
description: HTTP 200 response
content:
application/json:
schema:
type: object
properties:
data:
type: object
additionalProperties:
type: object
additionalProperties:
type: array
items:
type: integer
format: int64
description: '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:
type: array
items:
type: string
description: Errors associated with the request. This array is always empty. If an error occurs, the API
returns an error (non-200) status code.
example:
code: 200
data:
AAAAAAAAAAA:
- - 1705449600000
- 227.07710813246499
AAAAAAAAAAE:
- - 1705449600000
- 122.4751087329639
errors: []
examples:
example:
value:
code: 200
data:
AAAAAAAAAAA:
- - 1705449600000
- 227.07710813246499
AAAAAAAAAAE:
- - 1705449600000
- 122.4751087329639
errors: []
'400':
description: HTTP 400 response
content:
application/json:
schema:
type: object
properties:
code:
type: integer
format: int32
description: HTTP response code. Always 400
message:
type: string
description: Error explanation
type:
type: string
description: Type of the status. Always "error".
example:
code: 400
message: 'API error: 400'
type: error
examples:
example:
value:
code: 400
message: 'API error: 400'
type: error
'401':
description: HTTP 401 response
content:
application/json:
schema:
type: object
properties:
code:
type: integer
format: int32
description: HTTP response code. Always 401
message:
type: string
description: Error explanation
type:
type: string
description: Type of the status. Always "error".
example:
code: 401
message: Authentication Required
type: error
examples:
example:
value:
code: 401
message: Authentication Required
type: error
'404':
description: HTTP 404 response
content:
application/json:
schema:
type: object
properties:
code:
type: integer
format: int32
description: HTTP response code. Always 404
message:
type: string
description: Error explanation
type:
type: string
description: Type of the status. Always "error".
example:
code: 404
message: 'API Error: 404'
type: error
examples:
example:
value:
code: 404
message: 'API Error: 404'
type: error
security:
- SessionToken: []
tags:
- Retrieve metric time series (MTS)