Splunk® Enterprise

REST API Reference Manual

Download manual as PDF

This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Download topic as PDF

System

Use System endpoints to manage Splunk server configuration settings, including server-generated messages.

  • messages/
  • server/

messages

Provides access to Splunk system messages. Most messages are created by splunkd to inform the user of system problems.

Splunk Web typically displays these as bulletin board messages.

GET messages

Enumerate all systemwide messages. This is typically used for splunkd to advertise issues such as license quotas, license expirations, misconfigured indexes, and disk space.

Request

See Common GET request parameters.

Response

Attribute Description
restart_required Splunk system message indicating that restarting Splunk is required.

HTTP status codes

See HTTP status code table.

Example

This example lists all system messages.


curl -k -u admin:pass https://localhost:8089/services/messages


<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>messages</title>
  <id>https://localhost:8089/services/messages</id>
  <updated>2011-07-08T01:14:21-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/messages/_new" rel="create"/>
     ... opensearch elements elided ...
  <s:messages/>
  <entry>
    <title>restart_required</title>
    <id>https://localhost:8089/services/messages/restart_required</id>
    <updated>2011-07-08T01:14:21-07:00</updated>
    <link href="/services/messages/restart_required" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/messages/restart_required" rel="list"/>
    <link href="/services/messages/restart_required" rel="remove"/>
    <content type="text/xml">
      <s:dict>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="restart_required">Splunk must be restarted for changes to take effect.</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

POST messages

Create a persistent message displayed at /services/messages.

Request

Name Type Required Default Description
<name> String
Message name (key).
value String
Message text.
severity String Message severity level:
info: Informative
warn: Warning condition
error: Error condition

Response

No values returned for this request.

HTTP status codes

See HTTP status code table.

Example

Create/update a "hello world" message.


curl -k -u admin:pass https://localhost:8089/services/messages \
	-d name=helloMessage \
	-d value="hello world" \
	-d severity="info"


<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:s="http://dev.splunk.com/ns/rest"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>messages</title>
  <id>https://localhost:8089/services/messages</id>
  <updated>2014-02-20T10:24:02-08:00</updated>
  <generator build="197187" version="6.1beta"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/messages/_new" rel="create"/>
     ... opensearch elements elided ...
  <s:messages/>
  <entry>
    <title>helloMessage</title>
    <id>https://localhost:8089/services/messages/helloMessage</id>
    <updated>2014-02-20T10:24:02-08:00</updated>
    <link href="/services/messages/helloMessage" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/messages/helloMessage" rel="remove"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="helloMessage">"hello world"</s:key>
        <s:key name="eai:acl">
           ... elided ...
        </s:key>
        <s:key name="message">"hello world"</s:key>
        <s:key name="severity">info</s:key>
        <s:key name="timeCreated_epochSecs">1392920642</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

messages/{name}

DELETE messages/{name}

Deletes a message identified by {name}.

Request

No parameters for this request.

Response

No values returned for this request.

HTTP status codes

See HTTP status code table.

Example

This example deletes the message named message.

After invoking this operation, the message no longer displays on Splunk Web.


curl -k -u admin:pass --request DELETE https://localhost:8089/services/messages/message


<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>messages</title>
  <id>https://localhost:8089/services/messages</id>
  <updated>2011-07-08T01:14:21-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/messages/_new" rel="create"/>
     ... opensearch elements elided ...
  <s:messages/>
</feed>

GET messages/{name}

Get the entry corresponding to a single message identified by {name}.

Request

No parameters for this request.

Response

Attribute Description
eai:attributes See Accessing Splunk resources
message The system message.

HTTP status codes

See HTTP status code table.

Example

This example lists the message named "message."

curl -k -u admin:pass https://localhost:8089/services/messages/message
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>messages</title>
  <id>https://localhost:8089/services/messages</id>
  <updated>2011-07-08T01:14:21-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/messages/_new" rel="create"/>
     ... opensearch elements elided ...
  <s:messages/>
  <entry>
    <title>message</title>
    <id>https://localhost:8089/services/messages/message</id>
    <updated>2011-07-08T01:14:21-07:00</updated>
    <link href="/services/messages/message" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/messages/message" rel="list"/>
    <link href="/services/messages/message" rel="remove"/>
    <content type="text/xml">
      <s:dict>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="eai:attributes">
          <s:dict>
            <s:key name="optionalFields">
              <s:list/>
            </s:key>
            <s:key name="requiredFields">
              <s:list/>
            </s:key>
            <s:key name="wildcardFields">
              <s:list/>
            </s:key>
          </s:dict>
        </s:key>
        <s:key name="message">hello world</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

server/control

Allows access to controls, such as restarting server.

GET server/control

Lists the actions that can be performed at this endpoint.

Request

See Common GET request parameters.

Response

No values returned for this request.

HTTP status codes

See HTTP status code table.

Example

Displays actions available at server control endpoint.


