Search Endpoint

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

Jobs
POST
GET
Search ID
GET
DELETE
Events
GET
Results
GET
Timeline
GET
Summary
GET
Control
POST

Search Endpoint

Use the services/search/jobs/ endpoint to interact with Splunk's REST search interface. Any search dispatched through the search endpoint receives a $SEARCH_ID you can use as reference.

Jobs

Use the services/search/jobs endpoint to access Splunk's REST search endpoint. Create a new search job with POST. List current search jobs with GET.

POST

Starts a new search job on the Splunk server.

Pass along any of the following variables with your request to constrain your search job.

Form	Variables
search	The search language string executed on local and remote servers.
remote_server_list	Comma separated list of remote servers to search (can include wildcards). This same server list is used in subsearches.
start_time	The earliest (inclusive) time limit for the search. The time string can be in UTC (with fractional seconds), a relative time specifier (to now) or a formatted time string.
end_time	The latest (exclusive) time limit for the search. The time string can be in UTC (with fractional seconds), a relative time specifier (to now) or a formatted time string.
time_format	Used to convert a formatted time string from {start,end}_time into UTC seconds. Defaults to ISO-8601.
status_buckets	Integer. The most status buckets to generate. Defaults to 300.
max_count	The number of events accessible in any given status bucket. Also, in transforming mode, the maximum number of results to store. Specifically, in all calls, offset+count <= max_count. Defaults to 10000.
timeout	Integer. The number of seconds to keep this search after processing has stopped. Defaults to 86400 (or 24 hours).
enable_eventtypes	{1\|0} Specfies whether eventtypes should be assigned to events. This may slow searches and should be used with discretion. Defaults to 0.

Response

If your job is executed successfully, Splunk returns a job ID, which you can use to access the search.

Response	Status
201	OK
404	something is very wrong

Example

Simple curl example with the search for "syslog." The response is a job id that can be used the $SEARCH_ID (see below).

curl -k -H "$SPLUNK_AUTH_HEADER" -X POST -d "search=search syslog" "$SPLUNK_URL/search/jobs"
<?xml version='1.0'?>
<response><sid>1213402282.1</sid></response>

GET

Returns a list of current searches associated with the user ID authenticating the search.

Response

Response	Status
200	Method executed successfully.

Example

curl -k -H "$SPLUNK_AUTH_HEADER" "$SPLUNK_URL/search/jobs/"
<?xml version="1.0" encoding="UTF-8"?>
<!--This is to override browser formatting; see server.conf[httpServer] to disable
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .-->
<?xml-stylesheet type="text/xml" href="/static/atom.xsl"?>
<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-06-13T17:18:15-0700</updated>
  <generator version="37999"/>
  <author>
    <name>Splunk</name>
  </author>
  <entry>
    <title>search syslog</title>
    <id>https://localhost:8089/services/search/jobs/1213402282.1</id>
    <updated>2008-06-13T17:11:23.000-07:00</updated>
    <link href="https://localhost:8089/services/search/jobs/1213402282.1" rel="alternate"/>
    <published>2008-06-13T17:11:22.000-07:00</published>
    <link href="https://localhost:8089/services/search/jobs/1213402282.1/events" rel="events"/>
    <link href="https://localhost:8089/services/search/jobs/1213402282.1/results" rel="results"/>
    <link href="https://localhost:8089/services/search/jobs/1213402282.1/timeline" rel="timeline"/>
    <link href="https://localhost:8089/services/search/jobs/1213402282.1/summary" rel="summary"/>
    <link href="https://localhost:8089/services/search/jobs/1213402282.1/control" rel="control"/>
    <author>
      <name>admin</name>
    </author>
    <content type="text/xml">
      <s:dict>
        <s:key name="cursorTime">2008-05-22T14:46:31.000-07:00</s:key>
        <s:key name="error"></s:key>
        <s:key name="eventCount">1</s:key>
        <s:key name="isDone">1</s:key>
        <s:key name="isFinalized">0</s:key>
        <s:key name="isPaused">0</s:key>
        <s:key name="isStreaming">1</s:key>
        <s:key name="keywords">syslog</s:key>
        <s:key name="resultCount">1</s:key>
        <s:key name="sid">1213402282.1</s:key>
        <s:key name="ttl">23.89 hours</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

