Splunk® Enterprise

REST API Reference Manual

Splunk Enterprise version 7.0 is no longer supported as of October 23, 2019. See the Splunk Software Support Policy for details. For information about upgrading to a supported version, see How to upgrade Splunk Enterprise.
This documentation does not apply to the most recent version of Splunk® Enterprise. For documentation on the most recent version, go to the latest release.

Metrics Catalog endpoint descriptions

Use the Metrics Catalog REST API to enumerate metrics and the dimensions and dimension values associated with metrics.

Usage details

Review ACL information for an endpoint

To check Access Control List (ACL) properties for an endpoint, append /acl to the path. For more information see Access Control List in the REST API User Manual.

Authentication and Authorization

Username and password authentication is required for access to endpoints and REST operations.

Splunk users must have role and/or capability-based authorization to use REST endpoints, and must have the list_metrics_catalog capability to use the Metrics Catalog endpoint. Users with an administrative role, such as admin, can access authorization information in Splunk Web. To view the roles assigned to a user, select Settings > Access controls > Users. To determine the capabilities assigned to a role, select Settings > Access controls > Roles.

Default indexes for Metrics Catalog endpoints

If no metric indexes are defined with the filter parameter, Metrics Catalog endpoints use the default indexes specified for the role of the user. To review or update the default indexes for specific roles, select Settings > Access controls > Roles, select a role, and review or update the Indexes searched by default field.

If the set of default indexes for a role includes a mix of metrics indexes and event indexes, the Metrics Catalog endpoints only use the metrics indexes.

If there are no metrics indexes, the Metrics Catalog endpoints display an empty list.

Splunk Cloud URL for REST API access

Splunk Cloud has a different host and management port syntax than Splunk Enterprise. Depending on your deployment type, use one of the following options to access REST API resources.

Managed Splunk Cloud deployments

Use the following URL for managed deployments. If necessary, submit a support case to open port 8089 on your deployment. Please include the IP Addresses/CIDR Ranges you would like to have access from. 

https://<deployment-name>.splunkcloud.com:8089

E-commerce Splunk Cloud deployments

Use the following URL for e-commerce deployments. To get the required non-SAML user credentials, submit a support case. 

http://api-<deployment-name>.cloud.splunk.com:8089

See Using the REST API in Splunk Cloud in the the Splunk REST API Tutorials for more information.

catalog/metricstore/metrics

https://<host>:<mPort>/services/catalog/metricstore/metrics

Use this endpoint to list metric names.

GET

Returns metric names.

Request parameters
Pagination and filtering parameters can be used with this method.

Name Type Description
earliest String A time string that specifies the earliest time for this search. Can be a relative or absolute time. The default value is -1d.
filter String A URL-encoded set of one or more key-value pairs, where keys correspond to metric fields such as index or dimension. For example, to specify a dimension named app, use filter=app. To specify two index names and values such as index=index1 and index=index2, use filter=index%3dindex1%26index%3dindex2.
latest String A time string that specifies the latest time for this search. Can be a relative or absolute time. The default value is now.
metric_name String The name of a metric.

Returned values
There are no returned values other than the metric names.

Example request and response

XML Request
List all metric names: 

curl -k -u admin:passwd https://localhost:8089/services/catalog/metricstore/metrics

XML Response