curl -k -u admin:pass https://localhost:8089/services/server/control


<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>server-control</title>
  <id>https://localhost:8089/services/server/control</id>
  <updated>2011-07-12T00:17:53-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/server/control/restart" rel="restart"/>
     ... opensearch elements elided ...
  <s:messages/>
</feed>

server/control/restart

Allows for restarting Splunk.

POST server/control/restart

Restarts the Splunk server.

Request

No parameters for this request.

Response

No values returned for this request.

HTTP status codes

See HTTP status code table.

Example

Requests the Splunk process to restart.


curl -k -u admin:pass https://localhost:8089/services/server/control/restart -X POST


<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>server-control</title>
  <id>https://localhost:8089/services/server/control</id>
  <updated>2011-07-12T00:18:08-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/server/control/restart" rel="restart"/>
     ... opensearch elements elided ...
  <s:messages/>
</feed>

server/info

Provide Splunk Enterprise server configuration information.

GET server/info

List information about the running server.

Request

See Common GET request parameters.

Response data keys
Name Description
activeLicenseGroup Type of Splunk Enterprise license:
Enterprise
Forwarder
Free
Invalid
Trial
addOns Names of active Splunk Enterprise add-ons.
build The build number for this version of Splunk.
cpu_arch The architecture type for the CPU hosting splunkd.
guid Globally unique identifier for this server.
host TBD
host_fqdn host fully-qualified domain name.
isFree Indicates if this server is running Splunk under a free license.
isTrial Indicates if this server is using a trial license.
kv_store_status TBD
license_labels Labels associated with the license for this server.
licenseKeys License key unique for each license.
licenseSignature Hash signature for the license for this server.
licenseState Specifies the status of the license, which can be either OK or Expired.
master_guid Globally unique identifier for this server.
max_users TBD
mode Indicates whether the server is a dedicated forwarder. Possible values are:
normal
dedicated forwarder
numberOfCores Server number of processor cores. Not useful if host is a VM guest. 0 if the respective result cannot be acquired for some reason. That reason is logged to splunkd.log.
os_build Software build for this os_version.
os_name Operating system.
os_version Operating system version.
physicalMemoryMB Server physical memory (MB). Same as mem field of server/status/resource-usage/hostwide. 0 if the respective result cannot be acquired for some reason. That reason is logged to splunkd.log.
product_type Splunk product type:
enterprise
hunk
splunk
rtsearch_enabled Indicates if real-time search is enabled for this server.
server_roles Zero or more of the following possible server roles:
indexer
universal_forwarder
heavyweight_forwarder
lightweight_forwarder
license_master
license_slave
cluster_master
cluster_slave
cluster_search_head
deployment_server
deployment_client
search_head
search_peer

See also: server/roles endpoint.

serverName Server DNS domain name.
startup_time Server platform start time, in seconds since January 1, 1970 (UNIX epoch).
version os_build software version number.

HTTP status codes

See HTTP status code table.

Example

Lists information about the Splunk server.


curl -k -u admin:pass https://localhost:8089/services/server/info


<feed xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>server-info</title>
  <id>https://localhost:8089/services/server/info</id>
  <updated>2014-03-25T10:09:19-07:00</updated>
  <generator build="200839" version="6.1"/>
  <author>
    <name>Splunk</name>
  </author>
     ... opensearch elements elided ...
  <s:messages/>
  <entry>
    <title>server-info</title>
    <id>https://localhost:8089/services/server/info/server-info</id>
    <updated>2014-03-25T10:09:19-07:00</updated>
    <link href="/services/server/info/server-info" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/server/info/server-info" rel="list"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="activeLicenseGroup">Enterprise</s:key>
        <s:key name="addOns">
          <s:dict>
            <s:key name="hadoop">external_results_provider</s:key>
          </s:dict>
        </s:key>
        <s:key name="build">200839</s:key>
        <s:key name="cpu_arch">x64</s:key>
        <s:key name="eai:acl">
          ... elided ...
        </s:key>
        <s:key name="guid">9CBD8473-4E7D-4FF2-A042-050C5C27C298</s:key>
        <s:key name="isFree">0</s:key>
        <s:key name="isTrial">0</s:key>
        <s:key name="licenseKeys">
          <s:list>
            <s:item>BFE99AD913B0F7B63F9CB4A554CF3BC77A8D863919350BF1143FBCC38E680036</s:item>
          </s:list>
        </s:key>
        <s:key name="licenseSignature">f3c1efc6a429bb1eeb36580008f270e7</s:key>
        <s:key name="licenseState">OK</s:key>
        <s:key name="license_labels">
          <s:list>
            <s:item>Splunk Internal License DO NOT DISTRIBUTE</s:item>
          </s:list>
        </s:key>
        <s:key name="master_guid">9CBD8473-4E7D-4FF2-A042-050C5C27C298</s:key>
        <s:key name="mode">normal</s:key>
        <s:key name="numberOfCores">2</s:key>
        <s:key name="os_build">6</s:key>
        <s:key name="os_name">Windows</s:key>
        <s:key name="os_version">1</s:key>
        <s:key name="physicalMemoryMB">3982</s:key>
        <s:key name="product_type">splunk</s:key>
        <s:key name="rtsearch_enabled">1</s:key>
        <s:key name="serverName">SPLUNK-T420S</s:key>
        <s:key name="server_roles">
          <s:dict>
            <s:key name="indexer"/>
            <s:key name="license_master"/>
            <s:key name="license_slave"/>
          </s:dict>
        </s:key>
        <s:key name="startup_time">1395246838</s:key>
        <s:key name="version">6.1</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

