Developing Dashboards, Views, and Apps for Splunk Web

 


Search endpoints

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

Search endpoints

Many calls to Splunk's API involve running some type of search. For example, you may wish to run a search within Splunk and post the results in a third party application. Use the search endpoints located at ../services/search/<endpoint>.

To run new searches, use the ../search/jobs/ endpoint. When you run a search, Splunk launches a search process asynchronously. This means that you must pull the jobs or events endpoint to see if your search has finished.

Jobs

To run searches, use the ../jobs endpoint located at /services/search/jobs. Once you create a job, you'll get a search ID which will let you retrieve the job later. The jobs endpoint support GET, to return a list of running jobs, and POST, to create a new job.

GET

Returns a list of current searches. Optional filter arguments can be passed to specify searches. The user id is implied by the authentication to the call. See the response properties for /search/jobs/<job_id> for descriptions of the job properties.

response status

response body

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest">
	<title>jobs</title>
	<id>https://localhost:8089/services/search/jobs</id>
	<updated>2008-01-11T14:02:00-0800</updated>
	<generator version="30887"/>
	<author>
		<name>Splunk</name>
	</author>
	<entry>
		<title>search *</title>
		<id>https://localhost:8089/services/search/jobs/1014004140</id>
		<published>2008-01-11T14:02:00-0800</published>
		<updated>2008-01-11T14:02:00-0800</updated>
		<link href="https://localhost:8089/services/search/jobs/1014004140" rel="alternate"/>
		<link href="https://localhost:8089/services/search/jobs/1014004140/events" rel="events"/>
		<link href="https://localhost:8089/services/search/jobs/1014004140/results" rel="results"/>
		<link href="https://localhost:8089/services/search/jobs/1014004140/timeline" rel="timeline"/>
		<link href="https://localhost:8089/services/search/jobs/1014004140/summary" rel="summary"/>
		<link href="https://localhost:8089/services/search/jobs/1014004140/control" rel="control"/>
		<s:messages>
			<s:msg type="ERROR">my error text</s:msg>
			<s:msg type="WARN">my error text</s:msg>
		</s:messages>
		<author>
			<name>admin</name>
		</author>
		<content type="text/xml">
			<s:dict>
				<s:key name="sid">1014004140</s:key>
				<s:key name="eventCount">1234</s:key>
				<s:key name="cursorTime">2008-01-11T19:24:00-0800</s:key>
				<s:key name="isDone">0</s:key>
				<s:key name="isFinalized">1</s:key>
				<s:key name="keywords">none</s:key>
				<s:key name="isPaused">0</s:key>
				<s:key name="isStreaming">0</s:key>
				<s:key name="ttl">600</s:key>
			</s:dict>
		</content>
	</entry>
</feed>

POST

Starts a new search job on Splunk server.

form variables

response status

Search ID

Use this endpoint, located at /services/search/jobs/search_id, to access a specific search in the system.

GET

Returns summary information about the search job.

response status

response properties

response body