...
  <title>metricstore-metrics</title>
  <id>https://epic-metriks-splk.sv.splunk.com:8089/services/catalog/metricstore/metrics</id>
  <updated>2017-12-19T19:11:49+00:00</updated>
  <generator build="31fcdba9ddc1" version="7.0.0"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/catalog/metricstore/metrics/_acl" rel="_acl"/>
  <opensearch:totalResults>16</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
  <entry>
    <title>aws.ec2.CPUUtilization</title>
    <id>https://epic-metriks-splk.sv.splunk.com:8089/services/catalog/metricstore/metrics/aws.ec2.CPUUtilization</id>
    <updated>1970-01-01T00:00:00+00:00</updated>
    <link href="/services/catalog/metricstore/metrics/aws.ec2.CPUUtilization" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/catalog/metricstore/metrics/aws.ec2.CPUUtilization" rel="list"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="eai:acl">
          <s:dict>
            <s:key name="app"></s:key>
            <s:key name="can_list">0</s:key>
            <s:key name="can_write">0</s:key>
            <s:key name="modifiable">0</s:key>
            <s:key name="owner">system</s:key>
            <s:key name="perms">
              <s:dict>
                <s:key name="read">
                  <s:list>
                    <s:item>admin</s:item>
                    <s:item>bbuser</s:item>
                    <s:item>cat_read</s:item>
                    <s:item>power</s:item>
                    <s:item>splunk-system-role</s:item>
                    <s:item>statsd</s:item>
                    <s:item>user</s:item>
                  </s:list>
                </s:key>
                <s:key name="write">
                  <s:list/>
                </s:key>
              </s:dict>
            </s:key>
            <s:key name="removable">0</s:key>
            <s:key name="sharing">system</s:key>
          </s:dict>
        </s:key>
      </s:dict>
    </content>
  </entry>
  <entry>

Example requests

  • List all metric names that include the dimension field dc:
curl -k -u admin:passwd https://localhost:8089/services/catalog/metricstore/metrics?filter=dc
  • List all metric names that include either dc=east or dc=west dimension fields:
curl -k -u admin:passwd https://localhost:8089/services/catalog/metricstore/metrics?filter=dc%3deast&filter=dc%3dwest
  • List all metric names that are in index1 or index2:
curl -k -u admin:passwd https://localhost:8089/services/catalog/metricstore/metrics?filter=index%3dindex1%26index%3dindex2

catalog/metricstore/dimensions

https://<host>:<mPort>/services/catalog/metricstore/dimensions

Use this endpoint to list dimension names.

GET

Returns dimension names for a given metric.

Request parameters
Pagination and filtering parameters can be used with this method.

Name Type Description
earliest String Optional. A time string that specifies the earliest time for this search. Can be a relative or absolute time. The default value is -1d.
filter String Optional. A URL-encoded set of one or more key-value pairs, where keys correspond to metric fields such as index or dimension. For example, to specify a dimension named os, use filter=os. To specify two index names and values such asindex=index1 and index=index2, use filter=index%3dindex1%26index%3dindex2.
latest String Optional. A time string that specifies the latest time for this search. Can be a relative or absolute time. The default value is now.
metric_name String Required. The name of a metric.

Returned values
There are no returned values other than the dimension names.

Example request and response

XML Request

curl -k -u admin:passwd https://localhost:8089/services/catalog/metricstore/dimensions?metric_name=*

XML Response

...
  <title>metricstore-dimensions</title>
  <id>https://epic-metriks-splk.sv.splunk.com:8089/services/catalog/metricstore/dimensions</id>
  <updated>2017-12-19T00:02:27+00:00</updated>
  <generator build="31fcdba9ddc1" version="7.0.0"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/catalog/metricstore/dimensions/_acl" rel="_acl"/>
  <opensearch:totalResults>7</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
  <entry>
    <title>App</title>
    <id>https://epic-metriks-splk.sv.splunk.com:8089/services/catalog/metricstore/dimensions/App</id>
    <updated>1970-01-01T00:00:00+00:00</updated>
    <link href="/services/catalog/metricstore/dimensions/App" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/catalog/metricstore/dimensions/App" rel="list"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="eai:acl">
          <s:dict>
            <s:key name="app"></s:key>
            <s:key name="can_list">0</s:key>
            <s:key name="can_write">0</s:key>
            <s:key name="modifiable">0</s:key>
            <s:key name="owner">system</s:key>
            <s:key name="perms">
              <s:dict>
                <s:key name="read">
                  <s:list>
                    <s:item>admin</s:item>
                    <s:item>bbuser</s:item>
                    <s:item>cat_read</s:item>
                    <s:item>power</s:item>
                    <s:item>splunk-system-role</s:item>
                    <s:item>statsd</s:item>
                    <s:item>user</s:item>
                  </s:list>
                </s:key>
                <s:key name="write">
                  <s:list/>
                </s:key>
              </s:dict>
            </s:key>
            <s:key name="removable">0</s:key>
            <s:key name="sharing">system</s:key>
          </s:dict>
        </s:key>
      </s:dict>
    </content>
  </entry>

