Create a search
Contents
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 and POST the results to a third party application. Use the search endpoints located at ../services/search/<endpoint>.
When you run a search, Splunk launches a search process asynchronously. This means that you must 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:
curl -u admin:changeme \
-k https://localhost:8089/services/search/jobs/1258421375.19/results/ \
-d output_mode=csv
Python example
Here's an example of authenticating against a Splunk server and running a search query in Python.
#!/opt/splunk/bin/python -u
import urllib
import httplib2
from xml.dom import minidom
baseurl = 'https://localhost:8089'
userName = 'admin'
password = 'changeme'
searchQuery = 'sourcetype=access_common | head 5'
serverContent = httplib2.Http().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
# check if the query has the search operator
if not searchQuery.startswith('search'):
searchQuery = 'search ' + searchQuery
print httplib2.Http().request(baseurl + '/services/search/jobs','POST',
headers={'Authorization': 'Splunk %s' % sessionKey},body=urllib.urlencode({'search': searchQuery}))[1]
Ruby example
The following example shows how to use Ruby to authenticate against the Splunk REST API with a generic user name and password. Then, run a search, delete a specific search job and list out available search jobs. Note that the list is returned in XML and not parsed. To parse the results from endpoints, use an XML parser such as libxml. Also, you'll need to install the hpricot gem to get this to work.
require 'net/https'
require 'rubygems'
require 'hpricot'
class SplunkClient
HOST = 'localhost'
PORT = 8089
USER = 'admin'
PASSWORD = 'changeme'
def splunk_ssl_post_request(path, data = nil, headers = nil)
http = Net::HTTP.new(HOST, PORT)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
http.post(path, data, headers).body
end
def session_key
@session_key ||= load_session_key
end
def load_session_key
doc = Hpricot(splunk_ssl_post_request("/services/auth/login", "username=#{USER}&password=#{PASSWORD}"))
(doc/"//sessionkey").inner_html
end
def create_job query
search = "search index=internetmail #{query}"
splunk_ssl_post_request("/services/search/jobs",
"search=#{CGI::escape(search)}",
{ 'authorization' => "Splunk #{session_key}" })
end
def list_jobs
xml = splunk_ssl_post_request("/services/search/jobs/", nil, {'authorization' => "Splunk #{session_key}"})
puts xml
end
def search_results(sid)
doc = Hpricot(
splunk_ssl_post_request("/services/search/jobs/#{sid}/events",
nil,
{'authorization' => "Splunk #{session_key}"}))
(doc/"/results/result").collect do | result |
log_text = (result/"field[@k='_raw']/v").inner_text
Email.new log_text
end
end
def splunk_ssl_delete_request(path, headers = nil)
http = Net::HTTP.new(HOST, PORT)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
http.delete(path, headers).body
end
def delete_job(sid)
splunk_ssl_delete_request("/services/search/jobs/#{sid}",
{ 'authorization' => "Splunk #{session_key}" })
end
end
# Here's the actual operating code
client = SplunkClient.new
puts client.list_jobs
Thanks to Patrick Shaughnessy for submitting this example. If you'd like to submit code examples, let us know!
This documentation applies to the following versions of Splunk: 4.3 View the Article History for its revisions.