Splunk® Enterprise

REST API Reference Manual

Download manual as PDF

Splunk Enterprise version 5.0 reached its End of Life on December 1, 2017. Please see the migration information.
This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Download topic as PDF

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:
  • totalResults: Total number of entries that can be returned for this operation.
  • itemsPerPage: The maximum number of entries returned for this operation. itemsPerPage is the value specified by the count parameter in the GET operation. The actual number of entries returned can be less than the maximum specified by itemsPerPage. The default value of the count parameter is 30.
  • startIndex: Offset of the first entry returned. Use the offset parameter in the GET operation to override the default value of 0. The default value of 0 retrieves the first itemsPerPage results from the full result set.

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:
  • system
  • nobody
  • specific user

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:
  • list: GET operation
  • edit: POST operation to modify the resource
  • create: POST operation to create the resource
  • remove: DELETE operation
  • disable / enable: disable or enable the resource
  • move: change location of the resource
  • _reload: refresh the resource
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.
  • optionalFields
  • requiredFields
  • wildcardFields

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/fields
GET search/fields/{field_name}
json, xml
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.
GET search/jobs/{search_id}/events
atom, csv, json, json_cols, json_rows, raw, xml
GET search/jobs/{search_id}/results
atom, csv, json, json_cols, json_rows, raw, xml
GET search/jobs/{search_id}/results_preview
atom, csv, json, json_cols, json_rows, raw, xml
GET search/parser
json, xml
GET search/timeparser
json, xml
GET search/typeahead
csv, json, xml

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>
PREVIOUS
Splunk REST API basics
  NEXT
Accessing Splunk resources

This documentation applies to the following versions of Splunk® Enterprise: 5.0, 5.0.1, 5.0.2, 5.0.3, 5.0.4, 5.0.5, 5.0.6, 5.0.7, 5.0.8, 5.0.9, 5.0.10, 5.0.11, 5.0.12, 5.0.13, 5.0.14, 5.0.15, 5.0.16, 5.0.17, 5.0.18


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