Documentation: 3.2.2
|  Print Version Contents
This page last updated: 04/17/08 05:04pm

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>
 </code>

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

Previous: Properties    |    Next: Streaming

Comments

No comments have been submitted.

Log in to comment.