Splunk® Enterprise

REST API Tutorials

Download manual as PDF

Download topic as PDF

Creating searches using the REST API

Use the search/jobs endpoint to create a search job in a Splunk deployment. However, before creating searches you should be aware of how searches work and how to structure a search so you can easily access the results.

Learn about searches

You can learn about searches and how to write them in the Search Manual.

Here are some highlights from the Search Reference that can help you get started creating searches:

Additional information about working with searches is in the Search Manual:

REST endpoints for searches

Here is a brief description of some of the key endpoints for creating and accessing searches.

/search/jobs
Create searches or access the results of search jobs. Returns a search ID (sid) that you use when accessing the results of a search.

/search/jobs/export
Stream search results as they become available. Does not create a search ID for later access.

/search/jobs/{search_id}/control
Execute a job control command for a search, such as pause, setpriority, or finalize.

/search/jobs/{search_id}/events
Return untransformed events of a search.

/search/jobs/{search_id}/results
Return transformed events of a search.

/search/jobs/{search_id}/summary
Return summary information for fields of a search.

/search/jobs/{search_id}/timeline
Return event distribution over time of the so-far-read untransformed events.

/saved/searches
Create or access the configuration of saved searches.

Tips on creating searches

When creating a search (POST /search/jobs), consider the following properties of the search:

max_count
Set this parameter for searches returning more than the default maximum of 10000 events. Otherwise you may not be able to retrieve results in excess of the default.

status_buckets
To access summary and timeline information from a search job, specify a value for status_buckets. The default value is zero. For example, searches spawned from the Splunk timeline specify status_buckets=300.

rf
Use the rf parameter to add required fields to a search. Adding fields guarantees results for the endpoints that return events and a summary. (The required_fields parameter has been deprecated in favor of the rf parameter.)

Tips on accessing searches

When accessing the results of a search (GET /search/jobs/{search_id}), consider the following:

search, offset, and count parameters
Use these parameters to a GET operation to filter or limit the results returned.

dispatchState
dispatchState is one of the properties returned when accessing a search. It provides the state of a search, which can be any of the following:

QUEUED
PARSING
RUNNING
PAUSED
FINALIZING
FAILED
DONE

search job properties
The GET operation for /search/jobs returns all the properties of a search. These properties are described in the parameters to the POST operation. Search job properties are also described in View search job properties in the Search Manual.

performance
The GET operation for /search/jobs returns information that helps you troubleshoot the efficiency of a search. See the "Execution costs" section in View search job properties in the Search Manual.

Example: Create a search

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

When you run a search, the search process launches asynchronously. You can poll the jobs or events endpoint to see if your search has finished.

Create a search job

Create a search job using the POST operation at search/jobs/. Set your search as the POST payload. For example:

curl -u admin:changeme -k https://localhost:8089/services/search/jobs -d search="search *"

This simple example runs the search for *. It returns an XML response such as:

<?xml version='1.0' encoding='UTF-8'?>
<response>
  <sid>1258421375.19</sid>
</response>

You need the search ID to retrieve the search, which is returned within the <sid> tags. In the example above this is 1258421375.19.

Check status of a search

Check the status of a search job by accessing the GET operation of search/jobs/. If you know the search's ID, you can access search/jobs/{search_id} to get information about that search only:

curl -u admin:changeme -k https://localhost:8089/services/search/jobs/1258421375.19 

If you're not sure what searches you're running, the GET operation at search/jobs endpoint returns a list of searches with their search IDs.

curl -u admin:changeme -k https://localhost:8089/services/search/jobs/ 

Get search results

Use the results endpoint located at /search/jobs/<sid>/results/ to retrieve your search results. This endpoint returns results only when your search has completed. You can also get output from the events endpoint located at /search/jobs/{search_id}/events/ while your search is still running. For complete search results, use the results endpoint.

You can return search results in JSON, CSV or XML by setting the output_mode parameter. By default, results are returned in XML format.

For example, to retrieve search results in CSV format, make the following call.

Note: The curl listing includes --get because you are passing a parameter to a GET operation.

curl -u admin:changeme \
     -k https://localhost:8089/services/search/jobs/1258421375.19/results/ \
     --get -d output_mode=csv

Note: This is one method that you can use to export large numbers of search results. For more information about exporting search results, as well as information about the other export methods, see "Export search results" in the Search Manual.

Python example

This example script authenticates against a Splunk server and runs a search query in Python. After running the search, the script returns the search ID (sid).

#!/usr/bin/python -u

import urllib
import httplib2
from xml.dom import minidom

baseurl = 'https://localhost:8089'
userName = 'admin'
password = 'password'

searchQuery = '| inputcsv foo.csv | where sourcetype=access_common | head 5'

# Authenticate with server.
# Disable SSL cert validation. Splunk certs are self-signed.
serverContent = httplib2.Http(disable_ssl_certificate_validation=True).request(baseurl + '/services/auth/login',
    'POST', headers={}, body=urllib.urlencode({'username':userName, 'password':password}))[1]

sessionKey = minidom.parseString(serverContent).getElementsByTagName('sessionKey')[0].childNodes[0].nodeValue

# Remove leading and trailing whitespace from the search
searchQuery = searchQuery.strip()

# If the query doesn't already start with the 'search' operator or another 
# generating command (e.g. "| inputcsv"), then prepend "search " to it.
if not (searchQuery.startswith('search') or searchQuery.startswith("|")):
    searchQuery = 'search ' + searchQuery

print searchQuery