<feed xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest">
  <title>jobs</title>
  <id>https://localhost:8089/services/search/jobs</id>
  <updated>2009-01-22T11:28:55-0800</updated>
  <generator version="49165"/>
  <author>

    <name>Splunk</name>
  </author>
  <entry>
    <title>search *</title>
    <id>https://localhost:8089/services/search/jobs/1232652525.1</id>
    <updated>2009-01-22T11:28:52.000-08:00</updated>
    <link href="https://localhost:8089/services/search/jobs/1232652525.1" rel="alternate"/>

    <published>2009-01-22T11:28:45.000-08:00</published>
    <link href="https://localhost:8089/services/search/jobs/1232652525.1/events" rel="events"/>
    <link href="https://localhost:8089/services/search/jobs/1232652525.1/results" rel="results"/>
    <link href="https://localhost:8089/services/search/jobs/1232652525.1/timeline" rel="timeline"/>
    <link href="https://localhost:8089/services/search/jobs/1232652525.1/summary" rel="summary"/>
    <link href="https://localhost:8089/services/search/jobs/1232652525.1/control" rel="control"/>
    <author>
      <name>admin</name>

    </author>
    <content type="text/xml">
      <s:dict>
        <s:key name="cursorTime">2009-01-01T00:00:00.000-08:00</s:key>
        <s:key name="doneProgress">1.0</s:key>
        <s:key name="earliestTime">2009-01-01T00:00:00.000-08:00</s:key>
        <s:key name="error"></s:key>
        <s:key name="eventAvailableCount">10000</s:key>
        <s:key name="eventCount">44864</s:key>
        <s:key name="eventIsStreaming">1</s:key>
        <s:key name="eventIsTruncated">0</s:key>
        <s:key name="eventSearch">search index=default readlevel=2 *</s:key>
        <s:key name="eventSorting">desc</s:key>

        <!-- Indicates when the search job is completed.  [0 | 1] -->
        <s:key name="isDone">1</s:key>

        <!-- Indicates if a request to finalize the running search has been received.
        Once finalization has been completed, isDone will be 1.  Finalizing a completed
        job has no effect.  [0 | 1] -->
        <s:key name="isFinalized">0</s:key>

        <!-- Indicates if the search job has been paused. [0 | 1] -->
        <s:key name="isPaused">0</s:key>
        <s:key name="isSaved">0</s:key>

        <!-- Indicates if the search job is an artifact of a saved search. [0 | 1] -->
        <s:key name="isSavedSearch">0</s:key>
        <s:key name="isZombie">0</s:key>
        <s:key name="keywords"></s:key>
        <s:key name="label"></s:key>
        <s:key name="latestTime">2009-02-01T00:00:00.000-08:00</s:key>
        <s:key name="remoteSearch">litsearch index=default readlevel=2 * | fields keepcolorder=t *</s:key>
        <s:key name="reportSearch"></s:key>
        <s:key name="resultCount">10000</s:key>
        <s:key name="resultIsStreaming">1</s:key>

        <!-- The elapsed execution time of the search job, in seconds. --> 
        <s:key name="runDuration">7.103000</s:key>
        <s:key name="scanCount">44864</s:key>
        <s:key name="searchProviders">$HOSTNAME-johnvey</s:key>

        <!-- The unique ID of the search job -->
        <s:key name="sid">1232652525.1</s:key>
        <s:key name="statusBuckets">300</s:key>
        <s:key name="ttl">597</s:key>
        <s:key name="delegate"></s:key>

        <!-- The raw parameters passed in to the search dispatcher at request time -->
        <s:key name="request">
          <s:dict>
            <s:key name="UI_dispatching_app">search</s:key>
            <s:key name="UI_dispatching_view">/app/search/flashtimeline</s:key>
            <s:key name="earliest_time">@mon</s:key>
            <s:key name="latest_time">+1mon@mon</s:key>
            <s:key name="required_field_list">*</s:key>
            <s:key name="search">search *</s:key>
            <s:key name="status_buckets">300</s:key>
            <s:key name="time_format">%m/%d/%Y:%H:%M:%S.%Q</s:key>
          </s:dict>
        </s:key>
      </s:dict>

    </content>
  </entry>
</feed>

DELETE

Deletes the specified search job.

response status

Events

If you want to get a digest of the raw events from a specific search, use the endpoint located at /services/search/jobs/search_id/events.

GET

This is the primary method for a client to fetch a set of UNTRANSFORMED events. If the dispatched search includes a transforming command, the events here are those that would be transformed, not the final transformed results.

request variables

response status

response body

// sample JSON output
// https://localhost:8089/services/search/jobs/1234/events?output_mode=json

[
	{
		"_cd": "0:4374557",
		"_index": "main",
		"_kv": "1",
		"_meta": " date_second::36 date_hour::19 date_minute::11 date_year::2008 date_month::january date_mday::21 date_wday::monday date_zone::-480 punct::_[//:::_-]____\\\"@...\\\"...",
		"_raw": "I [21/Jan/2008:19:11:36 -0800] Added remote printer \"HPLaserJ@10.1.1.123\"...",
		"_serial": "0",
		"_time": "1200971496",
		"date_hour": "19",
		"date_mday": "21",
		"date_minute": "11",
		"date_month": "january",
		"date_second": "36",
		"date_wday": "monday",
		"date_year": "2008",
		"date_zone": "-480",
		"host": "decider.local",
		"linecount": "1",
		"punct": "_[//:::_-]____\"@...\"...",
		"source": "/var/log/cups/error_log",
		"sourcetype": "cups_error"
	},
	{
		"_cd": "0:4374549",
		"_index": "main",
		"_kv": "1",
		"_meta": " date_second::36 date_hour::19 date_minute::11 date_year::2008 date_month::january date_mday::21 date_wday::monday date_zone::-480 punct::_[//:::_-]____\\\"@...\\\"...",
		"_raw": "I [21/Jan/2008:19:11:36 -0800] Added remote printer \"HPLaserJ@10.1.5.65\"...",
		"_serial": "1",
		"_time": "1200971496",
		"date_hour": "19",
		"date_mday": "21",
		"date_minute": "11",
		"date_month": "january",
		"date_second": "36",
		"date_wday": "monday",
		"date_year": "2008",
		"date_zone": "-480",
		"host": "decider.local",
		"linecount": "1",
		"punct": "_[//:::_-]____\"@...\"...",
		"source": "/var/log/cups/error_log",
		"sourcetype": "cups_error"
	}
]

Results

If you've run a search that has transformed events (for example, anything with statistics), use the endpoint at /services/search/jobs/search_id/results.

This is the primary method for a client to fetch a set of TRANSFORMED events. If the dispatched search does not include a transforming command, the effect is the same as get_events, albeit with fewer options.

GET

request variables

response status

200

   Search events returned

204

   Search job was found, but the server has not finished preparing the events yet; retry your request.

404

   Search job id was not found on this server