Another example request'

List all the dimension fields for the os.mem.free metric when the dc dimension field is limited to a value of east: 

curl -k -u admin:passwd https://localhost:8089/services/catalog/metricstore/dimensions?metric_name=mem.free&filter=dc%3deast

catalog/metricstore/dimensions/{dimension-name}/values

https://<host>:<mPort>/services/catalog/metricstore/dimensions/{dimension-name}/values

Use this endpoint to list values for given dimensions.

GET

Returns values of a dimension for a given metric.

Request parameters
Pagination and filtering parameters can be used with this method.

Name Type Description
earliest String Optional. A time string that specifies the earliest time for this search. Can be a relative or absolute time. The default value is -1d.
filter String Optional. A URL-encoded set of one or more key-value pairs, where keys correspond to metric fields such as index or dimension. For example, to specify a dimension named os, use filter=os. To specify two index names and values such asindex=index1 and index=index2, use filter=index%3dindex1%26index%3dindex2.
latest String Optional. A time string that specifies the latest time for this search. Can be a relative or absolute time. The default value is now.
metric_name String Required. The name of a metric.

Returned values
There are no returned values other than those of the selected dimension.

Example request and response

XML Request

List all values for the app dimension of the os.mem.free metric: 

curl -k -u statsd:statsd https://localhost:8089/services/catalog/metricstore/dimensions/app/values?metric_name=os.mem.free

XML Response 

...
  <title>metricstore-dimensions</title>
  <id>https://epic-metriks-splk.sv.splunk.com:8089/services/catalog/metricstore/dimensions</id>
  <updated>2017-12-19T02:05:19+00:00</updated>
  <generator build="31fcdba9ddc1" version="7.0.0"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/catalog/metricstore/dimensions/_acl" rel="_acl"/>
  <opensearch:totalResults>7</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
  <entry>
    <title>accountmanagement</title>
    <id>https://epic-metriks-splk.sv.splunk.com:8089/services/catalog/metricstore/dimensions/accountmanagement</id>
    <updated>1970-01-01T00:00:00+00:00</updated>
    <link href="/services/catalog/metricstore/dimensions/accountmanagement" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/catalog/metricstore/dimensions/accountmanagement" rel="list"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="eai:acl">
          <s:dict>
            <s:key name="app"></s:key>
            <s:key name="can_list">0</s:key>
            <s:key name="can_write">0</s:key>
            <s:key name="modifiable">0</s:key>
            <s:key name="owner">system</s:key>
            <s:key name="perms">
              <s:dict>
                <s:key name="read">
                  <s:list>
                    <s:item>admin</s:item>
                    <s:item>bbuser</s:item>
                    <s:item>cat_read</s:item>
                    <s:item>power</s:item>
                    <s:item>splunk-system-role</s:item>
                    <s:item>statsd</s:item>
                    <s:item>user</s:item>
                  </s:list>
                </s:key>
                <s:key name="write">
                  <s:list/>
                </s:key>
              </s:dict>
            </s:key>
            <s:key name="removable">0</s:key>
            <s:key name="sharing">system</s:key>
          </s:dict>
        </s:key>
      </s:dict>
    </content>
  </entry>

More example requests

  • List all values for the dc dimension of the os.mem.free metric, where dc is limited to a value of east:
curl -k -u admin:passwd https://localhost:8089/services/catalog/metricstore/dimensions/dc/values?metric_name=os.mem.free&filter=dc%3deast
  • List all values for the dc dimension of the mem.free metric, where the recorded measurements also have an os dimension field:
curl -k -u admin:passwd https://localhost:8089/services/catalog/metricstore/dimensions/dc/values?metric_name=mem.free&filter=os
Last modified on 11 January, 2021
License endpoint descriptions   Output endpoint descriptions

This documentation applies to the following versions of Splunk® Enterprise: 7.0.0, 7.0.1, 7.0.2, 7.0.3, 7.0.4, 7.0.5, 7.0.6, 7.0.7, 7.0.8, 7.0.9, 7.0.10, 7.0.11, 7.0.13

Acrobat logo Download manual
Acrobat logo Download this page

Was this topic useful?







You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters