Search
This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Contents
Search
/services/search/jobs
Provides listing for for jobs
GET
Returns a list of current searches. Optional filter arguments can be passed to specify searches. The user id is implied by the authetication to the call.
Response Status
200 - OK
Response Body
<?xml version="1.0" encoding="UTF-8"?> <feed xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest"> <title>jobs</title> <id>https://localhost:8089/services/search/jobs</id> <updated>2008-01-11T14:02:00-0800</updated> <generator version="30887"/> <author> <name>Splunk</name> </author> <entry> <title>search *</title> <id>https://localhost:8089/services/search/jobs/1014004140</id> <published>2008-01-11T14:02:00-0800</published> <updated>2008-01-11T14:02:00-0800</updated> <link href="https://localhost:8089/services/search/jobs/1014004140" rel="alternate"/> <link href="https://localhost:8089/services/search/jobs/1014004140/events" rel="events"/> <link href="https://localhost:8089/services/search/jobs/1014004140/results" rel="results"/> <link href="https://localhost:8089/services/search/jobs/1014004140/timeline" rel="timeline"/> <link href="https://localhost:8089/services/search/jobs/1014004140/summary" rel="summary"/> <link href="https://localhost:8089/services/search/jobs/1014004140/control" rel="control"/> <s:messages> <s:msg type="ERROR">my error text</s:msg> <s:msg type="WARN">my error text</s:msg> </s:messages> <author> <name>admin</name> </author> <content type="text/xml"> <s:dict> <s:key name="sid">1014004140</s:key> <s:key name="eventCount">1234</s:key> <s:key name="cursorTime">2008-01-11T19:24:00-0800</s:key> <s:key name="isDone">0</s:key> <s:key name="isFinalized">1</s:key> <s:key name="keywords">none</s:key> <s:key name="isPaused">0</s:key> <s:key name="isStreaming">0</s:key> <s:key name="ttl">24.00 hours</s:key> </s:dict> </content> </entry> </feed>
POST
Starts a new search job on Splunk server
Form Variables
search -This is the search language string that will be executed taking results from the local and remote servers.
remote_server_list - (comma separated list) (default: empty) This is the list of (possibly wildcarded) servers from which raw events should be pulled. This same server list is to be used in subsearches.
start_time - The earliest (inclusive), respectively, time bounds for the search. The time string can be either a UTC time (with fractional seconds), a relative time specifier (to now) or a formatted time string.
end_time - The latest (exclusive), respectively, time bounds for the search. The time string can be either a UTC time (with fractional seconds), a relative time specifier (to now) or a formatted time string.
time_format - Used to convert a formatted time string from {start,end}_time into UTC seconds. It defaults to ISO-9601.
status_buckets - [int] (default: 300) The most status buckets to generate.
with_event_types - {1,0} (default: 0) Specifies whether events should be processed for event types.
max_count - (default: 10000) The number of events that can be accessible in any given status bucket. Also, in transforming mode, the maximum number of results to store. Specifically, in all calls, offset+count <= max_count.
timeout - [int] (default: 86400) The number of seconds to keep this search after processing has stopped.
enable_eventtypes - Specfies whether eventtypes should be assigned to events. This option causes searches to be significantly slower and should be used with discretion.
Response Status
200 - OK
404 - something is very wrong
Response Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
<sid>12345</sid>
</response>
/services/search/jobs/search_id
Represents an active search in the search system.
GET
Returns summary information about the search job
Response Status
200 - OK
404 - Search job id was not found on this server
Response Body
<?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest"> <title>search *</title> <id>https://localhost:8089/services/search/jobs/1014004140</id> <updated>2008-01-11T14:02:00-0800 (mtime)</updated> <published>2008-01-11T14:02:00-0800 (start)</published> <link href="https://localhost:8089/services/search/jobs/1014004140/events" rel="events"/> <link href="https://localhost:8089/services/search/jobs/1014004140/results" rel="results"/> <link href="https://localhost:8089/services/search/jobs/1014004140/timeline" rel="timeline"/> <link href="https://localhost:8089/services/search/jobs/1014004140/summary" rel="summary"/> <link href="https://localhost:8089/services/search/jobs/1014004140/control" rel="control"/> <s:messages> <s:msg type="ERROR">my error text</s:msg> <s:msg type="WARN">my error text</s:msg> </s:messages> <author> <name>admin</name> </author> <content type="text/xml"> <s:dict> <s:key name="sid">1014004140</s:key> <s:key name="eventCount">1234</s:key> <s:key name="cursorTime">2008-01-11T19:24:00-0800</s:key> <s:key name="isDone">0</s:key> <s:key name="isFinalized">1</s:key> <s:key name="keywords">none</s:key> <s:key name="isPaused">0</s:key> <s:key name="isStreaming">0</s:key> <s:key name="ttl">24.00 hours</s:key> </s:dict> </content> </entry>
</pre>
DELETE
Deletes the current search job
Response Status
200 - OK
404 - Search job id was not found on this server
/services/search/jobs/search_id/events
Represents the raw events returned by the current search
GET
This is the primary method for a client to fetch a set of untransformed events. If the dispatched search includes a transforming command, the events here are those that would be transformed, not the final transformed results.
Request Query
offset - The first result (inclusive) from which to begin returning data. This value is 0-indexed. Default value is 0.
count - The maximum number of results to return. If value is set to 0, then all available results are returned. Default value is 100
start_time - The earliest (inclusive), respectively, time bounds for the results to be returned. If not specified, the range applies to all results found.
end_time - The latest (exclusive), respectively, time bounds for the results to be returned. If not specified, the range applies to all results found.
time_format - Used to convert a formatted time string from {start,end}_time into UTC seconds. It defaults to %m/%d/%Y:%H:%M:%S
field_list - [comma separated list] (default: *) A list of the fields to return for the event set.
max_lines - (default: 0) (NI) The most lines that any single event's _raw field should contain. The value 0 is used to specify no limit.
truncation_mode - {abstract,truncate} (default: abstract) (NI) Specifies how "max_lines" should be achieved.
output_mode - {csv,text,xml,json} (default: text) Specifies what format the output should be returned in.
segmentation - (default: raw) The type of segmentation to perform on the data. This will include an option to perform k/v segmentation.
Response Status
200 - Search events returned
204 - Search job was found, but the server has not finished preparing the events yet; retry your request.
404 - Search job id was not found on this server
Response Body
// sample JSON output
// https://localhost:8089/services/search/jobs/1234/events?output_mode=json
[
{
"_cd": "0:4374557",
"_index": "main",
"_kv": "1",
"_meta": " date_second::36 date_hour::19 date_minute::11 date_year::2008 date_month::january date_mday::21 date_wday::monday date_zone::-480 punct::_[//:::_-]____\\\"@...\\\"...",
"_raw": "I [21/Jan/2008:19:11:36 -0800] Added remote printer \"HPLaserJ@10.1.1.123\"...",
"_serial": "0",
"_time": "1200971496",
"date_hour": "19",
"date_mday": "21",
"date_minute": "11",
"date_month": "january",
"date_second": "36",
"date_wday": "monday",
"date_year": "2008",
"date_zone": "-480",
"host": "decider.local",
"linecount": "1",
"punct": "_[//:::_-]____\"@...\"...",
"source": "/var/log/cups/error_log",
"sourcetype": "cups_error"
},
{
"_cd": "0:4374549",
"_index": "main",
"_kv": "1",
"_meta": " date_second::36 date_hour::19 date_minute::11 date_year::2008 date_month::january date_mday::21 date_wday::monday date_zone::-480 punct::_[//:::_-]____\\\"@...\\\"...",
"_raw": "I [21/Jan/2008:19:11:36 -0800] Added remote printer \"HPLaserJ@10.1.5.65\"...",
"_serial": "1",
"_time": "1200971496",
"date_hour": "19",
"date_mday": "21",
"date_minute": "11",
"date_month": "january",
"date_second": "36",
"date_wday": "monday",
"date_year": "2008",
"date_zone": "-480",
"host": "decider.local",
"linecount": "1",
"punct": "_[//:::_-]____\"@...\"...",
"source": "/var/log/cups/error_log",
"sourcetype": "cups_error"
}
]
/services/search/jobs/search_id/results
This is the primary method for a client to fetch a set of TRANSFORMED events. If the dispatched search does not include a transforming command, the effect is the same as get_events, albeit with fewer options.
GET
Request Query
offset - The first result (inclusive) from which to begin returning data. This value is 0-indexed. Default value is 0.
count - The maximum number of results to return. If value is set to 0, then all available results are returned. Default value is 100
field_list - [comma separated list] (default: *) A list of the fields to return for the event set.
output_mode - {csv,text,xml,json} (default: text) Specifies what format the output should be returned in.
Response Status
200 - Search events returned
204 - Search job was found, but the server has not finished preparing the events yet; retry your request.
404 - Search job id was not found on this server
Response Body
// sample JSON output
// https://localhost:8089/services/search/jobs/1234/results?output_mode=json
[
{
"_cd": "0:4374557",
"_index": "main",
"_kv": "1",
"_meta": " date_second::36 date_hour::19 date_minute::11 date_year::2008 date_month::january date_mday::21 date_wday::monday date_zone::-480 punct::_[//:::_-]____\\\"@...\\\"...",
"_raw": "I [21/Jan/2008:19:11:36 -0800] Added remote printer \"HPLaserJ@10.1.1.123\"...",
"_serial": "0",
"_time": "1200971496",
"date_hour": "19",
"date_mday": "21",
"date_minute": "11",
"date_month": "january",
"date_second": "36",
"date_wday": "monday",
"date_year": "2008",
"date_zone": "-480",
"host": "decider.local",
"linecount": "1",
"punct": "_[//:::_-]____\"@...\"...",
"source": "/var/log/cups/error_log",
"sourcetype": "cups_error"
},
{
"_cd": "0:4374549",
"_index": "main",
"_kv": "1",
"_meta": " date_second::36 date_hour::19 date_minute::11 date_year::2008 date_month::january date_mday::21 date_wday::monday date_zone::-480 punct::_[//:::_-]____\\\"@...\\\"...",
"_raw": "I [21/Jan/2008:19:11:36 -0800] Added remote printer \"HPLaserJ@10.1.5.65\"...",
"_serial": "1",
"_time": "1200971496",
"date_hour": "19",
"date_mday": "21",
"date_minute": "11",
"date_month": "january",
"date_second": "36",
"date_wday": "monday",
"date_year": "2008",
"date_zone": "-480",
"host": "decider.local",
"linecount": "1",
"punct": "_[//:::_-]____\"@...\"...",
"source": "/var/log/cups/error_log",
"sourcetype": "cups_error"
}
]
/services/search/jobs/search_id/timeline
Provides "timeline" output of the so-far-read untransformed events.
GET
Returns the timeline data
Request Query
time_format
Used to convert a formatted time string from {start,end}_time into UTC seconds. It defaults to %m/%d/%Y:%H:%M:%S
Response Status
200 - OK
204 - Search id was found, but the server has not finished preparing the events yet; retry your request.
404 - Search id was not found on server
Response Body
<?xml version="1.0"?> <timeline c="478586" cursor="1143878400"> <bucket c="2" t="1143878400.000" d="2588400" f="1">2006-04-01T00:00:00.000-08:00</bucket> <bucket c="0" t="1146466800.000" d="2678400" f="1">2006-05-01T00:00:00.000-07:00</bucket> <bucket c="0" t="1149145200.000" d="2592000" f="1">2006-06-01T00:00:00.000-07:00</bucket> ... <bucket c="37620" t="1191222000.000" d="2678400" f="1">2007-10-01T00:00:00.000-07:00</bucket> <bucket c="108760" t="1193900400.000" d="2595600" f="1">2007-11-01T00:00:00.000-07:00</bucket> <bucket c="102507" t="1196496000.000" d="2678400" f="1">2007-12-01T00:00:00.000-08:00</bucket> <bucket c="67179" t="1199174400.000" d="2678400" f="1">2008-01-01T00:00:00.000-08:00</bucket> </timeline>
/services/search/jobs/search_id/summary
Provides "getFieldsAndStats" output of the so-far-read untransformed events.
GET
Returns the summary output
Request Query
start_time - The earliest (inclusive), respectively, time bounds for the results to be returned. If not specified, the range applies to all results found.
end_time - The latest (exclusive), respectively, time bounds for the results to be returned. If not specified, the range applies to all results found.
time_format - Used to convert a formatted time string from {start,end}_time into UTC seconds. It defaults to %m/%d/%Y:%H:%M:%S
field_list - [comma separated list] (default: *) A list of the fields to return for the event set.
top_count - (default: 10) For each key, this number of the most frequent items will be returned.
Response Status
200 - Action was executed successfully
403 - Not authorized to execute action
404 - Search id was not found on server
/services/search/jobs/search_id/control
Provides job control handle for current search
POST
Executes a job control command
Request Form
action - The control action to execute
pause - Suspends the execution of the current search
unpause - Resumes the execution of the current search, if paused
finalize - Stops the search, and provides intermediate results to the /results endpoint
cancel - Stops the current search and deletes the result cache
Response Status
200 - Action was executed successfully
403 - Not authorized to execute action
404 - Search id was not found on server
This documentation applies to the following versions of Splunk: 3.2 , 3.2.1 , 3.2.2 , 3.2.3 , 3.2.4 , 3.2.5 , 3.2.6 View the Article History for its revisions.