response body

	// sample JSON output
	// https://localhost:8089/services/search/jobs/1234/results?output_mode=json

	[
	{
	"_cd": "0:4374557",
	"_index": "main",
	"_kv": "1",
	"_meta": " date_second::36 date_hour::19 date_minute::11 date_year::2008 date_month::january date_mday::21 date_wday::monday date_zone::-480 punct::_[//:::_-]____\\\"@...\\\"...",
	"_raw": "I [21/Jan/2008:19:11:36 -0800] Added remote printer \"HPLaserJ@10.1.1.123\"...",
	"_serial": "0",
	"_time": "1200971496",
	"date_hour": "19",
	"date_mday": "21",
	"date_minute": "11",
	"date_month": "january",
	"date_second": "36",
	"date_wday": "monday",
	"date_year": "2008",
	"date_zone": "-480",
	"host": "decider.local",
	"linecount": "1",
	"punct": "_[//:::_-]____\"@...\"...",
	"source": "/var/log/cups/error_log",
	"sourcetype": "cups_error"
	},
	{
	"_cd": "0:4374549",
	"_index": "main",
	"_kv": "1",
	"_meta": " date_second::36 date_hour::19 date_minute::11 date_year::2008 date_month::january date_mday::21 date_wday::monday date_zone::-480 punct::_[//:::_-]____\\\"@...\\\"...",
	"_raw": "I [21/Jan/2008:19:11:36 -0800] Added remote printer \"HPLaserJ@10.1.5.65\"...",
	"_serial": "1",
	"_time": "1200971496",
	"date_hour": "19",
	"date_mday": "21",
	"date_minute": "11",
	"date_month": "january",
	"date_second": "36",
	"date_wday": "monday",
	"date_year": "2008",
	"date_zone": "-480",
	"host": "decider.local",
	"linecount": "1",
	"punct": "_[//:::_-]____\"@...\"...",
	"source": "/var/log/cups/error_log",
	"sourcetype": "cups_error"
	}
	]

Control

The endpoint at /services/search/jobs/search_id/control. Provides job control handle for current search: start, stop, pause, etc.

POST

Executes a job control command

request variables

response status

Parser

Located at /services/search/parser. Provides search language parsing services.

GET

Parses splunk search language and returns semantic map

request variables

response status

response body

Response to a sample request: /services/search/parser?q=search foo | timechart avg(bar)

XML format

<response>
	<dict>
		<key name="remoteSearch">search index=default readlevel=2 foo</key>
		<key name="remoteTimeOrdered">true</key>
		<key name="eventsSearch">search index=default readlevel=2 foo</key>
		<key name="eventsTimeOrdered">true</key>
		<key name="eventsStreaming">true</key>

		<key name="reportsSearch">timechart avg(bar)</key>
	</dict>
	<list>
		<item>
			<dict>
				<key name="command">search</key>
				<key name="rawargs">foo</key>
				<key name="args">index=default readlevel=2 foo</key>

				<key name="isGenerating">true</key>
				<key name="isTransforming">false</key>
				<key name="isStreaming">true</key>
				<key name="retainsEvents">true</key>
				<key name="overridesTimeOrder">false</key>
				<key name="isStreamingOpRequired">false</key>

			</dict>
		</item>		
		<item>
			<dict>
				<key name="command">timechart</key>
				<key name="rawargs">avg(bar)</key>
				<key name="args">avg(bar)</key>
				<key name="isGenerating">false</key>
				<key name="isTransforming">false</key>

				<key name="isStreaming">false</key>
				<key name="isStatefulStreaming">false</key>
				<key name="retainsEvents">false</key>
				<key name="overridesTimeOrder">true</key>
				<key name="isStreamingOpRequired">false</key>
			</dict>

		</item>	
	</list>
</response>

JSON format

{
	"remoteSearch": "search index=default readlevel=2 foo",
	"remoteTimeOrdered": true,
	"eventsSearch": "search index=default readlevel=2 foo",
	"eventsTimeOrdered": true,
	"eventsStreaming": true,
	"reportsSearch": "timechart avg(bar)",
	"commands": [
		{
			"command": "search",
                        "rawargs": "foo",
			"args": "index=default readlevel=2 foo",
			"isGenerating": true,
			"isTransforming": false,
			"isStreaming": true,
			"retainsEvents": true,
			"overridesTimeOrder": false,
			"isStreamingOpRequired": false,
		},
		{
			"command": "timechart",
			"rawargs": "avg(bar)",
			"args": "avg(bar)",
			"isGenerating": false,
			"isTransforming": false,
			"isStreaming": false,
			"isStatefulStreaming": false,
			"retainsEvents": false,
			"overridesTimeOrder": true,
			"isStreamingOpRequired": false,
		},
	]
}

This documentation applies to the following versions of Splunk: 4.2 , 4.2.1 , 4.2.2 , 4.2.3 , 4.2.4 , 4.3 View the Article History for its revisions.


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

Was this documentation topic helpful?

If you'd like to hear back from us, please provide your email address:

We'd love to hear what you think about this topic or the documentation as a whole. Feedback you enter here will be delivered to the documentation team.

Feedback submitted, thanks!