# Run the search.
# Again, disable SSL cert validation. 
print httplib2.Http(disable_ssl_certificate_validation=True).request(baseurl + '/services/search/jobs','POST',
    headers={'Authorization': 'Splunk %s' % sessionKey},body=urllib.urlencode({'search': searchQuery}))[1]
PREVIOUS
Accessing and updating Splunk Enterprise configurations
 

This documentation applies to the following versions of Splunk® Enterprise: 6.5.0, 6.5.1, 6.5.1612 (Splunk Cloud only), 6.5.2, 6.5.3, 6.5.4, 6.5.5, 6.5.6, 6.5.7, 6.5.8, 6.5.9, 6.5.10, 6.6.0, 6.6.1, 6.6.2, 6.6.3, 6.6.4, 6.6.5, 6.6.6, 6.6.7, 6.6.8, 6.6.9, 6.6.10, 6.6.11, 6.6.12, 7.0.0, 7.0.1, 7.0.2, 7.0.3, 7.0.4, 7.0.5, 7.0.6, 7.0.7, 7.0.8, 7.0.9, 7.0.10, 7.0.11, 7.1.0, 7.1.1, 7.1.2, 7.1.3, 7.1.4, 7.1.5, 7.1.6, 7.1.7, 7.1.9, 7.2.0, 7.2.1, 7.2.2, 7.2.3, 7.2.4, 7.2.5, 7.2.6, 7.2.7, 7.2.8, 7.2.9, 7.3.0, 7.3.1, 7.3.2, 7.1.8, 7.3.3, 8.0.0


Comments

"This means that you must poll the jobs or events endpoint to see if your search has finished." Am I wrong in assuming the search_listener request parameter could be used to avoid polling? (I'm assuming an application running independently of Splunk here.) One would need to write a small server exposing e.g. a 'listener' endpoint on a TCP <port>. When POSTing a search job, one would set up the search_listener along the lines of search_listener="onResults;true;POST;https://localhost:<port>/listener;"
And where is the search_listener documented? I can't find any listing of the possible "search states" it could listen for.

DUThibault
June 19, 2019

"This is one method that you can use to export large numbers of search results. For more information about exporting search results with the REST API, as well as information about the other export methods, see "Export search results" in the Search Manual." But if one does this and looks up https://docs.splunk.com/Documentation/Splunk/latest/Search/ExportdatausingRESTAPI, one finds that there are no other REST API methods!

DUThibault
June 19, 2019

I am trying to use the Python example and am getting an SSL Error despite disabling the certification validation as the example suggests. I have copied everything else in the example exactly, filling in my info for URL/Query/Username/Password. I'm assuming it's something to do with the corporate proxies etc...but was hoping someone could point me in the right direction

This is the error - >
ssl.SSLError: [SSL: WRONG_VERSION_NUMBER] wrong version number (_ssl.c:1056)

Azibuda
May 21, 2019

Hi Kiril123,
You can use the "output_mode" tag to have results returned in a number of encoding formats. For example:

curl -k -u user:pass localhost:8089/services/saved/searches?"output_mode=JSON"

Please note, however, some endpoints only support XML. You can read more about response formats under Encoding schemes here: http://docs.splunk.com/Documentation/Splunk/latest/RESTUM/RESTusing

I hope this helps!
Eve

Emeelan splunk, Splunker
February 15, 2018

Is it possible to receive HTTP response in JSON rather than XML format?

Kiril123
February 10, 2018

Hi @Palrav12,

My assumption is that you want to run a search in the UI then grab the results through our API; is that correct?

There are two ways to find the SID of a job. One is to go to the search in the Splunk UI, click Job > Inspect Job. The Search job inspector will show you the SID in parenthesis.

You can also return the search ID (SID) of various search jobs via API by using the POST command with the following call: https://<host>:<mPort>/services/search/jobs. The <host> field and the <mPort> fields are place holders for your personal info.

You can view more info here: http://docs.splunk.com/Documentation/Splunk/6.6.3/RESTREF/RESTsearch#search.2Fjobs for this endpoint.

Thank you,
Eve Meelan
Technical Writer
Splunk>

Emeelan splunk, Splunker
August 24, 2017

Emeelan splunk, Splunker
August 24, 2017

How to get hte job id, As per my understand we will get the job id from splunk UI.Once we will create job id in splunk then we will get the job id by using curl commmand. let me know if that is wrong. please expalin clearly.

Palrav12
August 22, 2017

Hi Visu,
There is not a webhook for this that I know of, but this page in our app developer documentation discusses how to set up callbacks for different search events.
http://dev.splunk.com/view/webframework-developapps/SP-CAAAEU5

Hope this helps!

Frobinson splunk, Splunker
June 21, 2017

Is there/will there be a webhook for search api calls? Polling to check if the results are ready feels wasteful and unnecessarily hard on your servers.

Visu
June 20, 2017

Hi @Spammenot66,
You can use the earliest_time and latest_time parameters, as mentioned in the linked endpoint docs for search/jobs, to specify your time range. See:
http://docs.splunk.com/Documentation/Splunk/6.5.2/RESTREF/RESTsearch#search.2Fjobs

Hope this helps!

Frobinson splunk, Splunker
March 8, 2017

When running the search using REST API, how do you specify a start and end time for the search? Do we need to use epoch time, date as string? Can you give some examples if more than one method is available for specifying a start and end date?


# Run the search.
# Again, disable SSL cert validation.
print httplib2.Http(disable_ssl_certificate_validation=True).request(baseurl + '/services/search/jobs','POST',
headers={'Authorization': 'Splunk %s' % sessionKey},body=urllib.urlencode({'search': searchQuery}))[1]

Spammenot66
March 7, 2017

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