Search ID

Use the services/search/jobs/$SEARCH_ID endpoint to access a specific search you've already dispatched. Replace $SEARCH_ID with the ID of an active search in the search system. $SEARCH_ID is returned anytime you launch a job via the search/jobs endpoint.

GET

Returns summary information about the search job.

Response

Response	Status
200	OK
404	Search job id was not found on this server.

Example

curl -k -H "$SPLUNK_AUTH_HEADER" "$SPLUNK_URL/search/jobs/1213402282.1"
<?xml version="1.0" encoding="UTF-8"?>
<!--This is to override browser formatting; see server.conf[httpServer] to disable
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .-->
<?xml-stylesheet type="text/xml" href="/static/atom.xsl"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest">
  <title>search syslog</title>
  <id>https://localhost:8089/services/search/jobs/1213402282.1</id>
  <updated>2008-06-13T17:11:23.000-07:00</updated>
  <link href="https://localhost:8089/services/search/jobs/1213402282.1" rel="alternate"/>
  <published>2008-06-13T17:11:22.000-07:00</published>
  <link href="https://localhost:8089/services/search/jobs/1213402282.1/events" rel="events"/>
  <link href="https://localhost:8089/services/search/jobs/1213402282.1/results" rel="results"/>
  <link href="https://localhost:8089/services/search/jobs/1213402282.1/timeline" rel="timeline"/>
  <link href="https://localhost:8089/services/search/jobs/1213402282.1/summary" rel="summary"/>
  <link href="https://localhost:8089/services/search/jobs/1213402282.1/control" rel="control"/>
  <author>
    <name>admin</name>
  </author>
  <content type="text/xml">
    <s:dict>
      <s:key name="cursorTime">2008-05-22T14:46:31.000-07:00</s:key>
      <s:key name="error"></s:key>
      <s:key name="eventCount">1</s:key>
      <s:key name="isDone">1</s:key>
      <s:key name="isFinalized">0</s:key>
      <s:key name="isPaused">0</s:key>
      <s:key name="isStreaming">1</s:key>
      <s:key name="keywords">syslog</s:key>
      <s:key name="resultCount">1</s:key>
      <s:key name="sid">1213402282.1</s:key>
      <s:key name="ttl">23.97 hours</s:key>
    </s:dict>
  </content>
</entry>

DELETE

Deletes the specified search job.

Response

Response	Status
200	OK
404	Search job id was not found on this server.

Events

The endpoint /services/search/jobs/$SEARCH_ID/events references the raw events returned by the current search.

GET

This is the primary method for a client to fetch a set of untransformed [EXPLAIN TRANSFORM VS 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	Query
offset	The first result (inclusive) from which to begin returning data. This value is 0-indexed. Default value is 0.
count	The maximum number of results to return. If value is set to 0, then all available results are returned. Default value is 100.
start_time	The earliest (inclusive), respectively, time bounds for the results to be returned. If not specified, the range applies to all results found.
end_time	The latest (exclusive), respectively, time bounds for the results to be returned. If not specified, the range applies to all results found.
search	The post processing search to apply to results. Can be any valid search language string.
time_format	Used to convert a formatted time string from {start,end}_time into UTC seconds. It defaults to %m/%d/%Y:%H:%M:%S.
field_list	[comma separated list] A list of the fields to return for the event set. Defaults to *.
output_mode	{csv,raw,xml,json} Specifies what format the output should be returned in. Defaults to xml.
segmentation	The type of segmentation to perform on the data. This includes an option to perform k/v segmentation. Defaults to raw.

Response

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.

Sample JSON output to 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

The /services/search/jobs/$SEARCH_ID/results endpoint 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 with fewer options.

GET

Request	Query
offset	The first result (inclusive) from which to begin returning data. This value is 0-indexed. Default value is 0.
count	The maximum number of results to return. If value is set to 0, then all available results are returned. Default value is 100.
show_incomplete	{1\|0} Toggle whether or not to generate a preview of the results if the final results are not ready. Set to 1 to generate preview. Defaults to 0. Generating incomplete results are a potentially expensive operation.
timeout	This option specifies the maximum amount of time in seconds to wait for incomplete results. This option is only valid if show_incomplete=1. Default value is 30.
search	The post processing search to apply to results. Can be any valid search language string.
field_list	A comma separated list of the fields to return for the event set. Defaults to *.
output_mode	{csv,raw,xml,json} Specifies what format the output should be returned in. Defaults to XML.

Response

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.

Sample JSON output to

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"
	}
	]

