Splunk responses to REST operations
Contents
Splunk responses to REST operations
With few exceptions, Splunk returns responses to REST API operations in the Atom Syndication Format, also known as an Atom Feed.
Note: New to Atom? For an introduction go to AtomEnabled.org.
You can use the output_mode parameter to a GET operation to override the default behavior, and instead return results in JSON format. For example, to return information for all locally installed apps in JSON format, specify GET apps/local as:
curl -k -u admin:pass https://localhost:8089/services/apps/local --get -d output_mode=json
For some search endpoints, Splunk provides additional options to return data in JSON, XML, and other formats. See JSON and other response formats below.
Atom Feed responses
Each Splunk response includes the following containers:
- <feed> top-level element containing metadata plus one or more entries.
- <entry> contains metadata, plus the content element.
- <content> provides key/value pairs returned by the Splunk operation.
The Feed, Entry, and Content sections below describe the meanings of elements within those containers.
Feed element
<feed> <title>. . .</title> <id>. . .</id> <updated>. . .</updated> <generator /> <author>. . .</author> <link>. . .</link> <opensearch:totalResults>...</opensearch:totalResults> <opensearch:itemsPerPage>...</opensearch:itemsPerPage> <opensearch:startIndex>...</opensearch:startIndex> <s:messages>. . .</messages> <entry>...</entry> <entry>...</entry> . . . </feed>
| Name | Description |
|---|---|
| title | Human readable name of the endpoint, typically derived from the last node of the endpoint. |
| id | Splunk management URL for accessing the endpoint. |
| updated | Date this endpoint was implemented in Splunk |
| generator | Lists the version of the Atom Feed generator. |
| author | Splunk is the author for all responses. |
| link | URI for the endpoint, relative to the management port of a Splunk instance |
| opensearch | For GET operations, these elements list the pagination attributes of a response:
See GET parameter list. |
| messages | Displays any info, warning, or error messages associated with the operation.
Not all responses display messages. |
| entry | A result returned from the operation. See Entry element below. |
Entry element
Endpoints that return lists of entry elements typically sort the entries by entry name as listed in the <title> tag. Certain endpoints override this default ordering of endpoints. For example, search/jobs lists entries in descending order by dispatch time, as listed in the <published> tag.
This section describes tags commonly found in returned entries. Some endpoints contain tags specific to that endpoint.
<entry>
<messages>...</messages>
<title>. . .</title>
<id>. . .</id>
<updated>. . .</updated>
<link>. . .</link>
<author>. . .</author>
<link>. . .</link>
<link>. . .</link>
. . .
<content>. . .</content>
</entry>
| Name | Description |
|---|---|
| messages | Displays any info, warning, or error messages associated with the entry.
Not all entries display messages |
| title | Human readable name for the returned entry. The value of title depends on the endpoint accessed. |
| id | Splunk management URL for accessing the endpoint. |
| updated | Date the value for this entry was updated in Splunk |
| link | URI for the endpoint to this entry, relative to the management port of a Splunk instance. |
| author | The owner of this resource, as defined in the access control list. The value can be:
Refer to Access control lists for Splunk objects in the section Accessing Splunk resources. |
| link | One or more URIs for the endpoint to this entry, relative to the management port of a Splunk instance. Each URI lists an action available for this endpoint. Possible actions include:
|
| content | Container for content returned by the operation for an entry. Typically, Splunk returns content as dictionaries with key/value pairs that list properties of the entry. However, content can be returned as a list of values or as inline plain text. |
Content element
Container for content returned by the operation for an entry. Typically, Splunk returns content as dictionaries with key/value pairs that list properties of the entry. However, content can be returned as a list of values or as inline plain text.
The key value pairs present depend on the endpoint and REST operation. Not all entries have all the elements listed here. Some key value pairs will be unique to some endpoints.
The following example shows content returned as a dictionary.
<content>
<s:dict>
<s:key name="...">. . .</s:key>
<s:list>
<s:item>. . .</s:item>
. . .
</s:list>
<s:key name="...">. . .</s:key>
. . .
<s:key name="eai:acl">
<s:dict>
<s:key name="app">...</s:key>
<s:key name="can_write">...</s:key>
. . .
</s:dict>
</s:key>
<s:key name="eai:attributes">
<s:dict>
<s:key name="optionalFields">...</s:key>
<s:key name="requiredFields">...</s:key>
<s:key name="wildcardFields">...</s:key>
</s:dict>
</s:key>
. . .
</s:dict>
</content>
| Name | Description |
|---|---|
| dict | Container for holding related properties. |
| list | Container for listing values. |
| key | Element defining a key/value pair. |
| key name="eai:acl" | The access control list for a resource, listing the permissions for accessing the endpoint. See Access control lists for Splunk objects. |
| key name="eai:attributes" | Lists the eai attributes for the resource.
|
JSON and other response formats
For some search endpoints, Splunk provides options to return data in alternate formats. For the following endpoints, use the output_mode parameter to the GET operation to specify the format for the output. The default output mode for these endpoints is indicated in bold.
- GET search/jobs/export
atom, csv, json, json_cols, json_rows, raw, xml
See below for details on the returned JSON output for this endpoint.
JSON output for GET search/jobs/export
The JSON output for GET search/jobs/export has changed for Splunk 5.
You typically use GET search/jobs/export to export large amounts of data from Splunk. In Splunk 5, to support real-time streaming of large amounts of data in JSON format, each row of data is exported as an individual JSON object when rows are delimited by a newline. The exported JSON indicates when a preview is closed.
For details and an example, see the description for this endpoint in the REST API reference.
Search example to show output modes
The results from the following example search illustrate the different output formats:
index="_internal" source="*metrics.log" group="*" name="*" earliest="@w1" latest="+7d@w6"The search ID for the example search was passed to GET search/jobs/{search_id}/results:
curl -k -u admin:pass https://localhost:8089/services/search/jobs/<searchid>/results --get \ -d f=source -d f=sourcetype -d f=host -d f=group -d f=name -d count=3 \ -d output_mode=<output_mode>
atom
Results of sample search in atom format:
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest">
<title>Search Results</title>
<id>/services/search/jobs/49</id>
<updated>2012-10-27T09:06:02-07:00</updated>
<generator build="138753" version="5.0"/>
<author>
<name>Splunk</name>
</author>
<entry>
<title>Result Offset 0</title>
<id>/services/search/jobs/49/results?output_mode=atom&count=1&offset=0</id>
<updated>2012-10-27T09:06:02-07:00</updated>
<link href="/services/search/jobs/49/results?output_mode=atom&count=1&offset=0" rel="alternate"/>
<content type="text/xml">
<s:dict>
<s:key name="source">/Applications/splunk-ace/var/log/splunk/metrics.log</s:key>
<s:key name="sourcetype">splunkd</s:key>
<s:key name="host">splunks-ombra.sv.splunk.com</s:key>
<s:key name="group">tpool</s:key>
<s:key name="name">indexertpool</s:key>
</s:dict>
</content>
</entry>
<entry>
<title>Result Offset 1</title>
<id>/services/search/jobs/49/results?output_mode=atom&count=1&offset=1</id>
<updated>2012-10-27T09:06:02-07:00</updated>
<link href="/services/search/jobs/49/results?output_mode=atom&count=1&offset=1" rel="alternate"/>
<content type="text/xml">
<s:dict>
<s:key name="source">/Applications/splunk-ace/var/log/splunk/metrics.log</s:key>
<s:key name="sourcetype">splunkd</s:key>
<s:key name="host">splunks-ombra.sv.splunk.com</s:key>
<s:key name="group">tpool</s:key>
<s:key name="name">bundlereplthreadpool</s:key>
</s:dict>
</content>
</entry>
<entry>
<title>Result Offset 2</title>
<id>/services/search/jobs/49/results?output_mode=atom&count=1&offset=2</id>
<updated>2012-10-27T09:06:02-07:00</updated>
<link href="/services/search/jobs/49/results?output_mode=atom&count=1&offset=2" rel="alternate"/>
<content type="text/xml">
<s:dict>
<s:key name="source">/Applications/splunk-ace/var/log/splunk/metrics.log</s:key>
<s:key name="sourcetype">splunkd</s:key>
<s:key name="host">splunks-ombra.sv.splunk.com</s:key>
<s:key name="group">tpool</s:key>
<s:key name="name">batchreadertpool</s:key>
</s:dict>
</content>
</entry>
</feed>
csv
Results of sample search in comma-separated values (CSV) format:
source,sourcetype,host,group,name "/Applications/splunk-ace/var/log/splunk/metrics.log",splunkd,"splunks-ombra.sv.splunk.com",tpool,indexertpool "/Applications/splunk-ace/var/log/splunk/metrics.log",splunkd,"splunks-ombra.sv.splunk.com",tpool,bundlereplthreadpool "/Applications/splunk-ace/var/log/splunk/metrics.log",splunkd,"splunks-ombra.sv.splunk.com",tpool,batchreadertpool
json
Results of sample search in json format:
{ "init_offset" : 0,
"messages" : [ { "text" : "base lispy: [ AND index::_internal source::*metrics.log ]",
"type" : "DEBUG"
},
{ "text" : "search context: user=\"admin\", app=\"search\", bs-pathname=\"/Applications/splunk-ace/etc\"",
"type" : "DEBUG"
},
{ "text" : "Your timerange was substituted based on your search string",
"type" : "INFO"
}
],
"preview" : false,
"results" : [ { "group" : "tpool",
"host" : "splunks-ombra.sv.splunk.com",
"name" : "indexertpool",
"source" : "/Applications/splunk-ace/var/log/splunk/metrics.log",
"sourcetype" : "splunkd"
},
{ "group" : "tpool",
"host" : "splunks-ombra.sv.splunk.com",
"name" : "bundlereplthreadpool",
"source" : "/Applications/splunk-ace/var/log/splunk/metrics.log",
"sourcetype" : "splunkd"
},
{ "group" : "tpool",
"host" : "splunks-ombra.sv.splunk.com",
"name" : "batchreadertpool",
"source" : "/Applications/splunk-ace/var/log/splunk/metrics.log",
"sourcetype" : "splunkd"
}
]
}
json_cols
Results of sample search in json (formatted in columns):
{ "columns" : [ [ "/Applications/splunk-ace/var/log/splunk/metrics.log",
"/Applications/splunk-ace/var/log/splunk/metrics.log",
"/Applications/splunk-ace/var/log/splunk/metrics.log"
],
[ "splunkd",
"splunkd",
"splunkd"
],
[ "splunks-ombra.sv.splunk.com",
"splunks-ombra.sv.splunk.com",
"splunks-ombra.sv.splunk.com"
],
[ "tpool",
"tpool",
"tpool"
],
[ "indexertpool",
"bundlereplthreadpool",
"batchreadertpool"
]
],
"fields" : [ "source",
"sourcetype",
"host",
"group",
"name"
],
"init_offset" : 0,
"messages" : [ { "text" : "base lispy: [ AND index::_internal source::*metrics.log ]",
"type" : "DEBUG"
},
{ "text" : "search context: user=\"admin\", app=\"search\", bs-pathname=\"/Applications/splunk-ace/etc\"",
"type" : "DEBUG"
},
{ "text" : "Your timerange was substituted based on your search string",
"type" : "INFO"
}
],
"preview" : false
}
json_rows
Results of sample search in json (formatted in rows):
{ "rows" : [ [ "/Applications/splunk-ace/var/log/splunk/metrics.log",
"splunkd",
"splunks-ombra.sv.splunk.com",
"tpool",
"indexertpool"
],
[ "/Applications/splunk-ace/var/log/splunk/metrics.log",
"splunkd",
"splunks-ombra.sv.splunk.com",
"tpool",
"bundlereplthreadpool"
],
[ "/Applications/splunk-ace/var/log/splunk/metrics.log",
"splunkd",
"splunks-ombra.sv.splunk.com",
"tpool",
"batchreadertpool"
]
],
"fields" : [ "source",
"sourcetype",
"host",
"group",
"name"
],
"init_offset" : 0,
"messages" : [ { "text" : "base lispy: [ AND index::_internal source::*metrics.log ]",
"type" : "DEBUG"
},
{ "text" : "search context: user=\"admin\", app=\"search\", bs-pathname=\"/Applications/splunk-ace/etc\"",
"type" : "DEBUG"
},
{ "text" : "Your timerange was substituted based on your search string",
"type" : "INFO"
}
],
"preview" : false,
}
raw
raw format returns unparsed raw data as seen by Splunk during indexing. It does not include any additional information about the data, including whether the raw data is a full or partial event.
Results of the sample search in raw format:
10-27-2012 09:04:09.904 -0700 INFO Metrics - group=tpool, name=indexertpool, qsize=0, workers=2, qwork_units=0 10-27-2012 09:04:09.904 -0700 INFO Metrics - group=tpool, name=bundlereplthreadpool, qsize=0, workers=0, qwork_units=0 10-27-2012 09:04:09.904 -0700 INFO Metrics - group=tpool, name=batchreadertpool, qsize=0, workers=1, qwork_units=0
xml
Results of sample search in xml format:
<?xml version='1.0' encoding='UTF-8'?>
<results preview='0'>
<meta>
<fieldOrder>
<field>source</field>
<field>sourcetype</field>
<field>host</field>
<field>group</field>
<field>name</field>
</fieldOrder>
</meta>
<result offset='0'>
<field k='source'>
<value h='1'><text>/Applications/splunk-ace/var/log/splunk/metrics.log</text></value>
</field>
<field k='sourcetype'>
<value><text>splunkd</text></value>
</field>
<field k='host'>
<value><text>splunks-ombra.sv.splunk.com</text></value>
</field>
<field k='group'>
<value h='1'><text>tpool</text></value>
</field>
<field k='name'>
<value h='1'><text>indexertpool</text></value>
</field>
</result>
<result offset='1'>
<field k='source'>
<value h='1'><text>/Applications/splunk-ace/var/log/splunk/metrics.log</text></value>
</field>
<field k='sourcetype'>
<value><text>splunkd</text></value>
</field>
<field k='host'>
<value><text>splunks-ombra.sv.splunk.com</text></value>
</field>
<field k='group'>
<value h='1'><text>tpool</text></value>
</field>
<field k='name'>
<value h='1'><text>bundlereplthreadpool</text></value>
</field>
</result>
<result offset='2'>
<field k='source'>
<value h='1'><text>/Applications/splunk-ace/var/log/splunk/metrics.log</text></value>
</field>
<field k='sourcetype'>
<value><text>splunkd</text></value>
</field>
<field k='host'>
<value><text>splunks-ombra.sv.splunk.com</text></value>
</field>
<field k='group'>
<value h='1'><text>tpool</text></value>
</field>
<field k='name'>
<value h='1'><text>batchreadertpool</text></value>
</field>
</result>
</results>This documentation applies to the following versions of Splunk: 5.0 , 5.0.1 , 5.0.2 , 5.0.3 View the Article History for its revisions.