This documentation applies to the following versions of Splunk: 4.0 , 4.0.1 , 4.0.2 , 4.0.3 , 4.0.4 , 4.0.5 , 4.0.6
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.
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.
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.
200 OK
<?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>
Starts a new search job on Splunk server.
search
This is the search language string that will be executed taking results from the local and remote servers.
remote_server_list
(comma separated list) (default: empty) This is the list of (possibly wildcarded) servers from which raw events should be pulled. This same server list is to be used in subsearches.
earliest_time
The earliest (inclusive), respectively, time bounds for the search. The time string can be either a UTC time (with fractional seconds), a relative time specifier (to now) or a formatted time string.
latest_time
The latest (exclusive), respectively, time bounds for the search. The time string can be either a UTC time (with fractional seconds), a relative time specifier (to now) or a formatted time string.
now
The absolute time used for any relative time specifier in the search. Defaults to the current system time.
time_format
Used to convert a formatted time string from {start,end}_time into UTC seconds. It defaults to ISO-8601.
exec_mode
{blocking|oneshot|normal} (default: normal) If set to normal, runs an asynchronous search. If set to blocking, returns the sid when the job is complete. If set to oneshot, returns results in the same call.
id
Optional string to specify the search id.
status_buckets
[int] (default: 300) The most status buckets to generate.
max_count
[int] (default: 10000) The number of events that can be 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.
max_time
[int] (default: 0) The number of seconds to run this search before finalizing (0 = never).
timeout
int (default: 86400) The number of seconds to keep this search after processing has stopped.
enable_lookups
{1|0} Specifies whether lookups should be applied to events. This option may slow searches significantly depending how the nature of the lookups. Default is 1.
reload_macros
{1|0} Specifies whether to reload macro definitions from macros.conf. Default is 1.
reduce_freq
[int] Determines how frequently to run the MapReduce reduce phase on accumulated map values.
spawn_process
{1|0} Specifies whether the search should run in a separate spawned process. Default is 1.
required_field_list
(comma separated list) (default: empty) This is the list of required fields that, even if not referenced or used directly by the search, will still be included by the events and summary endpoints.
auto_cancel
[int] If set, the job will be automatically cancelled after this many seconds of inactivity.
auto_pause
[int] If set, the job will be automatically paused after this many seconds of inactivity.
namespace
The application namespace in which to restrict searches. The namespace corresponds to the identifier recognized in the /services/apps/local endpoint. Optional.
200
OK
404
something is very wrong
Use this endpoint, located at /services/search/jobs/search_id, to access a specific search in the system.
Returns summary information about the search job.
200
OK
404
Search job id was not found on this server
sid
String: Unique search identifier
request
Dict: Dictionary of request parameters used to invoke this job
eventCount
Non-negative integer: Count of events (pre-transforming) generated by search
scanCount
Non-negative integer: Count of events scanned to satisfy search
eventAvailableCount
Non-negative integer: Count of events stored by search available to be retrieved from the events endpoint
resultCount
Non-negative integer: Count of final result rows
cursorTime
Time String: The earliest time from which we are sure no events later than this time will be scanned later. (Use as progress indicator)
isDone
Boolean 1/0: Is the search finished?
isFinalized
Boolean 1/0: Was this search finalized (forced to finish)?
isSaved
Boolean 1/0: Is this search to be saved indefinitely?
keywords
Boolean 1/0: All positive (i.e. not in a "NOT" clause) keywords used by this search
isPaused
Boolean 1/0: Is this search paused?
resultIsStreaming
Boolean 1/0: Are the final results of this search available in a streaming manner (e.g. no transforming operations)?
ttl
Minimum number of secs from now that this job will still be available. If expired, this property has value "0". Otherwise, it is a non-negative integer
error
String: A fatal search parsing or execution error message
earliestTime
Time String: The lower time bound for this search (inclusive)
latestTime
Time String: The upper time bound for this search (exclusive)
runDuration
Float: How long this search has been running
eventSearch
Search String: Subset of the entire search that is before any transforming commands. The timeline and events endpoint represents the result of this part of the search.
eventIsStreaming
Boolean 1/0: Are the events of this search, as defined by eventSearch, available in a streaming manner?
eventSorting
"desc" or "none": Are the events of this search sorted in inverse time order (latest first)?
reportSearch
Search String: The reporting subset of this search. The original search should = eventSearch + reportSearch
remoteSearch
Search String: The streaming part of the search that is send to remote providers
eventIsTruncated
Boolean 1/0: Have any events of the search *not* been stored, i.e. not available via the events endpoint
label
String: custom user specified label for this search
isSavedSearch
Boolean 1/0: Was this search run as a saved search (via scheduler?)
isZombie
Boolean 1/0: Is the process running this search dead, but with the search not finished?
searchProviders
CSV String List: Remote search providers that we are retrieving events from
statusBuckets
Non-negative integer: Maximum number of timeline buckets
doneProgress
Percentage: Approximate progress of the job
<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">100.00%</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>
Deletes the specified search job.
200
OK
404
Search job id was not found on this server
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.
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.
* In general, readlevel::0 is meaningless since raw events must be fetched off disk for many classes of search. We may provide an option to the search command that selects readlevel::0, but only if the search does not require raw event retrieval. If the search requires raw events but readlevel::0 is specified, an exception will be thrown. * There is no "autolimit" argument. The client is guaranteed that no more than end-start results are returned. * Personally I hate the time_format argments.
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
earliest_time
The earliest (inclusive), respectively, time bounds for the results to be returned. If not specified, the range applies to all results found.
latest_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
output_time_format
Used to format a UTC time. Defaults to time_format
field_list
[comma separated list] (default: *) A list of the fields to return for the event set.
max_lines
(default: 0) The most lines that any single event's _raw field should contain. The value 0 is used to specify no limit.
search
display results which contain at least one attribute whose value or name contains the given string
truncation_mode
{abstract,truncate} (default: abstract) Specifies how "max_lines" should be achieved.
output_mode
{csv,raw,xml,json} (default: xml) Specifies what format the output should be returned in.
segmentation
(default: raw) The type of segmentation to perform on the data. This will include an option to perform k/v segmentation.
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
// 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"
}
]
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.
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_preview
Specifies whether or not to show a preview of the results if the job is not finished yet. "1" indicates yes, "0" (default) means. This will only return results if preview generation is enabled via job control. If preview results are returned in xml format, a preview='1' attribute is set in the <results> node.
search
The post processing search to apply to results. Can be any valid search language string.
field_list
[comma separated list] (default: *) A list of the fields to return for the event set.
output_mode
{csv,raw,xml,json} (default: xml) Specifies what format the output should be returned in.
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
// 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"
}
]
/services/search/jobs/search_id/control Provides job control handle for current search
Executes a job control command
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
touch
Extends the expiration time of the search to now + ttl
ttl
Change the ttl of the search. Arguments: ttl=<number>
priority
Sets the priority of the search process. Arguments: priority=<0-10>
enablepreview
Enable preview generation (may slow search considerably)
disablepreview
Disable preview generation
200
Action was executed successfully
403
Not authorized to execute action
404
Search id was not found on server