Timeline

The /services/search/jobs/$SEARCH_ID/timeline endpoint provides "timeline" output of the so-far-read untransformed events.

GET

Returns the timeline data

Request	Query
time_format	Used to convert a formatted time string from {start,end}_time into UTC seconds. It defaults to %m/%d/%Y:%H:%M:%S

Response

Response	Status
200	OK.
204	Search id was found, but the server has not finished preparing the events yet; retry your request.
404	Search id was not found on server.

<?xml version="1.0"?>
<timeline c="478586" cursor="1143878400">
	<bucket c="2" t="1143878400.000" d="2588400" f="1">2006-04-01T00:00:00.000-08:00</bucket>
	<bucket c="0" t="1146466800.000" d="2678400" f="1">2006-05-01T00:00:00.000-07:00</bucket>
	<bucket c="0" t="1149145200.000" d="2592000" f="1">2006-06-01T00:00:00.000-07:00</bucket>
	...
	<bucket c="37620" t="1191222000.000" d="2678400" f="1">2007-10-01T00:00:00.000-07:00</bucket>
	<bucket c="108760" t="1193900400.000" d="2595600" f="1">2007-11-01T00:00:00.000-07:00</bucket>
	<bucket c="102507" t="1196496000.000" d="2678400" f="1">2007-12-01T00:00:00.000-08:00</bucket>
	<bucket c="67179" t="1199174400.000" d="2678400" f="1">2008-01-01T00:00:00.000-08:00</bucket>
</timeline>

Summary

The /services/search/jobs/$SEARCH_ID/summary endpoints provides "getFieldsAndStats" output of the so-far-read untransformed events.

GET

Returns the summary output.

Request	Query
start_time	The earliest (inclusive), respectively, time bounds for the results to be returned. If not specified, the range applies to all results found.
end_time	The latest (exclusive), respectively, time bounds for the results to be returned. If not specified, the range applies to all results found.
time_format	Used to convert a formatted time string from {start,end}_time into UTC seconds. It defaults to %m/%d/%Y:%H:%M:%S.
field_list	A comma separated list of the fields to return for the event set. Defaults to *.
top_count	For each key, this number of the most frequent items will be returned. Defaults to 10.

Response

Response	Status
200	Action was executed successfully
403	Not authorized to execute action
404	Search id was not found on server

Control

The /services/search/jobs/$SEARCH_ID/control endpoint provides job control handle for current search.

POST

Execute a job control command.

Request	Form
action	The control action to execute
pause	Suspends the execution of the current search
unpause	Resumes the execution of the current search, if paused
finalize	Stops the search, and provides intermediate results to the /results endpoint
cancel	Stops the current search and deletes the result cache

Response

Response	Status
200	Action was executed successfully
403	Not authorized to execute action
404	Search id was not found on server

Retrieved from "http://docs.splunk.com/Documentation/Splunk/3.4.1/Developer/SearchEndpoint"

« Search Overview Search with the Python SDK »

This documentation applies to the following versions of Splunk: 3.3 , 3.3.1 , 3.3.2 , 3.3.3 , 3.3.4 , 3.4 , 3.4.1 , 3.4.2 , 3.4.3 , 3.4.5 , 3.4.6 , 3.4.8 , 3.4.9 , 3.4.10 , 3.4.11 , 3.4.12 , 3.4.13 , 3.4.14 View the Article History for its revisions.

Was this topic useful?
Post a comment

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.

Developing Dashboards, Views, and Apps for Splunk Web

Search Endpoint

Contents

Search Endpoint

Jobs

POST

Response

Example

GET

Response

Example

Search ID

GET

Response

Example

DELETE

Response

Events

GET

Response

Results

GET

Response

Timeline

GET

Response

Summary

GET

Response

Control

POST

Response

Comments