Documentation: 3.3
|  Print Version Contents
This page last updated: 07/07/08 09:07am

Search Endpoint

Use the services/search/jobs/ endpoint to interact with Splunk's REST search interface. Any search dispatched through the search endpoint receives a $SEARCH_ID you can use as reference.

Jobs

Use the services/search/jobs endpoint to access Splunk's REST search endpoint. Create a new search job with POST. List current search jobs with GET.

POST

Starts a new search job on the Splunk server.

Pass along any of the following variables with your request to constrain your search job.

Form Variables
search The search language string executed on local and remote servers.
remote_server_list Comma separated list of remote servers to search (can include wildcards). This same server list is used in subsearches.
start_time The earliest (inclusive) time limit for the search. The time string can be in UTC (with fractional seconds), a relative time specifier (to now) or a formatted time string.
end_time The latest (exclusive) time limit for the search. The time string can be in UTC (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. Defaults to ISO-8601.
status_buckets Integer. The most status buckets to generate. Defaults to 300.
max_count The number of events 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. Defaults to 10000.
timeout Integer. The number of seconds to keep this search after processing has stopped. Defaults to 86400 (or 24 hours).
enable_eventtypes {1|0} Specfies whether eventtypes should be assigned to events. This may slow searches and should be used with discretion. Defaults to 0.

Response

If your job is executed successfully, Splunk returns a job ID, which you can use to access the search.

Response Status
200 OK
404 something is very wrong

Example

Simple curl example with the search for "syslog." The response is a job id that can be used the $SEARCH_ID (see below).

curl -k -H "$SPLUNK_AUTH_HEADER" -X POST -d "search=search syslog" "$SPLUNK_URL/search/jobs"

<?xml version='1.0'?>
<response><sid>1213402282.1</sid></response>

GET

Returns a list of current searches associated with the user ID authenticating the search.

Response

Response Status
200 Method executed successfully.

Example

curl -k -H "$SPLUNK_AUTH_HEADER" "$SPLUNK_URL/search/jobs/"

<?xml version="1.0" encoding="UTF-8"?>
<!--This is to override browser formatting; see server.conf[httpServer] to disable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .-->
<?xml-stylesheet type="text/xml" href="/static/atom.xsl"?>
<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-06-13T17:18:15-0700</updated>
  <generator version="37999"/>
  <author>
    <name>Splunk</name>
  </author>
  <entry>
    <title>search syslog</title>
    <id>https://localhost:8089/services/search/jobs/1213402282.1</id>
    <updated>2008-06-13T17:11:23.000-07:00</updated>
    <link href="https://localhost:8089/services/search/jobs/1213402282.1" rel="alternate"/>
    <published>2008-06-13T17:11:22.000-07:00</published>
    <link href="https://localhost:8089/services/search/jobs/1213402282.1/events" rel="events"/>
    <link href="https://localhost:8089/services/search/jobs/1213402282.1/results" rel="results"/>
    <link href="https://localhost:8089/services/search/jobs/1213402282.1/timeline" rel="timeline"/>
    <link href="https://localhost:8089/services/search/jobs/1213402282.1/summary" rel="summary"/>
    <link href="https://localhost:8089/services/search/jobs/1213402282.1/control" rel="control"/>
    <author>
      <name>admin</name>
    </author>
    <content type="text/xml">
      <s:dict>
        <s:key name="cursorTime">2008-05-22T14:46:31.000-07:00</s:key>
        <s:key name="error"></s:key>
        <s:key name="eventCount">1</s:key>
        <s:key name="isDone">1</s:key>
        <s:key name="isFinalized">0</s:key>
        <s:key name="isPaused">0</s:key>
        <s:key name="isStreaming">1</s:key>
        <s:key name="keywords">syslog</s:key>
        <s:key name="resultCount">1</s:key>
        <s:key name="sid">1213402282.1</s:key>
        <s:key name="ttl">23.89 hours</s:key>
      </s:dict>
    </content>
  </entry>
</feed>


Search ID

Use the services/search/jobs/$SEARCH_ID endpoint to access a specific search you've already dispatched. Replace $SEARCH_ID with the ID of an active search in the search system. $SEARCH_ID is returned anytime you launch a job via the search/jobs endpoint.

GET

Returns summary information about the search job.

Response

Response Status
200 OK
404 Search job id was not found on this server.

Example

curl -k -H "$SPLUNK_AUTH_HEADER" "$SPLUNK_URL/search/jobs/1213402282.1"

<?xml version="1.0" encoding="UTF-8"?>
<!--This is to override browser formatting; see server.conf[httpServer] to disable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .-->
<?xml-stylesheet type="text/xml" href="/static/atom.xsl"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest">
  <title>search syslog</title>
  <id>https://localhost:8089/services/search/jobs/1213402282.1</id>
  <updated>2008-06-13T17:11:23.000-07:00</updated>
  <link href="https://localhost:8089/services/search/jobs/1213402282.1" rel="alternate"/>
  <published>2008-06-13T17:11:22.000-07:00</published>
  <link href="https://localhost:8089/services/search/jobs/1213402282.1/events" rel="events"/>
  <link href="https://localhost:8089/services/search/jobs/1213402282.1/results" rel="results"/>
  <link href="https://localhost:8089/services/search/jobs/1213402282.1/timeline" rel="timeline"/>
  <link href="https://localhost:8089/services/search/jobs/1213402282.1/summary" rel="summary"/>
  <link href="https://localhost:8089/services/search/jobs/1213402282.1/control" rel="control"/>
  <author>
    <name>admin</name>
  </author>
  <content type="text/xml">
    <s:dict>
      <s:key name="cursorTime">2008-05-22T14:46:31.000-07:00</s:key>
      <s:key name="error"></s:key>
      <s:key name="eventCount">1</s:key>
      <s:key name="isDone">1</s:key>
      <s:key name="isFinalized">0</s:key>
      <s:key name="isPaused">0</s:key>
      <s:key name="isStreaming">1</s:key>
      <s:key name="keywords">syslog</s:key>
      <s:key name="resultCount">1</s:key>
      <s:key name="sid">1213402282.1</s:key>
      <s:key name="ttl">23.97 hours</s:key>
    </s:dict>
  </content>
</entry>

DELETE

Deletes the specified search job.

Response

Response Status
200 OK
404 Search job id was not found on this server.

Events

The endpoint /services/search/jobs/$SEARCH_ID/events references the raw events returned by the current search.

GET

This is the primary method for a client to fetch a set of untransformed [EXPLAIN TRANSFORM VS 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.
search The post processing search to apply to results. Can be any valid search language string.
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] A list of the fields to return for the event set. Defaults to *.
output_mode {csv,raw,xml,json} Specifies what format the output should be returned in. Defaults to xml.
segmentation The type of segmentation to perform on the data. This includes an option to perform k/v segmentation. Defaults to raw.

Response

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.

Sample JSON output to 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"
    }
]