server/logger

Provides access to splunkd logging categories, either specified in code or in $SPLUNK_HOME/etc/log.cfg.

GET server/logger

Enumerates all splunkd logging categories, either specified in code or in $SPLUNK_HOME/etc/log.cfg.

Request

See Common GET request parameters.

Response

Attribute Description
eai:acl See Access control lists for Splunk objects
level Logger level for this server.

Valid values: (FATAL | WARN | INFO | DEBUG)

HTTP status codes

See HTTP status code table.

Example

This example lists all logging categories for the Splunk server.

curl -k -u admin:pass https://localhost:8089/services/server/logger
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:s="http://dev.splunk.com/ns/rest"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>logger</title>
  <id>https://mrt:8089/services/server/logger</id>
  <updated>2011-05-16T20:29:38-0700</updated>
  <generator version="98144"/>
  <author>
    <name>Splunk</name>
  </author>
     ... opensearch elements elided ...
  <s:messages/>
  <entry>
    <title>AdminHandler:AuthenticationHandler</title>
    <id>https://mrt:8089/services/server/logger/AdminHandler%3AAuthenticationHandler</id>
    <updated>2011-05-16T20:29:38-0700</updated>
    <link href="/services/server/logger/AdminHandler%3AAuthenticationHandler" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/server/logger/AdminHandler%3AAuthenticationHandler" rel="list"/>
    <link href="/services/server/logger/AdminHandler%3AAuthenticationHandler" rel="edit"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="eai:acl">. . .</s:key>
        <s:key name="level">WARN</s:key>
      </s:dict>
    </content>
  </entry>
  . . .
  <entry>
    <title>Application</title>
    <id>https://mrt:8089/services/server/logger/Application</id>
    <updated>2011-05-16T20:29:38-0700</updated>
    <link href="/services/server/logger/Application" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/server/logger/Application" rel="list"/>
    <link href="/services/server/logger/Application" rel="edit"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="eai:acl">. . .</s:key>
        <s:key name="level">WARN</s:key>
      </s:dict>
    </content>
  </entry>
  <entry>
    <title>ApplicationManager</title>
    <id>https://mrt:8089/services/server/logger/ApplicationManager</id>
    <updated>2011-05-16T20:29:38-0700</updated>
    <link href="/services/server/logger/ApplicationManager" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/server/logger/ApplicationManager" rel="list"/>
    <link href="/services/server/logger/ApplicationManager" rel="edit"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="eai:acl">. . .</s:key>
        <s:key name="level">WARN</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

server/logger/{name}

GET server/logger/{name}

Describes a specific splunkd logging category.

Request

No parameters for this request.

Response

Attribute Description
eai:acl See Access control lists for Splunk objects
eai:attributes See Accessing Splunk resources
level Logger level for this server.

Valid values: (FATAL | WARN | INFO | DEBUG)

HTTP status codes

See HTTP status code table.

Example

Describes the logger for the Application Manager.


curl -k -u admin:pass https://localhost:8089/services/server/logger/Application


<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:s="http://dev.splunk.com/ns/rest"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>logger</title>
  <id>https://localhost:8089/services/server/logger</id>
  <updated>2011-07-02T15:10:44-07:00</updated>
  <generator version="100492"/>
  <author>
    <name>Splunk</name>
  </author>
     ... opensearch elements elided ...
  <s:messages/>
  <entry>
    <title>Application</title>
    <id>https://localhost:8089/services/server/logger/Application</id>
    <updated>2011-07-02T15:10:44-07:00</updated>
    <link href="/services/server/logger/Application" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/server/logger/Application" rel="list"/>
    <link href="/services/server/logger/Application" rel="edit"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="eai:acl">. . .</s:key>
        <s:key name="eai:attributes">
          <s:dict>
            <s:key name="optionalFields">
              <s:list/>
            </s:key>
            <s:key name="requiredFields">
              <s:list>
                <s:item>level</s:item>
              </s:list>
            </s:key>
            <s:key name="wildcardFields">
              <s:list/>
            </s:key>
          </s:dict>
        </s:key>
        <s:key name="level">WARN</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

POST server/logger/{name}

Sets the logging level for a specific logging category.

