Documentation > Splunk > REST API Reference > Creating searches using the REST API

REST API Reference

 


REST API reference
Using Splunk's REST API

Creating searches using the REST API

Contents

Creating searches using the REST API

Use the search/jobs endpoint to create a search job in Splunk. 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

The best place to learn about searches and how to write searches is the Search Manual.

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

REST endpoints for searches

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

/search/jobs
Create 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 the Search Reference.

performance
The GET operation for /search/jobs returns information that helps you troubleshoot the efficiency of a search. Refer to Execution costs in the Search Reference for more information.

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 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.

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

Python example

Here's an example of authenticating against a Splunk server and running 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 = 'pass'

searchQuery = '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

# check if the query has the search operator
if not searchQuery.startswith('search'):
    searchQuery = 'search ' + 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]

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
Retrieved from "http://docs.splunk.com/Documentation/Splunk/5.0.2/RESTAPI/RESTsearches"

This documentation applies to the following versions of Splunk: 5.0 , 5.0.1 , 5.0.2 View the Article History for its revisions.


You must be logged into splunk.com in order to post comments. Log in now.

Was this documentation topic helpful?

If you'd like to hear back from us, please provide your email address:

We'd love to hear what you think about this topic or the documentation as a whole. Feedback you enter here will be delivered to the documentation team.

Feedback submitted, thanks!