Search Overview

Before you can build effective extensions to Splunk using the REST API, you should understand how Splunk search works. If you are not already familiar with the Splunk search syntax, read how search works. You can find an example of using the search endpoint with the Python SDK here.

Handling Search Results

Once you create a search job, Splunk continues to add results to the search until it is complete. Jobs can be queried to see if they are complete, or you can fetch portions of the results while the job is being updated.

Check to see if a job has been created, how many results have been returned, and whether or not it is still running by doing a GET on the following URL:

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

Because this is a GET call, you can use this right in your web browser. Query a job directly by putting its job_id on the end of the URL:

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

search 404
cursorTime    2003-05-01T00:00:00.000-04:00
error        
eventCount    3862
isDone        1
isFinalized    0
isPaused    0
isStreaming    1
keywords    404
sid        1209535222.1235
ttl        23.98 hours

Result Formats

The result format is determined by passing an output_format parameter to the job URL.

https://localhost:8089/services/search/jobs/1209535222.1235//results?count=150&output_mode=json

You can use the following output formats: 'csv', 'json', 'raw', 'xml', 'xml_atom'

What's the data type that you're getting back?

Events come back as either untransformed events or transformed events.

Are your results restricted by access controls?

The user you authenticate as determines what data you have access to. Consider creating a user with limited access specifically for your REST API searches.

How are you handling time ranges?

Time values are passed in as header parameters. You can pass time values as starttime and endtime in epoch seconds (which you must do if you pass them this way), or you can pass them in the search string itself.
To see how that works, use Splunk Web to build queries. Try searching for something over a custom time range.
You can also specify times relative to "now".

Here is the BNF for the relative time arguments:

<rel_time> ::= "now" | ("-"|"+")<integer><unit>
<unit>     ::= "seconds" | "minutes" | "hours" | "days" | "weeks" | "months" | "years"

If you use "now", Splunk returns the raw result of a call to the system call "time" is returned. Otherwise, specify a unit to subtract or add that amount of time to "now."
For example, suppose "now" is 10/9/2007, 07:32:15, the relative specifier "+2d" becomes to 10/11/2007, 07:32:15.

Searchable fields

Any fields that are extracted at search time are available. Be aware that when you search, multiple field extractions are being created and returned to the interface, although you may not see them all.

The following search gives you the number of occurrences and distinct values of each field in the most recent <maxresults> of sourcetype=foo
> sourcetype=foo | stats count(*) dc(*)

If you want this information over all results, perform the same search using the CLI dispatch command, which is useful for long-running searches.

Previous: Configuration file access with Python | Next: Search Endpoint

Comments

I have cleared up that part of the page. You should be able to specify minutes or months instead of just m.
Posted by emma on Aug 25 2008, 4:09pm
It's not clear from the BNF which 'm' stands for 'minutes' and which stands for 'months'. Can you please clarify/fix this?
Posted by pfig on Aug 23 2008, 2:06pm