Request

Name Type Required Default Description
level Enum
Valid values: (FATAL | WARN | INFO | DEBUG)

The desired logging level for this category.

Response

No values returned for this request.

HTTP status codes

See HTTP status code table.

Example

Sets the level of ApplicationManager logger to INFO.


curl -k -u admin:pass https://localhost:8089/services/server/logger/Application \
	-d level=INFO


<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>logger</title>
  <id>https://localhost:8089/services/server/logger</id>
  <updated>2011-07-07T00:24:02-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <s:messages/>
</feed>

server/roles

Access the server role information. A server can have zero or more of the following roles:

indexer
universal_forwarder
heavyweight_forwarder
lightweight_forwarder
license_master
license_slave
cluster_master
cluster_slave
cluster_search_head
deployment_server
deployment_client
search_head
search_peer

See also: /server/info endpoint, server-roles attribute.

GET server/roles

Get the roles applicable to this server.

Request

None

Response

Name Description
<variable> List of defined roles, from the following possible server roles:
indexer
universal_forwarder
heavyweight_forwarder
lightweight_forwarder
license_master
license_slave
cluster_master
cluster_slave
cluster_search_head
deployment_server
deployment_client
search_head
search_peer

HTTP status codes

See HTTP status code table.

Example

curl -k -u admin:passwd https://localhost:8089/services/server/roles
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>server-roles</title>
  <id>https://localhost:8089/services/server/roles</id>
  <updated>2014-04-02T12:13:07-07:00</updated>
  <generator build="200839" version="6.1"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/server/roles/catalog_allPossible_predefined" rel="catalog_allPossible_predefined"/>
    ... opensearch elements elided ...
  <s:messages/>
  <entry>
    <title>result</title>
    <id>https://localhost:8089/services/server/roles/result</id>
    <updated>2014-04-02T12:13:07-07:00</updated>
    <link href="/services/server/roles/result" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/server/roles/result" rel="list"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="eai:acl">
            ... elided ...
        </s:key>
        <s:key name="indexer"/>
        <s:key name="license_master"/>
        <s:key name="license_slave"/>
      </s:dict>
    </content>
  </entry>
</feed>

server/settings

Provides access to server configuration information for an instance of Splunk.

GET server/settings

Returns the server configuration of an instance of Splunk.

Request

See Common GET request parameters.

Response

Attribute Description
SPLUNK_DB Absolute filepath to the default index for this instance of Splunk.
SPLUNK_HOME Absolute filepath to the local installation of this instance of Splunk.
enableSplunkWebSSL Indicates if https and SSL is enabled for Splunk Web.
host The default hostname to use for data inputs that do not override this setting.
httpport Port on which Splunk Web is listening for this instance of Splunk.

Defaults to 8000. If using SSL, set to the HTTPS port number.

mgmtHostPort The port on which Splunk Web is listening for management operations. Defaults to 8089.
minFreeSpace Safe amount of space in MB that must exist for splunkd to continue operating.

minFreespace affects search and indexing:

Before attempting to launch a search, splunk requires this amount of free space on the filesystem where the dispatch directory is stored ($SPLUNK_HOME/var/run/splunk/dispatch).

Applied similarly to the search quota values in authorize.conf and limits.conf.

For indexing, periodically, the indexer checks space on all partitions that contain splunk indexes as specified by indexes.conf. When you need to clear more disk space, indexing is paused and Splunk posts a ui banner + warning.

pass4SymmKey Password string that is prefixed to the Splunk symmetric key, generating the final key to sign all traffic between master/slave licenser.
serverName Name used to identify this Splunk instance for features such as distributed search.
sessionTimeout Time range string to set the amount of time before a user session times out, expressed as a search-like time range. Default is 1h (one hour).

For example:

24h: (24 hours)

3d: (3 days)

7200s: (7200 seconds, or two hours)

startwebserver Indicates if Splunk Web is started.
trustedIP The IP address of the authenticating proxy. Set to a valid IP address to enable SSO.

Disabled by default. Normal value is '127.0.0.1'

HTTP status codes

See HTTP status code table.

Example

List the server configuration of this instance of Splunk.


curl -k -u admin:pass https://localhost:8089/services/server/settings


<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>server-settings</title>
  <id>https://localhost:8089/services/server/settings</id>
  <updated>2011-07-08T01:56:40-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
     ... opensearch elements elided ...
  <s:messages/>
  <entry>
    <title>settings</title>
    <id>https://localhost:8089/services/server/settings/settings</id>
    <updated>2011-07-08T01:56:40-07:00</updated>
    <link href="/services/server/settings/settings" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/server/settings/settings" rel="list"/>
    <link href="/services/server/settings/settings" rel="edit"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="SPLUNK_DB">/home/amrit/temp/curl/splunk/var/lib/splunk</s:key>
        <s:key name="SPLUNK_HOME">/home/amrit/temp/curl/splunk</s:key>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="enableSplunkWebSSL">0</s:key>
        <s:key name="host">MrT</s:key>
        <s:key name="httpport">8001</s:key>
        <s:key name="mgmtHostPort">8085</s:key>
        <s:key name="minFreeSpace">2000000</s:key>
        <s:key name="pass4SymmKey">changeme</s:key>
        <s:key name="serverName">MrT</s:key>
        <s:key name="sessionTimeout">1h</s:key>
        <s:key name="startwebserver">1</s:key>
        <s:key name="trustedIP"/>
      </s:dict>
    </content>
  </entry>