Results

The /services/search/jobs/$SEARCH_ID/results endpoint 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 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.
show_incomplete {1|0} Toggle whether or not to generate a preview of the results if the final results are not ready. Set to 1 to generate preview. Defaults to 0. Generating incomplete results are a potentially expensive operation.
timeout This option specifies the maximum amount of time in seconds to wait for incomplete results. This option is only valid if show_incomplete=1. Default value is 30.
search The post processing search to apply to results. Can be any valid search language string.
field_list A comma separated list of the fields to return for the event set. Defaults to *.
output_mode {csv,raw,xml,json} Specifies what format the output should be returned in. Defaults to XML.

Response

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.

Sample JSON output to <code>https://localhost:8089/services/search/jobs/1234/results?output_mode=json}}</code>.

    [
    {
    "_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"
    }
    ]


Timeline

The /services/search/jobs/$SEARCH_ID/timeline endpoint 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

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

Summary

The /services/search/jobs/$SEARCH_ID/summary endpoints 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 A comma separated list of the fields to return for the event set. Defaults to *.
top_count For each key, this number of the most frequent items will be returned. Defaults to 10.

Response

Response Status
200 Action was executed successfully
403 Not authorized to execute action
404 Search id was not found on server

Control

The /services/search/jobs/$SEARCH_ID/control endpoint provides job control handle for current search.

POST

Execute 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

Response Status
200 Action was executed successfully
403 Not authorized to execute action
404 Search id was not found on server
Previous: Search Overview    |    Next: Search with the Python SDK

Comments

  1. This is true -- by default, all included endpoints require authentication. Please see this section on authenticating:

    http://www.splunk.com/doc/latest/developer/DevGetStarted
    Posted by emma on Aug 26 2008, 12:14pm

  2. You will need to add an 'Authorization' header to the call, with the value "Splunk $session_key" (the string 'Splunk' concatenated with a space concatenated with the session key you got from the auth call earlier.
    Posted by pfig on Aug 23 2008, 12:47pm

Log in to comment.