Search endpoints
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
- 200: OK
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
- 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
- defaults to 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
- defaults to 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.
- search_mode: normal | realtime
- defaults to normal
- If set to realtime, search will be run over live data. A realtime search may also be indicated by earliest_time and latest_time variables starting with 'rt' even if the search_mode is set to normal or is unset. For a real-time search, if both earliest_time and latest_time are both exactly 'rt', the search will represent all appropriate live data received since the start of the search. Additionally, if earliest_time and/or latest_time are 'rt' followed by a relative time specifiers then a sliding window is used where the time bounds of the window are determined by the relative time specifier(s) and are continuously updated based on the wall-clock time.
- rt_blocking = true | false
- defaults to false
- For a realtime search, should the indexer block if the queue for this search is full?
- rt_queue_size = integer
- defaults to 10000 (events)
- For a realtime search, the amount of events that the indexer should use for this search.
- rt_maxblocksecs = integer
- defaults to 60; 0 means no limit
- For a realtime search with rt_blocking set to true, the maximum time to block.
- rt_indexfilter = true | false
- defaults to true
- For a realtime search, allow the indexer to prefilter events?
- id
- Optional string to specify the search id.
- status_buckets = integer
- defaults to 0.
- The most status buckets to generate. (0 = do not generate timeline information)
- max_count = int
- Defaults to 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
- Defaults to 0.
- The number of seconds to run this search before finalizing (0 = never).
- timeout = int
- Defaults to 86400
- The number of seconds to keep this search after processing has stopped.
- auto_finalize_ec = integer
- defaults to 0
- Auto-finalize search after at least this many events have been processed (0 = no limit).
- enable_lookups = 0 | 1
- 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 = 0 | 1
- Specifies whether to reload macro definitions from macros.conf.
- Default is 1.
- reduce_freq = integer
- Determines how frequently to run the MapReduce reduce phase on accumulated map values.
- spawn_process = 0 | 1
- 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 canceled 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.
response status
- 200: OK.
- 404: something is very wrong.
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
- 200: OK
- 404: Search job id was not found on this server.
response properties
- 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 = 0 | 1
- Is the search finished?
- isFinalized = 0 | 1
- Was this search finalized (forced to finish)?
- isSaved = 0 | 1
- Is this search to be saved indefinitely?
- keywords = 0 | 1
- All positive (i.e. not in a "NOT" clause) keywords used by this search
- isPaused = 0 | 1
- Is this search paused?
- resultIsStreaming = 0 | 1
- Are the final results of this search available in a streaming manner (e.g. no transforming operations)?
- ttl = 0 or positive int
- 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 = 0 | 1
- Are the events of this search, as defined by eventSearch, available in a streaming manner?
- eventSorting = desc | 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 be the eventSearch + reportSearch
- remoteSearch = search string
- The streaming part of the search that is send to remote providers
- eventIsTruncated = 0 | 1
- 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 = 0 | 1
- Was this search run as a saved search (via scheduler?)
- isZombie = 0 | 1
- 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 = float between 0 and 1.0.
- Approximate progress of the job.
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
- 200: OK
- 404: Search job id was not found on this server.
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.
- 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.
request variables
- offset = integer
- Defaults to 0.
- The first result (inclusive) from which to begin returning data.
- In 4.1+, negative offsets are allowed and are added to 'count' to compute the absolute offset, e.g. offset=-1 is the last available offset. Offsets in the results are always absolute and never negative.
- count = integer
- Defaults to 100.
- The maximum number of results to return.
- earliest_time = 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 = time
- The latest (exclusive), respectively, time bounds for the results to be returned. If not specified, the range applies to all results found.
- search = search
- The post processing search to apply to results. Can be any valid search language string.
- time_format = format
- Defaults to %m/%d/%Y:%H:%M:%S
- Used to convert a formatted time string from {start,end}_time into UTC seconds.
- output_time_format = time_format
- Defaults to time_format.
- Used to format a UTC time.
- field_list = comma-separated list of fields
- Defaults to *.
- A list of the fields to return for the event set.
- max_lines = integer
- Defaults to 0.
- The most lines that any single event's _raw field should contain.
- The value 0 is used to specify no limit.
- search = search
- Display results which contain at least one attribute whose value or name contains the given string.
- truncation_mode = abstract | truncate
- Defaults to abstract.
- Specifies how "max_lines" should be achieved.
- output_mode = csv | raw | xml | json
- Defaults to xml.
- Specifies what format the output should be returned in.
- segmentation = raw | inner | outer
- Defaults to raw.
- The type of segmentation to perform on the data. This will include an option to perform k/v segmentation.
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/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
- offset = integer
- Defaults to 0.
- The first result (inclusive) from which to begin returning data.
- In 4.1+, negative offsets are allowed and are added to 'count' to compute the absolute offset, e.g. offset=-1 is the last available offset. Offsets in the results are always absolute and never negative.
- count = integer
- Defaults to 100.
- The maximum number of results to return.
- If value is set to 0, then all available results are returned.
- show_preview = 0 | 1
- Specifies whether or not to show a preview of the results if the job is not finished yet.
- "1" indicates yes, "0" (default) means no.
- 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 = search
- The post processing search to apply to results.
- Can be any valid search language string.
- field_list = comma-separated list of fields
- Defaults to *.
- A list of the fields to return for the event set.
- output_mode = csv | raw | xml | json
- Defaults to xml.
- Specifies what format the output should be returned in.
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
- action = pause | unpause | finalize | cancel | touch | enablepreview | disablepreview
- 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
- enablepreview: Enable preview generation (may slow search considerably)
- disablepreview: Disable preview generation
- setttl= integer
- Change the time to live of the search.
- setpriority = 0 - 10
- Sets the priority of the search.
response status
- 200: Action was executed successfully
- 403: Not authorized to execute action
- 403: Search id was not found on server
Parser
Located at /services/search/parser. Provides search language parsing services.
GET
Parses splunk search language and returns semantic map
request variables
- q = search
- The search string to parse
- enable_lookups = 1 | 0
- Defaults to 0.
- Specifies whether reverse lookups should be done to expand the search expression.
- reload_macros = 1 | 0
- Defaults to 1.
- Specifies whether to reload macro definitions from macros.conf.
- parse_only = 1 | 0
- Defaults to 0.
- If set to true (1), this disables expansion of search due evaluation of subsearches, time term expansion, lookups, tags, eventtypes, sourcetype alias.
- output_mode = xml | json
- Defaults to XML.
- The output formatting.
response status
- 200: OK
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.