</feed>

server/status

Access system status information.

GET server/status

Enumerate server/status endpoints.

Request

None

Response

List of server/status/ child endpoints.

Note: The server/status/limits/ and server/status/resource-usage/ endpoints are not listed. A bug report has been submitted.

HTTP status codes

See HTTP status code table.

Example

curl -k -u admin:passwd https://localhost:8089/services/server/status
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest">
  <title></title>
  <id>https://localhost:8089/services/server/status</id>
  <updated>2014-03-25T13:52:59-07:00</updated>
  <generator build="200839" version="6.1"/>
  <author>
    <name>Splunk</name>
  </author>
  <s:messages/>
  <entry>
    <title>dispatch-artifacts</title>
    <id>https://localhost:8089/services/server/status/dispatch-artifacts</id>
    <updated>2014-03-25T13:52:59-07:00</updated>
    <link href="/services/server/status/dispatch-artifacts" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/server/status/dispatch-artifacts" rel="list"/>
    <content type="text/xml">
      <s:dict/>
    </content>
  </entry>
  <entry>
    <title>fishbucket</title>
    <id>https://localhost:8089/services/server/status/fishbucket</id>
    <updated>2014-03-25T13:52:59-07:00</updated>
    <link href="/services/server/status/fishbucket" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/server/status/fishbucket" rel="list"/>
    <content type="text/xml">
      <s:dict/>
    </content>
  </entry>
  <entry>
    <title>partitions-space</title>
    <id>https://localhost:8089/services/server/status/partitions-space</id>
    <updated>2014-03-25T13:52:59-07:00</updated>
    <link href="/services/server/status/partitions-space" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/server/status/partitions-space" rel="list"/>
    <content type="text/xml">
      <s:dict/>
    </content>
  </entry>
</feed>

server/status/dispatch-artifacts

Access search job information.

Note: At least one observation period must pass after Splunk Enterprise startup for valid endpoint data to be available. The observation period is defined in the $SPLUNK_HOME/etc/system/default/server.conf file:

[introspection:generator:disk_objects]
collectionPeriodInSecs = 600

The default period is 10 seconds, but 10 minutes (600 seconds) on a Universal Forwarder.

GET server/status/dispatch-artifacts

Get information about dispatched search jobs.

Request

None

Response

Attribute Description
count_realtime Jobs active in the immediate past observation period, not including historical jobs.
count_scheduled Jobs active in the immediate past observation period, not including real-time jobs.
count_summary Jobs active in the immediate past observation period, not including non-summary jobs.
top_apps Top 15 apps in the past observation period, inapp:count key-value pair format.
top_named_searches Top 15 named searches in the past observation period, in savedSearchName:count key-value pair format.
top_users Top 15 users in the past observation period, in username:count key-value pair format, with count as the number of app contexts for the user.
total_count Number of dispatched search jobs since start-up.

HTTP status codes

See HTTP status code table.

Example

curl -k -u admin:passwd https://localhost:8089/services/server/status/dispatch-artifacts
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>introspection--disk-objects--search-dispatch-artifacts</title>
  <id>https://localhost:8089/services/server/status/dispatch-artifacts</id>
  <updated>2014-03-25T11:10:33-07:00</updated>
  <generator build="200839" version="6.1"/>
  <author>
    <name>Splunk</name>
  </author>
     ... opensearch elements elided ...
  <s:messages/>
  <entry>
    <title>result</title>
    <id>https://localhost:8089/services/server/status/dispatch-artifacts/result</id>
    <updated>2014-03-25T11:10:33-07:00</updated>
    <link href="/services/server/status/dispatch-artifacts/result" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/server/status/dispatch-artifacts/result" rel="list"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="count_realtime">0</s:key>
        <s:key name="count_scheduled">0</s:key>
        <s:key name="count_summary">0</s:key>
        <s:key name="eai:acl">
          ... elided ...
        </s:key>
        <s:key name="top_apps"/>
        <s:key name="top_named_searches"/>
        <s:key name="top_users"/>
        <s:key name="total_count">0</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

server/status/fishbucket

Access information about the private BTree database.

Note: At least one observation period must pass after Splunk Enterprise startup for valid endpoint data to be available. The observation period is defined in the $SPLUNK_HOME/etc/system/default/server.conf file:

