Starting a Search Job

The most up-to-date version of this page lives here.

Splunk is a search engine, so most of the REST calls you'll be making will be doing searches. Starting in Splunk 3.2, searches are done by creating jobs, then reading from the job IDs to see the results. Results can come in asynchronously, so you don't have to block in your code waiting on the search to complete.

Search jobs are created via POSTs to the /search/jobs endpoints:

https://localhost:8089/services/search/jobs/

When you create search jobs, you'll need to pass search parameters into the call as a text string. For example, to do the default search you would pass search * hoursago=24 into the REST call.

The following Python code illustrates how to connect to the server, authenticate, grab a token, and then use the token to create a job that does a default search. Again, if you are running the free version, it is not necessary to get a token to talk to the endpoints.

from httplib2 import Http 
from urllib import urlencode
import xml.dom.minidom as xml

# set variables
endpoint = 'https://localhost:8089'
authURI = endpoint + '/services/auth/login/'
jobURI = endpoint + '/services/search/jobs/'
authData = {'username': "admin", 'password': "changeme"}
headers = {}

# initialize our connection handler
h = Http()

# open a connection and do a POST for auth
resp, content = h.request(authURI, "POST", urlencode(authData))

# parse our token out of the response
xmlDoc = xml.parseString(content)
tokenElements = xmlDoc.getElementsByTagName('sessionKey')

if not tokenElements:
        print 'No session key found!  Are you running the free version?'
        tokenElements = xmlDoc.getElementsByTagName('msg')
        print 'Reason=%s' % tokenElements[0].firstChild.nodeValue
        headers['Authorization'] = ''
else:
        sessionKey = tokenElements[0].firstChild.nodeValue
        print 'sessionKey=%s' % sessionKey
        headers['Authorization'] = 'Splunk %s' % sessionKey

# set up our search job
postargs = { 'search': "search * hoursago=24" }
payload = urlencode(postargs)

# open a connection and do a POST for a new job
resp, content = h.request(jobURI, "POST", headers=headers, body=payload)

print 'server returned code %s.' % resp.status
print content

Save this as something like start_job.py and then run it:

[kord@tiny examples]$ python start_job.py 
sessionKey=131e32fc70ff741993f9e667cf6b44ab
server returned code 201.
<?xml version='1.0'?>
<response><sid>1209537183.1821</sid></response>
[kord@tiny examples]$ 

<< Go back to Auth | Move on to Handle Search >>