[introspection:generator:disk_objects]
collectionPeriodInSecs = 600

The default period is 10 seconds, but 10 minutes (600 seconds) on a Universal Forwarder.

GET server/status/fishbucket

Request

None

Response

Attribute Description
key_count Number of file input records (keys) seen since start-up.
total_size Total number of file input records (keys).

HTTP status codes

See HTTP status code table.

Example

curl -k -u admin:passwd https://localhost:8089/services/server/status/fishbucket
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>introspection--disk-objects--fishbucket</title>
  <id>https://localhost:8089/services/server/status/fishbucket</id>
  <updated>2014-03-25T11:31:10-07:00</updated>
  <generator build="200839" version="6.1"/>
  <author>
    <name>Splunk</name>
  </author>
     ... opensearch elements elided ...
  <s:messages/>
  <entry>
    <title>result</title>
    <id>https://localhost:8089/services/server/status/fishbucket/result</id>
    <updated>2014-03-25T11:31:10-07:00</updated>
    <link href="/services/server/status/fishbucket/result" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/server/status/fishbucket/result" rel="list"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="eai:acl">
          ... elided ...
        </s:key>
        <s:key name="key_count">0</s:key>
        <s:key name="total_size">0.000</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

server/status/limits/search-concurrency

Access search concurrency metrics.

GET server/status/limits/search-concurrency

Get search concurrency limits for a standalone Splunk instance.

Request

None

Response

Attribute Description
max_auto_summary_searches Maximum number of auto summary searches.
max_hist_scheduled_searches Maximum number of historical scheduled searches.
max_hist_searches Maximum number of historical searches.
max_rt_scheduled_searches Maximum number of scheduled searches.
max_rt_searches Maximum number of real-time searches.

HTTP status codes

See HTTP status code table.

Example

curl -k -u admin:passwd https://localhost:8089/services/server/status/limits/search-concurrency
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>server-status-limits-concurrency</title>
  <id>https://localhost:8089/services/server/status/limits/search-concurrency</id>
  <updated>2014-03-25T11:40:16-07:00</updated>
  <generator build="200839" version="6.1"/>
  <author>
    <name>Splunk</name>
  </author>
     ... opensearch elements elided ...
  <s:messages/>
  <entry>
    <title>search-concurrency</title>
    <id>https://localhost:8089/services/server/status/limits/search-concurrency/search-concurrency</id>
    <updated>2014-03-25T11:40:16-07:00</updated>
    <link href="/services/server/status/limits/search-concurrency/search-concurrency" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/server/status/limits/search-concurrency/search-concurrency" rel="list"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="eai:acl">
          ... elided ...
        </s:key>
        <s:key name="max_auto_summary_searches">2</s:key>
        <s:key name="max_hist_scheduled_searches">5</s:key>
        <s:key name="max_hist_searches">10</s:key>
        <s:key name="max_rt_scheduled_searches">5</s:key>
        <s:key name="max_rt_searches">10</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

server/status/partitions-space

Access disk utilization information for filesystems that have Splunk Enterprise disk objects, such as indexes, volumes, and logs. A filesystem can span multiple physical disk partitions.

Note: At least one observation period must pass after Splunk Enterprise startup for valid endpoint data to be available. The observation period is defined in the $SPLUNK_HOME/etc/system/default/server.conf file:

[introspection:generator:disk_objects]
collectionPeriodInSecs = 600

The default period is 10 seconds, but 10 minutes (600 seconds) on a Universal Forwarder.

GET server/status/partitions-space

Enumerate filesystem endpoints.

Request

See Common GET request parameters.

Response

Attribute Description
capacity Disk capacity (MB).
free Disk free space (MB).
fs_type File system type.

Example values:
Linux: ext2, ext3, ext4, qnx4
Solaris: ufs, zfs
Windows: ntfs, fat32
AIX: jfs
(not OS-specific) WORM: ISO9660, UDF13346
(not OS-specific); network-shared: SMB, CIFS, NFS
(not OS-specific) Veritas: VxFS.

mount_point Absolute path of the directory where this partition is mounted.

HTTP status codes

See HTTP status code table.

Example

curl -k -u admin:passwd https://localhost:8089/services/server/status/partitions-space
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>introspection--disk-objects--partitions-space</title>
  <id>https://localhost:8089/services/server/status/partitions-space</id>
  <updated>2014-03-25T11:43:39-07:00</updated>
  <generator build="200839" version="6.1"/>
  <author>
    <name>Splunk</name>
  </author>
     ... opensearch elements elided ...
  <s:messages/>
  <entry>
    <title>0</title>
    <id>https://localhost:8089/services/server/status/partitions-space/0</id>
    <updated>2014-03-25T11:43:39-07:00</updated>
    <link href="/services/server/status/partitions-space/0" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/server/status/partitions-space/0" rel="list"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="capacity">104901.000</s:key>
        <s:key name="eai:acl">
          ... elided ...
        </s:key>
        <s:key name="free">7774.000</s:key>
        <s:key name="fs_type">ntfs</s:key>
        <s:key name="mount_point">C:\</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

server/status/resource-usage

Learn the current levels of resource (CPU, RAM, VM, I/O, file handle) utilization for entire host, and per Splunk-related processes.

Note: At least one observation period must pass after Splunk Enterprise startup for valid endpoint data to be available. The observation period is defined in the $SPLUNK_HOME/etc/system/default/server.conf file:

[introspection:generator:resource_usage]
collectionPeriodInSecs = 600

The default period is 10 seconds, but 10 minutes (600 seconds) on a Universal Forwarder.

GET server/status/resource-usage

Enumerate server/status/resource-usage/ endpoints.

Request

See Common GET request parameters.

Response

List of server/status/resource-usage/ endpoints.

HTTP status codes

See HTTP status code table.

Example

curl -k -u admin:passwd https://localhost:8089/services/server/status/resource-usage
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest">
  <title></title>
  <id>https://localhost:8089/services/server/status/resource-usage</id>
  <updated>2014-03-25T11:53:26-07:00</updated>
  <generator build="200839" version="6.1"/>
  <author>
    <name>Splunk</name>
  </author>
  <s:messages/>
  <entry>
    <title>hostwide</title>
    <id>https://localhost:8089/services/server/status/resource-usage/hostwide</id>
    <updated>2014-03-25T11:53:26-07:00</updated>
    <link href="/services/server/status/resource-usage/hostwide" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/server/status/resource-usage/hostwide" rel="list"/>
    <content type="text/xml">
      <s:dict/>
    </content>
  </entry>
  <entry>
    <title>splunk-processes</title>
    <id>https://localhost:8089/services/server/status/resource-usage/splunk-processes</id>
    <updated>2014-03-25T11:53:26-07:00</updated>
    <link href="/services/server/status/resource-usage/splunk-processes" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/server/status/resource-usage/splunk-processes" rel="list"/>
    <content type="text/xml">
      <s:dict/>
    </content>
  </entry>
</feed>

server/status/resource-usage/hostwide

Access host-level, dynamic CPU utilization and paging information.

Note: At least one observation period must pass after Splunk Enterprise startup for valid endpoint data to be available. The observation period is defined in the $SPLUNK_HOME/etc/system/default/server.conf file:

[introspection:generator:resource_usage]
collectionPeriodInSecs = 600

The default period is 10 seconds, but 10 minutes (600 seconds) on a Universal Forwarder.

GET server/status/resource-usage/hostwide

Get host-level, dynamic CPU utilization and paging information.

Request

None

Response

pg_swapped_out in the example, below.]

Attribute Description
cpu_idle_pct Percentage of time CPU is idle. Value reported as 100.0 on Windows except for Vista+ and XP/Win2003 English-only OSes.
cpu_system_pct Percentage of time CPU is running in system mode. Missing from Windows except for Vista+ and XP/Win2003 English-only OSes.
cpu_user_pct Percentage of time CPU is running in user mode. Missing from Windows except for Vista+ and XP/Win2003 English-only OSes.
forks Cumulative number of forked processes since OS startup. Not available on Windows.
mem Total physical memory available.
mem_used Total physical memory used.
normalized_load_avg_1min Normalized load average of runnable_process_count across all cores (cumulative_load_avg / number_of_cores). This value is not reliable for a VM guest.
pg_paged_out Cumulative VM page count paged since OS startup. Not available on Windows.
pg_swapped_out Cumulative pages swapped out since OS startup. Not available on Windows.
runnable_process_count Number of process running or in the runnable queue. Value reported as 1 on Windows except for Vista+ and XP/Win2003 English-only OSes.
swap Amount of disk allocated to swap (fractional MB).
swap_used Swap space currently in use (fractional MB).

HTTP status codes

See HTTP status code table.

Example

curl -k -u admin:passwd https://localhost:8089/services/server/status/resource-usage/hostwide
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>introspection--resource-usage--hostwide</title>
  <id>https://localhost:8089/services/server/status/resource-usage/hostwide</id>
  <updated>2014-03-25T11:45:29-07:00</updated>
  <generator build="200839" version="6.1"/>
  <author>
    <name>Splunk</name>
  </author>
     ... opensearch elements elided ...
  <s:messages/>
  <entry>
    <title>result</title>
    <id>https://localhost:8089/services/server/status/resource-usage/hostwide/result</id>
    <updated>2014-03-25T11:45:29-07:00</updated>
    <link href="/services/server/status/resource-usage/hostwide/result" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/server/status/resource-usage/hostwide/result" rel="list"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="cpu_idle_pct">90.95</s:key>
        <s:key name="cpu_system_pct">4.84</s:key>
        <s:key name="cpu_user_pct">4.21</s:key>
        <s:key name="eai:acl">
          ... elided ...
        </s:key>
        <s:key name="mem">3982.234</s:key>
        <s:key name="mem_used">3193.137</s:key>
        <s:key name="runnable_process_count">1</s:key>
        <s:key name="swap">7962.652</s:key>
        <s:key name="swap_used">3244.652</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

server/status/resource-usage/splunk-processes

Access operating system resource utilization information.

Note: At least one observation period must pass after Splunk Enterprise startup for valid endpoint data to be available. The observation period is defined in the $SPLUNK_HOME/etc/system/default/server.conf file:

[introspection:generator:resource_usage]
collectionPeriodInSecs = 600

The default period is 10 seconds, but 10 minutes (600 seconds) on a Universal Forwarder.

GET server/status/resource-usage/splunk-processes

Get process operating system resource utilization information.

Request

None

Response

Attribute Description
args Non-search process arguments.
cpu_system_time Cumulative time this process has spent executing in kernel (incl. system calls). Extra field.
cpu_user_time Cumulative time this process has spent executing in user space (incl. library functions). Extra field.
elapsed Elapsed wall time, accurate to within the collection period.
fd_used Number of currently open files used by this process.
mem_unshared_data_used Amount of heap and stack used. Not available on Windows. Extra field.
mem_used Amount of resident / physical memory used, in megabytes.
normalized_pct_cpu Percentage of CPU usage across all cores. 100% is equivalent to all CPU resources on the machine.
page_faults Number of major page faults. Extra field.
pct_cpu Percentage of CPU usage, relative to one core. 100% is equivalent to 1 core.
pct_memory Percentage of physical memory used hostwide ((mem_used/available_host_memory) * 100).
pid Process ID.
ppid Parent process ID. Not available for all processes.
process Process name. The .exe suffix is stripped on Windows operating systems.
read_mb Amount of data read (MB), excluding cache reads.
search_props Search properties map of the following key:value pairs:
PropertyDescription
acceleration_idAcceleration ID.
appApp name.
modeSearch mode:
  • historical
  • historical batch
  • RT
  • RT indexed
provenanceSearch source:
  • cli
  • rest
  • ui:<App>:<View>
roleSplunk Enterprise platform role:
  • head
  • peer
sidSearch ID (SID).
typeSearch type:
  • ad-hoc
  • datamodel acceleration
  • other
  • report acceleration
  • scheduled
  • summary indexing
userSplunk Enterprise username who initiated the search.
status Status from the OS scheduler. Can be R (runnable or running), W (waiting), stopped, Z (zombie), or O (other). W includes voluntary sleep or blocking on I/O. O means status is knowable but doesn't fit into one of those categories. Not available on Windows.
t_count Current number of threads.
written_mb Amount of data written (MB), excluding canceled writes.

HTTP status codes

See HTTP status code table.

Example

curl -k -u admin:passwd https://localhost:8089/services/server/status/resource-usage/splunk-processes/0
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>introspection--resource-usage--splunk-processes</title>
  <id>https://localhost:8089/services/server/status/resource-usage/splunk-processes</id>
  <updated>2014-03-26T13:35:52-07:00</updated>
  <generator build="200839" version="6.1"/>
  <author>
    <name>Splunk</name>
  </author>
     ... opensearch elements elided ...
  <s:messages/>
  <entry>
    <title>0</title>
    <id>https://localhost:8089/services/server/status/resource-usage/splunk-processes/0</id>
    <updated>2014-03-26T13:35:52-07:00</updated>
    <link href="/services/server/status/resource-usage/splunk-processes/0" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/server/status/resource-usage/splunk-processes/0" rel="list"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="args"> instrument-resource-usage</s:key>
        <s:key name="eai:acl">
            ... elided ...
        </s:key>
        <s:key name="eai:attributes">
          <s:dict>
            <s:key name="optionalFields">
              <s:list/>
            </s:key>
            <s:key name="requiredFields">
              <s:list/>
            </s:key>
            <s:key name="wildcardFields">
              <s:list/>
            </s:key>
          </s:dict>
        </s:key>
        <s:key name="elapsed">619262.3610</s:key>
        <s:key name="mem_used">15.762</s:key>
        <s:key name="page_faults">12001684</s:key>
        <s:key name="pct_memory">0.40</s:key>
        <s:key name="pid">4256</s:key>
        <s:key name="ppid">2476</s:key>
        <s:key name="process">splunkd</s:key>
        <s:key name="t_count">4</s:key>
      </s:dict>
    </content>
  </entry>
</feed>
PREVIOUS
Search
  NEXT
Splunk REST API basics

This documentation applies to the following versions of Splunk® Enterprise: 6.1, 6.1.1, 6.1.2, 6.1.3, 6.1.4, 6.1.5, 6.1.6, 6.1.7, 6.1.8, 6.1.9, 6.1.10, 6.1.11, 6.1.12, 6.1.13, 6.1.14


Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

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