Documentation > Splunk > REST API Reference > Search

REST API Reference

 


REST API reference
Using Splunk's REST API

Search

This documentation does not apply to the most recent version of Splunk. Click here for the latest version.

Contents

Search

Use the Search endpoints to manage searches, alerts, and view objects generated from searches.


alerts/*
Manage alerts triggered by searches.


data/commands/
Retrieve information about Python search commands.


saved/searches/*
Create and manage saved searches.


search/jobs
Create, manage, and view results of Splunk searches.


scheduled/views/*
Manage scheduled view objects.

alerts/fired_alerts

Provides access to all alerts that have been fired on the server.

GET alerts/fired_alerts

Returns a summary view of the list of all alerts that have been fired on the server.

Request

Name Type Required Default Description
count Number 30 Indicates the maximum number of entries to return. To return all entries, specify 0.
offset Number 0 Index for first item to return.
search String Search expression to filter the response. The response matches field values against the search expression. For example:

search=foo matches any object that has "foo" as a substring in a field. search=field_name%3Dfield_value restricts the match to a single field. URI-encoding is required in this example.

sort_dir Enum asc Valid values: (asc | desc)

Indicates whether to sort returned entries in ascending or descending order.

sort_key String name Field to use for sorting.
sort_mode Enum auto Valid values: (auto | alpha | alpha_case | num)

Indicates the collating sequence for sorting the returned entries. auto: If all values of the field are numbers, collate numerically. Otherwise, collate alphabetically. alpha: Collate alphabetically. alpha_case: Collate alphabetically, case-sensitive. num: Collate numerically.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view fired alerts.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
triggered_alert_count the number of time this alert has been triggered.

Example

This example lists all alerts fired on this server that belong to the admin user. 


curl -k -u admin:pass https://localhost:8089/servicesNS/admin/-/alerts/fired_alerts



<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>alerts</title>
  <id>https://localhost:8089/services/alerts/fired_alerts</id>
  <updated>2011-07-11T19:27:22-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
  <entry>
    <title>-</title>
    <id>https://localhost:8089/servicesNS/admin/search/alerts/fired_alerts/-</id>
    <updated>2011-07-11T19:27:22-07:00</updated>
    <link href="/servicesNS/admin/search/alerts/fired_alerts/-" rel="alternate"/>
    <author>
      <name>admin</name>
    </author>
    <link href="/servicesNS/admin/search/alerts/fired_alerts/-" rel="list"/>
    <content type="text/xml">
      <s:dict>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="triggered_alert_count">0</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

alerts/fired_alerts/{name}

DELETE alerts/fired_alerts/{name}

Deletes the record of this triggered alert.

Request

No parameters for this request.

Response Codes

Status Code Description
200 Deleted successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to delete the fired alert.
404 Fired alert does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

No values returned for this request.

Example

Remove this particular record of the "have_events" alert being fired on this server. Note that the name is specially crafted, and was retrieved from the GET fired_alerts/have_events response. 


curl -k -u admin:pass --request DELETE \
	https://localhost:8089/servicesNS/admin/search/alerts/fired_alerts/scheduler__admin__search_aGF2ZV9ldmVudHM_at_1310437740_5d3dfde563194ffd_1310437749



<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>alerts</title>
  <id>https://localhost:8089/servicesNS/admin/search/alerts/fired_alerts</id>
  <updated>2011-07-11T19:35:25-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
</feed>

GET alerts/fired_alerts/{name}

Returns a list of all unexpired triggered or fired instances of this alert.

Specify - for {name} to return all fired alerts. For example: 

curl -k -u admin:pass https://localhost:8089/servicesNS/admin/search/alerts/fired_alerts/-

Request

No parameters for this request.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view fired alert.
404 Fired alert does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
actions Any additional alert actions triggered by this alert.
alert_type Indicates if the alert was historical or realtime.
expiration_time The time the alert expires, and no longer appears in the list of alerts.
savedsearch_name Name of the saved search that triggered the alert.
severity Indicates the severity level of an alert.

Severity level ranges from Info, Low, Medium, High, and Critical. Default is Medium.

Severity levels are informational in purpose and have no additional functionality.

sid The search ID of the search that triggered the alert.
trigger_time The time the alert was triggered.

Example

Retrieve all instances of the "have_alert" alert being fired. 


curl -k -u admin:pass https://localhost:8089/servicesNS/admin/search/alerts/fired_alerts/have_events



<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>alerts</title>
  <id>https://localhost:8089/servicesNS/admin/search/alerts/fired_alerts</id>
  <updated>2011-07-11T19:29:46-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
  <entry>
    <title>scheduler__admin__search_aGF2ZV9ldmVudHM_at_1310437740_5d3dfde563194ffd_1310437749</title>
    <id>https://localhost:8089/servicesNS/admin/search/alerts/fired_alerts/scheduler__admin__search_aGF2ZV9ldmVudHM_at_1310437740_5d3dfde563194ffd_1310437749</id>
    <updated>2011-07-11T19:29:09-07:00</updated>
    <link href="/servicesNS/admin/search/alerts/fired_alerts/scheduler__admin__search_aGF2ZV9ldmVudHM_at_1310437740_5d3dfde563194ffd_1310437749" rel="alternate"/>
    <author>
      <name>admin</name>
    </author>
    <published>2011-07-11T19:29:09-07:00</published>
    <link href="/servicesNS/admin/search/alerts/fired_alerts/scheduler__admin__search_aGF2ZV9ldmVudHM_at_1310437740_5d3dfde563194ffd_1310437749" rel="list"/>
    <link href="/servicesNS/admin/search/alerts/fired_alerts/scheduler__admin__search_aGF2ZV9ldmVudHM_at_1310437740_5d3dfde563194ffd_1310437749" rel="remove"/>
    <link href="/servicesNS/admin/search/search/jobs/scheduler__admin__search_aGF2ZV9ldmVudHM_at_1310437740_5d3dfde563194ffd" rel="job"/>
    <link href="/servicesNS/admin/search/saved/searches/have_events" rel="savedsearch"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="actions"/>
        <s:key name="alert_type">historical</s:key>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="expiration_time">1310524149</s:key>
        <s:key name="savedsearch_name">have_events</s:key>
        <s:key name="severity">3</s:key>
        <s:key name="sid">scheduler__admin__search_aGF2ZV9ldmVudHM_at_1310437740_5d3dfde563194ffd</s:key>
        <s:key name="trigger_time">1310437749</s:key>
      </s:dict>
    </content>
  </entry>
</feed>


data/commands

Provides access to Python search commands used in Splunk.

GET data/commands

List all python search commands.

Request

Name Type Required Default Description
count Number 30 Indicates the maximum number of entries to return. To return all entries, specify 0.
offset Number 0 Index for first item to return.
search String Search expression to filter the response. The response matches field values against the search expression. For example:

search=foo matches any object that has "foo" as a substring in a field. search=field_name%3Dfield_value restricts the match to a single field. URI-encoding is required in this example.

sort_dir Enum asc Valid values: (asc | desc)

Indicates whether to sort returned entries in ascending or descending order.

sort_key String name Field to use for sorting.
sort_mode Enum auto Valid values: (auto | alpha | alpha_case | num)

Indicates the collating sequence for sorting the returned entries. auto: If all values of the field are numbers, collate numerically. Otherwise, collate alphabetically. alpha: Collate alphabetically. alpha_case: Collate alphabetically, case-sensitive. num: Collate numerically.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view commands.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
changes_colorder Indicates whether the script output should be used to change the column ordering of the fields.
disabled Indicates if the command is disabled.
eai:appName Indicates the Splunk app context for this command.
eai:userName Indicates the Splunk user context for this command.
enableheader Indicate whether or not your script is expecting header information or not.


Currently, the only thing in the header information is an auth token. If set to true the command expects as input a head section + '\ ' then the csv input.

Note: Should be set to true if you use splunk.Intersplunk

filename Name of script file for command.

<stanza-name>.pl for perl.

<stanza-name>.py for python.

generates_timeorder If generating = false and streaming = true, indicates if the command changes the order of events w/respect to time.
generating Indicates if the command generates new events.
maxinputs Maximum number of events that can be passed to the command for each invocation. This limit cannot exceed the value of maxresultrows in limits.conf.

0 indicates no limit. Defaults to 50000.

outputheader If true, the output of script should be a header section + blank line + csv ouput.

If false, script output should be pure csv only.

passauth If true, passes an authentication token on the start of input.
required_fields A list of fields that this command may use. Informs previous commands that they should retain/extract these fields if possible. No error is generated if a field specified is missing.

Defaults to '*'.

requires_preop Indicates whether the command sequence specified by the streaming_preop key is required for proper execution or is it an optimization only.

Default is false (stremaing_preop not required).

retainsevents Indicates whether the command retains events (the way the sort/dedup/cluster commands do) or whether the command transforms them (the way the stats command does).
streaming Indicates whether the command is streamable.
supports_getinfo Indicates whether the command supports dynamic probing for settings (first argument invoked == __GETINFO__ or __EXECUTE__).
supports_rawargs Indicates whether the command supports raw arguments being passed to it or if it uses parsed arguments (where quotes are stripped).
type Specifies the type of command. The only valid value for this attribute is python.

Example

List python search commands. 


curl -k -u admin:pass https://localhost:8089/servicesNS/nobody/search/data/commands



<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>commandsconf</title>
  <id>https://localhost:8089/servicesNS/nobody/search/data/commands</id>
  <updated>2011-07-07T00:52:26-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/servicesNS/nobody/search/data/commands/_reload" rel="_reload"/>
  <s:messages/>
  <entry>
    <title>bucketdir</title>
    <id>https://localhost:8089/servicesNS/nobody/search/data/commands/bucketdir</id>
    <updated>2011-07-07T00:52:26-07:00</updated>
    <link href="/servicesNS/nobody/search/data/commands/bucketdir" rel="alternate"/>
    <author>
      <name>nobody</name>
    </author>
    <link href="/servicesNS/nobody/search/data/commands/bucketdir" rel="list"/>
    <link href="/servicesNS/nobody/search/data/commands/bucketdir/_reload" rel="_reload"/>
    <link href="/servicesNS/nobody/search/data/commands/bucketdir/disable" rel="disable"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="changes_colorder">1</s:key>
        <s:key name="disabled">0</s:key>
        <s:key name="eai:appName">search</s:key>
        <s:key name="eai:userName">admin</s:key>
        <s:key name="enableheader">1</s:key>
        <s:key name="filename">bucketdir.py</s:key>
        <s:key name="generates_timeorder">0</s:key>
        <s:key name="generating">0</s:key>
        <s:key name="maxinputs">50000</s:key>
        <s:key name="outputheader">0</s:key>
        <s:key name="passauth">0</s:key>
        <s:key name="required_fields">*</s:key>
        <s:key name="requires_preop">0</s:key>
        <s:key name="retainsevents">0</s:key>
        <s:key name="streaming">0</s:key>
        <s:key name="supports_getinfo">0</s:key>
        <s:key name="supports_rawargs">1</s:key>
        <s:key name="type">python</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

data/commands/{name}

GET data/commands/{name}

Provide information about a specific python search command.

Request

No parameters for this request.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view command.
404 Command does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
changes_colorder Indicates whether the script output should be used to change the column ordering of the fields.
disabled Indicates if the command is disabled.
eai:appName Indicates the Splunk app context for this command.
eai:attributes See Accessing Splunk resources
eai:userName Indicates the Splunk user context for this command.
enableheader Indicate whether or not your script is expecting header information or not.


Currently, the only thing in the header information is an auth token. If set to true the command expects as input a head section + '\ ' then the csv input.

Note: Should be set to true if you use splunk.Intersplunk

filename Name of script file for command.

<stanza-name>.pl for perl.

<stanza-name>.py for python.

generates_timeorder If generating = false and streaming = true, indicates if the command changes the order of events w/respect to time.
generating Indicates if the command generates new events.
maxinputs Maximum number of events that can be passed to the command for each invocation. This limit cannot exceed the value of maxresultrows in limits.conf.

0 indicates no limit. Defaults to 50000.

outputheader If true, the output of script should be a header section + blank line + csv ouput.

If false, script output should be pure csv only.

passauth If true, passes an authentication token on the start of input.
required_fields A list of fields that this command may use. Informs previous commands that they should retain/extract these fields if possible. No error is generated if a field specified is missing.

Defaults to '*'.

requires_preop Indicates whether the command sequence specified by the streaming_preop key is required for proper execution or is it an optimization only.

Default is false (stremaing_preop not required).

retainsevents Indicates whether the command retains events (the way the sort/dedup/cluster commands do) or whether the command transforms them (the way the stats command does).
streaming Indicates whether the command is streamable.
supports_getinfo Indicates whether the command supports dynamic probing for settings (first argument invoked == __GETINFO__ or __EXECUTE__).
supports_rawargs Indicates whether the command supports raw arguments being passed to it or if it uses parsed arguments (where quotes are stripped).
type Specifies the type of command.

The only valid value for this attribute is python</conde>.

Example

Provides information about the python search command, input. 


curl -k -u admin:pass https://localhost:8089/servicesNS/nobody/search/data/commands/input



<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>commandsconf</title>
  <id>https://localhost:8089/servicesNS/nobody/search/data/commands</id>
  <updated>2011-07-07T00:52:26-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/servicesNS/nobody/search/data/commands/_reload" rel="_reload"/>
  <s:messages/>
  <entry>
    <title>input</title>
    <id>https://localhost:8089/servicesNS/nobody/search/data/commands/input</id>
    <updated>2011-07-07T00:52:26-07:00</updated>
    <link href="/servicesNS/nobody/search/data/commands/input" rel="alternate"/>
    <author>
      <name>nobody</name>
    </author>
    <link href="/servicesNS/nobody/search/data/commands/input" rel="list"/>
    <link href="/servicesNS/nobody/search/data/commands/input/_reload" rel="_reload"/>
    <link href="/servicesNS/nobody/search/data/commands/input/disable" rel="disable"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="changes_colorder">1</s:key>
        <s:key name="disabled">0</s:key>
        <s:key name="eai:appName">search</s:key>
        <s:key name="eai:attributes">
          <s:dict>
            <s:key name="optionalFields">
              <s:list/>
            </s:key>
            <s:key name="requiredFields">
              <s:list/>
            </s:key>
            <s:key name="wildcardFields">
              <s:list/>
            </s:key>
          </s:dict>
        </s:key>
        <s:key name="eai:userName">admin</s:key>
        <s:key name="enableheader">1</s:key>
        <s:key name="filename">input.py</s:key>
        <s:key name="generates_timeorder">0</s:key>
        <s:key name="generating">0</s:key>
        <s:key name="maxinputs">50000</s:key>
        <s:key name="outputheader">0</s:key>
        <s:key name="passauth">1</s:key>
        <s:key name="required_fields">*</s:key>
        <s:key name="requires_preop">0</s:key>
        <s:key name="retainsevents">0</s:key>
        <s:key name="streaming">0</s:key>
        <s:key name="supports_getinfo">0</s:key>
        <s:key name="supports_rawargs">1</s:key>
        <s:key name="type">python</s:key>
      </s:dict>
    </content>
  </entry>
</feed>


saved/searches

Provides access to the configuration of saved searches.

GET saved/searches

Returns information on all saved searches.

Request

Name Type Required Default Description
count Number 30 Indicates the maximum number of entries to return. To return all entries, specify 0.
earliest_time String For scheduled searches display all the scheduled times starting from this time (not just the next run time)
latest_time String For scheduled searches display all the scheduled times until this time (not just the next run time)
offset Number 0 Index for first item to return.
search String Search expression to filter the response. The response matches field values against the search expression. For example:

search=foo matches any object that has "foo" as a substring in a field. search=field_name%3Dfield_value restricts the match to a single field. URI-encoding is required in this example.

sort_dir Enum asc Valid values: (asc | desc)

Indicates whether to sort returned entries in ascending or descending order.

sort_key String name Field to use for sorting.
sort_mode Enum auto Valid values: (auto | alpha | alpha_case | num)

Indicates the collating sequence for sorting the returned entries. auto: If all values of the field are numbers, collate numerically. Otherwise, collate alphabetically. alpha: Collate alphabetically. alpha_case: Collate alphabetically, case-sensitive. num: Collate numerically.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view saved search.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
action.email Indicates the state of the email action.
action.email.reportServerEnabled Indicates whether the PDF server is enabled.
action.email.sendresults Indicates whether search results are attached to the email.
action.email.to List of addresses for email recipients.
action.populate_lookup Indicates the state of the populate lookup action.
action.rss Indicates the state of the RSS action.
action.script Indicates the state of the script action.
action.summary_index Indicates the state of the summary index action.
alert.digest_mode Indicates if Splunk applies the alert actions to the entire result set or on each individual result.
alert.expires Sets the period of time to show the alert in the dashboard. Defaults to 24h.

Uses [number][time-unit] to specify a time. For example: 60 = 60 seconds, 1m = 1 minute, 1h = 60 minutes = 1 hour.

alert.severity The alert severity level.

Valid values are:

1 DEBUG
2 INFO
3 WARN
4 ERROR
5 SEVERE
6 FATAL
alert.suppress Indicates whether alert suppression is enabled for this schedules search.
alert.suppress.period Specifies the suppresion period. Only valid if alert.supress is enabled.

Uses [number][time-unit] to specify a time. For example: 60 = 60 seconds, 1m = 1 minute, 1h = 60 minutes = 1 hour.

alert.track Specifies whether to track the actions triggered by this scheduled search.

auto - determine whether to track or not based on the tracking setting of each action, do not track scheduled searches that always trigger actions.

true - force alert tracking.

false - disable alert tracking for this search.

alert_comparator One of the following strings: greater than, less than, equal to, rises by, drops by, rises by perc, drops by perc
alert_condition A conditional search that is evaluated against the results of the saved search. Defaults to an empty string.

Alerts are triggered if the specified search yields a non-empty search result list.

Note: If you specify an alert_condition, do not set counttype, relation, or quantity.

alert_threshold Valid values are: Integer[%]

Specifies the value to compare (see alert_comparator) before triggering the alert actions. If expressed as a percentage, indicates value to use when alert_comparator is set to "rises by perc" or "drops by perc."

alert_type What to base the alert on, overriden by alert_condition if it is specified.

Valid values are: always, custom, number of events, number of hosts, number of sources

cron_schedule The cron schedule to execute this search.

For more information, refer to the description of this parameter in the POST endpoint.

description Description of the saved search.
disabled Indicates if this saved search is disabled.
dispatch.buckets The maximum nuber of timeline buckets.
dispatch.earliest_time A time string that specifies the earliest time for this search. Can be a relative or absolute time.

If this value is an absolute time, use the dispatch.time_format to format the value.

dispatch.latest_time A time string that specifies the latest time for the saved search. Can be a relative or absolute time.

If this value is an absolute time, use the dispatch.time_format to format the value.

dispatch.lookups Indicates if lookups are enabled for this search.
dispatch.max_count The maximum number of results before finalizing the search.
dispatch.max_time Indicates the maximum amount of time (in seconds) before finalizing the search.
dispatch.reduce_freq Specifies how frequently Splunk should run the MapReduce reduce phase on accumulated map values.
dispatch.spawn_process Specifies whether Splunk spawns a new search process when this saved search is executed.

Searches against indexes must run in a separate process.

dispatch.time_format Time format string that defines the time format that Splunk uses to specify the earliest and latest time.
dispatch.ttl Indicates the time to live (in seconds) for the artifacts of the scheduled search, if no actions are triggered.

If an action is triggered Splunk changes the ttl to that action's ttl. If multiple actions are triggered, Splunk applies the maximum ttl to the artifacts. To set the action's ttl, refer to alert_actions.conf.spec.

If the integer is followed by the letter 'p' Splunk interprets the ttl as a multiple of the scheduled search's period.

displayview Defines the default UI view name (not label) in which to load the results. Accessibility is subject to the user having sufficient permissions.
earliest_time For scheduled searches display all the scheduled times starting from this time (not just the next run time).
is_scheduled Indicates if this search is to be run on a schedule
is_visible Indicates if this saved search appears in the visible saved search list.
latest_time For scheduled searches display all the scheduled times until this time (not just the next run time).
max_concurrent The maximum number of concurrent instances of this search the scheduler is allowed to run.
next_scheduled_time Time when the scheduler runs this search again.
qualifiedSearch The exact search string that the scheduler would run.
realtime_schedule Controls the way the scheduler computes the next execution time of a scheduled search. If this value is set to 1, the scheduler bases its determination of the next scheduled search execution time on the current time.

If this value is set to 0, the scheduler bases its determination of the next scheduled search on the last search execution time. This is called continuous scheduling. If set to 0, the scheduler never skips scheduled execution periods. However, the execution of the saved search might fall behind depending on the scheduler's load. Use continuous scheduling whenever you enable the summary index option.

If set to 1, the scheduler might skip some execution periods to make sure that the scheduler is executing the searches running over the most recent time range.

The scheduler tries to execute searches that have realtime_schedule set to 1 before it executes searches that have continuous scheduling (realtime_schedule = 0).

request.ui_dispatch_app A field used by Splunk UI to denote the app this search should be dispatched in.
request.ui_dispatch_view Specifies a field used by Splunk UI to denote the view this search should be displayed in.
restart_on_searchpeer_add Specifies whether to restart a real-time search managed by the scheduler when a search peer becomes available for this saved search.

Note: The peer can be a newly added peer or a peer that has been down and has become available.

run_on_startup Indicates whether this search runs when Splunk starts. If it does not run on startup, it runs at the next scheduled time.

Splunk recommends that you set run_on_startup to true for scheduled searches that populate lookup tables.

search Search expression to filter the response. The response matches field values against the search expression. For example:

search=foo matches any object that has "foo" as a substring in a field. search=field_name%3Dfield_value restricts the match to a single field. URI-encoding is required in this example.

vsid The viewstate id associated with the UI view listed in 'displayview'.

Matches to a stanza in viewstates.conf.

Example

List all saved searched on this Splunk instance. 


curl -k -u admin:pass https://localhost:8089/services/saved/searches



<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>savedsearch</title>
  <id>https://localhost:8089/services/saved/searches</id>
  <updated>2011-07-13T11:56:35-07:00</updated>
  <generator version="102824"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/saved/searches/_new" rel="create"/>
  <link href="/services/saved/searches/_reload" rel="_reload"/>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
  <entry>
    <title>Errors in the last 24 hours</title>
    <id>https://localhost:8089/servicesNS/nobody/search/saved/searches/Errors%20in%20the%20last%2024%20hours</id>
    <updated>2011-07-13T11:56:35-07:00</updated>
    <link href="/servicesNS/nobody/search/saved/searches/Errors%20in%20the%20last%2024%20hours" rel="alternate"/>
    <author>
      <name>nobody</name>
    </author>
    <link href="/servicesNS/nobody/search/saved/searches/Errors%20in%20the%20last%2024%20hours" rel="list"/>
    <link href="/servicesNS/nobody/search/saved/searches/Errors%20in%20the%20last%2024%20hours/_reload" rel="_reload"/>
    <link href="/servicesNS/nobody/search/saved/searches/Errors%20in%20the%20last%2024%20hours" rel="edit"/>
    <link href="/servicesNS/nobody/search/saved/searches/Errors%20in%20the%20last%2024%20hours/disable" rel="disable"/>
    <link href="/servicesNS/nobody/search/saved/searches/Errors%20in%20the%20last%2024%20hours/dispatch" rel="dispatch"/>
    <link href="/servicesNS/nobody/search/saved/searches/Errors%20in%20the%20last%2024%20hours/history" rel="history"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="action.email">0</s:key>
        <s:key name="action.email.reportServerEnabled">0</s:key>
        <s:key name="action.email.sendresults"/>
        <s:key name="action.email.to"/>
        <s:key name="action.populate_lookup">0</s:key>
        <s:key name="action.rss">0</s:key>
        <s:key name="action.script">0</s:key>
        <s:key name="action.summary_index">0</s:key>
        <s:key name="alert.digest_mode">1</s:key>
        <s:key name="alert.expires">24h</s:key>
        <s:key name="alert.severity">3</s:key>
        <s:key name="alert.suppress"/>
        <s:key name="alert.suppress.period"/>
        <s:key name="alert.track">auto</s:key>
        <s:key name="alert_comparator"/>
        <s:key name="alert_condition"/>
        <s:key name="alert_threshold"/>
        <s:key name="alert_type">always</s:key>
        <s:key name="cron_schedule"/>
        <s:key name="description"/>
        <s:key name="disabled">0</s:key>
        <s:key name="dispatch.buckets">0</s:key>
        <s:key name="dispatch.earliest_time">-1d</s:key>
        <s:key name="dispatch.latest_time"/>
        <s:key name="dispatch.lookups">1</s:key>
        <s:key name="dispatch.max_count">500000</s:key>
        <s:key name="dispatch.max_time">0</s:key>
        <s:key name="dispatch.reduce_freq">10</s:key>
        <s:key name="dispatch.spawn_process">1</s:key>
        <s:key name="dispatch.time_format">%FT%T.%Q%:z</s:key>
        <s:key name="dispatch.ttl">2p</s:key>
        <s:key name="displayview"/>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="is_scheduled">0</s:key>
        <s:key name="is_visible">1</s:key>
        <s:key name="max_concurrent">1</s:key>
        <s:key name="next_scheduled_time"/>
        <s:key name="qualifiedSearch">search  error OR failed OR severe OR ( sourcetype=access_* ( 404 OR 500 OR 503 ) )</s:key>
        <s:key name="realtime_schedule">1</s:key>
        <s:key name="request.ui_dispatch_app"/>
        <s:key name="request.ui_dispatch_view"/>
        <s:key name="restart_on_searchpeer_add">1</s:key>
        <s:key name="run_on_startup">0</s:key>
        <s:key name="search">error OR failed OR severe OR ( sourcetype=access_* ( 404 OR 500 OR 503 ) )</s:key>
        <s:key name="vsid">*:75qh2fwx</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

POST saved/searches

Creates a saved search.

Request

Name Type Required Default Description
name String
✓
 A name for the search.
search String
✓
 The search to save.
action.* String Wildcard argument for any action.

Use this parameter to specify specific action arguments. For example, to specify the email recipients for action.email.to.

action.email Boolean 0 The state of the email action. Read-only attribute. Value ignored on POST. Use actions to specify a list of enabled actions.
action.email.auth_password String The password to use when authenticating with the SMTP server. Normally this value will be set when editing the email settings, however you can set a clear text password here and it will be encrypted on the next Splunk restart.

Defaults to empty string.

action.email.auth_username String The username to use when authenticating with the SMTP server. If this is empty string, no authentication is attempted. Defaults to empty string.

NOTE: Your SMTP server might reject unauthenticated emails.

action.email.bcc String BCC email address to use if action.email is enabled.
action.email.cc String CC email address to use if action.email is enabled.
action.email.command String The search command (or pipeline) which is responsible for executing the action.

Generally the command is a template search pipeline which is realized with values from the saved search. To reference saved search field values wrap them in $, for example to reference the savedsearch name use $name$, to reference the search use $search$.

action.email.format Enum Valid values: (plain | html | raw | csv)

Specify the format of text in the email. plain indicates plain text. This value also applies to any attachments.

action.email.from String Email address from which the email action originates.

Defaults to splunk@$LOCALHOST or whatever value is set in alert_actions.conf.

action.email.hostname String Sets the hostname used in the web link (url) sent in email actions.

This value accepts two forms:

hostname (for example, splunkserver, splunkserver.example.com)

protocol://hostname:port (for example, http://splunkserver:8000, https://splunkserver.example.com:443)

When this value is a simple hostname, the protocol and port which are configured within splunk are used to construct the base of the url.

When this value begins with 'http://', it is used verbatim. NOTE: This means the correct port must be specified if it is not the default port for http or https. This is useful in cases when the Splunk server is not aware of how to construct an externally referencable url, such as SSO environments, other proxies, or when the Splunk server hostname is not generally resolvable.

Defaults to current hostname provided by the operating system, or if that fails "localhost". When set to empty, default behavior is used.

action.email.inline Boolean Indicates whether the search results are contained in the body of the email.

Results can be either inline or attached to an email. See action.email.sendresults.

action.email.mailserver String Set the address of the MTA server to be used to send the emails.

Defaults to <LOCALHOST> (or whatever is set in alert_actions.conf).

action.email.maxresults Number Sets the global maximum number of search results to send when action.email is enabled.

Defaults to 100.

action.email.maxtime Number Valid values are Integer[m|s|h|d].

Specifies the maximum amount of time the execution of an email action takes before the action is aborted. Defaults to 5m.

action.email.pdfview String The name of the view to deliver if sendpdf is enabled
action.email.preprocess_results String Search string to preprocess results before emailing them. Defaults to empty string (no preprocessing).

Usually the preprocessing consists of filtering out unwanted internal fields.

action.email.reportPaperOrientation Enum Valid values: (portrait | landscape)

Specifies the paper orientation: portrait or landscape. Defaults to portrait.

action.email.reportPaperSize Enum Valid values: (letter | legal | ledger | a2 | a3 | a4 | a5)

Specifies the paper size for PDFs. Defaults to letter.

action.email.reportServerEnabled Boolean Indicates whether the PDF server is enabled. Defaults to false.
action.email.reportServerURL String The URL of the PDF report server, if one is set up and available on the network.

For a default locally installed report server, the URL is http://localhost:8091/

action.email.sendpdf Boolean Indicates whether to create and send the results as a PDF. Defaults to false.
action.email.sendresults Boolean Indicates whether to attach the search results in the email.

Results can be either attached or inline. See action.email.inline.

action.email.subject String Specifies an alternate email subject.

Defaults to SplunkAlert-<savedsearchname>.

action.email.to String A comma or semicolon separated list of recipient email addresses. Required if this search is scheduled and the email alert action is enabled.
action.email.track_alert Boolean Indicates whether the execution of this action signifies a trackable alert.
action.email.ttl Number Valid values are Integer[p].

Specifies the minimum time-to-live in seconds of the search artifacts if this action is triggered. If p follows <Integer>, int is the number of scheduled periods. Defaults to 86400 (24 hours).

If no actions are triggered, the artifacts have their ttl determined by dispatch.ttl in savedsearches.conf.

action.email.use_ssl Boolean Indicates whether to use SSL when communicating with the SMTP server.

Defaults to false.

action.email.use_tls Boolean Indicates whether to use TLS (transport layer security) when communicating with the SMTP server (starttls).

Defaults to false.

action.email.width_sort_columns Boolean Indicates whether columns should be sorted from least wide to most wide, left to right.

Only valid if format=plain, indicating plain text.

action.populate_lookup Boolean 0 The state of the populate lookup action. Read-only attribute. Value ignored on POST. Use actions to specify a list of enabled actions.
action.populate_lookup.command String The search command (or pipeline) which is responsible for executing the action.

Generally the command is a template search pipeline which is realized with values from the saved search. To reference saved search field values wrap them in $, for example to reference the savedsearch name use $name$, to reference the search use $search$.

action.populate_lookup.dest String Lookup name of path of the lookup to populate
action.populate_lookup.hostname String Sets the hostname used in the web link (url) sent in alert actions.

This value accepts two forms:

hostname (for example, splunkserver, splunkserver.example.com)

protocol://hostname:port (for example, http://splunkserver:8000, https://splunkserver.example.com:443)

See action.email.hostname for details.

action.populate_lookup.maxresults Number Sets the maximum number of search results sent via alerts. Defaults to 100.
action.populate_lookup.maxtime Number Valid values are: Integer[m|s|h|d]

Sets the maximum amount of time the execution of an action takes before the action is aborted. Defaults to 5m.

action.populate_lookup.track_alert Boolean Indicates whether the execution of this action signifies a trackable alert.
action.populate_lookup.ttl Number Valid values are Integer[p]

Specifies the minimum time-to-live in seconds of the search artifacts if this action is triggered. If p follows Integer, then this specifies the number of scheduled periods. Defaults to 10p.

If no actions are triggered, the artifacts have their ttl determined by dispatch.ttl in savedsearches.conf.

action.rss Boolean 0 The state of the rss action. Read-only attribute. Value ignored on POST. Use actions to specify a list of enabled actions.
action.rss.command String The search command (or pipeline) which is responsible for executing the action.

Generally the command is a template search pipeline which is realized with values from the saved search. To reference saved search field values wrap them in $, for example to reference the savedsearch name use $name$, to reference the search use $search$.

action.rss.hostname String Sets the hostname used in the web link (url) sent in alert actions.

This value accepts two forms:

hostname (for example, splunkserver, splunkserver.example.com)

protocol://hostname:port (for example, http://splunkserver:8000, https://splunkserver.example.com:443)

See action.email.hostname for details.

action.rss.maxresults Number Sets the maximum number of search results sent via alerts. Defaults to 100.
action.rss.maxtime Number Valid values are Integer[m|s|h|d].

Sets the maximum amount of time the execution of an action takes before the action is aborted. Defaults to 1m.

action.rss.track_alert Boolean Indicates whether the execution of this action signifies a trackable alert.
action.rss.ttl Number Valid values are: Integer[p]

Specifies the minimum time-to-live in seconds of the search artifacts if this action is triggered. If p follows Integer, specifies the number of scheduled periods. Defaults to 86400 (24 hours).

If no actions are triggered, the artifacts have their ttl determined by dispatch.ttl in savedsearches.conf.

action.script Boolean 0 The state of the script action. Read-only attribute. Value ignored on POST. Use actions to specify a list of enabled actions.
action.script.command String The search command (or pipeline) which is responsible for executing the action.

Generally the command is a template search pipeline which is realized with values from the saved search. To reference saved search field values wrap them in $, for example to reference the savedsearch name use $name$, to reference the search use $search$.

action.script.filename String File name of the script to call. Required if script action is enabled
action.script.hostname String Sets the hostname used in the web link (url) sent in alert actions.

This value accepts two forms:

hostname (for example, splunkserver, splunkserver.example.com)

protocol://hostname:port (for example, http://splunkserver:8000, https://splunkserver.example.com:443)

See action.email.hostname for details.

action.script.maxresults Number Sets the maximum number of search results sent via alerts. Defaults to 100.
action.script.maxtime Number Valid values are: Integer[m|s|h|d]

Sets the maximum amount of time the execution of an action takes before the action is aborted. Defaults to 5m.

action.script.track_alert Boolean Indicates whether the execution of this action signifies a trackable alert.
action.script.ttl Number Valid values are: Integer[p]

Specifies the minimum time-to-live in seconds of the search artifacts if this action is triggered. If p follows Integer, specifies the number of scheduled periods. Defaults to 600 (10 minutes).

If no actions are triggered, the artifacts have their ttl determined by dispatch.ttl in savedsearches.conf.

action.summary_index Boolean 0 The state of the summary index action. Read-only attribute. Value ignored on POST. Use actions to specify a list of enabled actions.

Defaults to 0

action.summary_index._name String Specifies the name of the summary index where the results of the scheduled search are saved.

Defaults to "summary."

action.summary_index.command String The search command (or pipeline) which is responsible for executing the action.

Generally the command is a template search pipeline which is realized with values from the saved search. To reference saved search field values wrap them in $, for example to reference the savedsearch name use $name$, to reference the search use $search$.

action.summary_index.hostname String Sets the hostname used in the web link (url) sent in alert actions.

This value accepts two forms:

hostname (for example, splunkserver, splunkserver.example.com)

protocol://hostname:port (for example, http://splunkserver:8000, https://splunkserver.example.com:443)

See action.email.hostname for details.

action.summary_index.inline Boolean Determines whether to execute the summary indexing action as part of the scheduled search.

NOTE: This option is considered only if the summary index action is enabled and is always executed (in other words, if <code>counttype = always).

Defaults to true

action.summary_index.maxresults Number Sets the maximum number of search results sent via alerts. Defaults to 100.
action.summary_index.maxtime Number Valid values are: Integer[m|s|h|d]

Sets the maximum amount of time the execution of an action takes before the action is aborted. Defaults to 5m.

action.summary_index.track_alert Boolean Indicates whether the execution of this action signifies a trackable alert.
action.summary_index.ttl Number Valid values are: Integer[p]

Specifies the minimum time-to-live in seconds of the search artifacts if this action is triggered. If p follows Integer, specifies the number of scheduled periods. Defaults to 10p.

If no actions are triggered, the artifacts have their ttl determined by dispatch.ttl in savedsearches.conf.

actions String A comma-separated list of actions to enable.

For example: rss,email

alert.digest_mode Boolean 1 Specifies whether Splunk applies the alert actions to the entire result set or on each individual result.

Defaults to true.

alert.expires Number 24h Valid values: [number][time-unit]

Sets the period of time to show the alert in the dashboard. Defaults to 24h.

Use [number][time-unit] to specify a time. For example: 60 = 60 seconds, 1m = 1 minute, 1h = 60 minutes = 1 hour.

alert.severity Enum 3 Valid values: (1 | 2 | 3 | 4 | 5 | 6)

Sets the alert severity level.

Valid values are:

1 DEBUG 2 INFO 3 WARN 4 ERROR 5 SEVERE 6 FATAL

alert.suppress Boolean Indicates whether alert suppression is enabled for this scheduled search.
alert.suppress.fields String Comma delimited list of fields to use for suppression when doing per result alerting. Required if suppression is turned on and per result alerting is enabled.
alert.suppress.period Number Valid values: [number][time-unit]

Specifies the suppresion period. Only valid if alert.supress is enabled.

Use [number][time-unit] to specify a time. For example: 60 = 60 seconds, 1m = 1 minute, 1h = 60 minutes = 1 hour.

alert.track Enum auto Valid values: (true | false | auto)

Specifies whether to track the actions triggered by this scheduled search.

auto - determine whether to track or not based on the tracking setting of each action, do not track scheduled searches that always trigger actions.

true - force alert tracking.

false - disable alert tracking for this search.

alert_comparator String One of the following strings: greater than, less than, equal to, rises by, drops by, rises by perc, drops by perc

Used with alert_threshold to trigger alert actions.

alert_condition String Contains a conditional search that is evaluated against the results of the saved search. Defaults to an empty string.

Alerts are triggered if the specified search yields a non-empty search result list.

NOTE: If you specify an alert_condition, do not set counttype, relation, or quantity.

alert_threshold Number Valid values are: Integer[%]

Specifies the value to compare (see alert_comparator) before triggering the alert actions. If expressed as a percentage, indicates value to use when alert_comparator is set to "rises by perc" or "drops by perc."

alert_type String What to base the alert on, overriden by alert_condition if it is specified. Valid values are: always, custom, number of events, number of hosts, number of sources
args.* String Wildcard argument that accepts any saved search template argument, such as args.username=foobar when the search is search $username$.
cron_schedule String Valid values: cron string

The cron schedule to execute this search. For example: */5 * * * * causes the search to execute every 5 minutes.

cron lets you use standard cron notation to define your scheduled search interval. In particular, cron can accept this type of notation: 00,20,40 * * * *, which runs the search every hour at hh:00, hh:20, hh:40. Along the same lines, a cron of 03,23,43 * * * * runs the search every hour at hh:03, hh:23, hh:43.

Splunk recommends that you schedule your searches so that they are staggered over time. This reduces system load. Running all of them every 20 minutes (*/20) means they would all launch at hh:00 (20, 40) and might slow your system every 20 minutes.

description String Human-readable description of this saved search. Defaults to empty string.
disabled Boolean 0 Indicates if the saved search is enabled.

Disabled saved searches are not visible in Splunk Web.

dispatch.* String Wildcard argument that accepts any dispatch related argument.
dispatch.buckets Number 0 The maximum number of timeline buckets.
dispatch.earliest_time String A time string that specifies the earliest time for this search. Can be a relative or absolute time.

If this value is an absolute time, use the dispatch.time_format to format the value.

dispatch.latest_time String A time string that specifies the latest time for this saved search. Can be a relative or absolute time.

If this value is an absolute time, use the dispatch.time_format to format the value.

dispatch.lookups Boolean 1 Enables or disables the lookups for this search.
dispatch.max_count Number 500000 The maximum number of results before finalizing the search.
dispatch.max_time Number 0 Indicates the maximum amount of time (in seconds) before finalizing the search.
dispatch.reduce_freq Number 10 Specifies, in seconds, how frequently Splunk should run the MapReduce reduce phase on accumulated map values.
dispatch.rt_backfill Boolean 0 Whether to back fill the real time window for this search. Parameter valid only if this is a real time search
dispatch.spawn_process Boolean 1 Specifies whether Splunk spawns a new search process when this saved search is executed.

Searches against indexes must run in a separate process.

dispatch.time_format String  %FT%T.%Q%:z A time format string that defines the time format that Splunk uses to specify the earliest and latest time.
dispatch.ttl Number 2p Valid values: Integer[p]

Indicates the time to live (in seconds) for the artifacts of the scheduled search, if no actions are triggered.

If an action is triggered Splunk changes the ttl to that action's ttl. If multiple actions are triggered, Splunk applies the maximum ttl to the artifacts. To set the action's ttl, refer to alert_actions.conf.spec.

If the integer is followed by the letter 'p' Splunk interprets the ttl as a multiple of the scheduled search's period.

displayview String Defines the default UI view name (not label) in which to load the results. Accessibility is subject to the user having sufficient permissions.
is_scheduled Boolean Whether this search is to be run on a schedule
is_visible Boolean 1 Specifies whether this saved search should be listed in the visible saved search list.
max_concurrent Number 1 The maximum number of concurrent instances of this search the scheduler is allowed to run.
next_scheduled_time String Read-only attribute. Value ignored on POST. There are some old clients who still send this value
qualifiedSearch String Read-only attribute. Value ignored on POST. Splunk computes this value during runtime.
realtime_schedule Boolean 1 Controls the way the scheduler computes the next execution time of a scheduled search. If this value is set to 1, the scheduler bases its determination of the next scheduled search execution time on the current time.

If this value is set to 0, the scheduler bases its determination of the next scheduled search on the last search execution time. This is called continuous scheduling. If set to 0, the scheduler never skips scheduled execution periods. However, the execution of the saved search might fall behind depending on the scheduler's load. Use continuous scheduling whenever you enable the summary index option.

If set to 1, the scheduler might skip some execution periods to make sure that the scheduler is executing the searches running over the most recent time range.

The scheduler tries to execute searches that have realtime_schedule set to 1 before it executes searches that have continuous scheduling (realtime_schedule = 0).

request.ui_dispatch_app String Specifies a field used by Splunk UI to denote the app this search should be dispatched in.
request.ui_dispatch_view String Specifies a field used by Splunk UI to denote the view this search should be displayed in.
restart_on_searchpeer_add Boolean 1 Specifies whether to restart a real-time search managed by the scheduler when a search peer becomes available for this saved search.

NOTE: The peer can be a newly added peer or a peer that has been down and has become available.

run_on_startup Boolean 0 Indicates whether this search runs when Splunk starts. If it does not run on startup, it runs at the next scheduled time.

Splunk recommends that you set run_on_startup to true for scheduled searches that populate lookup tables.

vsid String Defines the viewstate id associated with the UI view listed in 'displayview'.

Must match up to a stanza in viewstates.conf.

Response Codes

Status Code Description
201 Created successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
402 The Splunk license in use has disabled this feature.
403 Insufficient permissions to create saved search.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.
503 This feature has been disabled in Splunk configuration files.

Returned Values

Attribute Description
action.email Indicates the state of the email action.
action.email.auth_password The password to use when authenticating with the SMTP server. Normally this value will be set when editing the email settings, however you can set a clear text password here and it will be encrypted on the next Splunk restart.

Defaults to empty string.

action.email.auth_username The username to use when authenticating with the SMTP server. If this is empty string, no authentication is attempted. Defaults to empty string.

Note: Your SMTP server might reject unauthenticated emails.

action.email.bcc BCC email address to use if action.email is enabled.
action.email.cc CC email address to use if action.email is enabled.
action.email.command The search command (or pipeline) which is responsible for executing the action.

Generally the command is a template search pipeline which is realized with values from the saved search. To reference saved search field values wrap them in $, for example to reference the savedsearch name use $name$, to reference the search use $search$.

action.email.format Specify the format of text in the email. This value also applies to any attachments.<

Valid values: (plain | html | raw | csv)

plain indicates plain text.

action.email.from Email address from which the email action originates.

Defaults to splunk@$LOCALHOST or whatever value is set in alert_actions.conf.

action.email.hostname Sets the hostname used in the web link (url) sent in email actions.

This value accepts two forms:

hostname (for example, splunkserver, splunkserver.example.com)

protocol://hostname:port (for example, http://splunkserver:8000, https://splunkserver.example.com:443)

When this value is a simple hostname, the protocol and port which are configured within splunk are used to construct the base of the url.

When this value begins with 'http://', it is used verbatim. NOTE: This means the correct port must be specified if it is not the default port for http or https. This is useful in cases when the Splunk server is not aware of how to construct an externally referencable url, such as SSO environments, other proxies, or when the Splunk server hostname is not generally resolvable.

Defaults to current hostname provided by the operating system, or if that fails "localhost". When set to empty, default behavior is used.

action.email.inline Indicates whether the search results are contained in the body of the email.

Results can be either inline or attached to an email. See action.email.sendresults.

action.email.mailserver Set the address of the MTA server to be used to send the emails.

Defaults to <LOCALHOST> (or whatever is set in alert_actions.conf).

action.email.maxresults Sets the global maximum number of search results to send when action.email is enabled.
action.email.maxtime Specifies the maximum amount of time the execution of an email action takes before the action is aborted.
action.email.pdfview The name of the view to deliver if sendpdf is enabled
action.email.preprocess_results Search string to preprocess results before emailing them. Defaults to empty string (no preprocessing).

Usually the preprocessing consists of filtering out unwanted internal fields.

action.email.reportPaperOrientation Specifies the paper orientation: portrait or landscape.
action.email.reportPaperSize Specifies the paper size for PDFs. Defaults to letter.

Valid values: (letter | legal | ledger | a2 | a3 | a4 | a5)

action.email.reportServerEnabled Indicates whether the PDF server is enabled.
action.email.reportServerURL The URL of the PDF report server, if one is set up and available on the network.

For a default locally installed report server, the URL is http://localhost:8091/

action.email.sendpdf Indicates whether to create and send the results as a PDF.
action.email.sendresults Indicates whether to attach the search results in the email.

Results can be either attached or inline. See action.email.inline.

action.email.subject Specifies an email subject.

Defaults to SplunkAlert-<savedsearchname>.

action.email.to List of recipient email addresses. Required if this search is scheduled and the email alert action is enabled.
action.email.track_alert Indicates whether the execution of this action signifies a trackable alert.
action.email.ttl Specifies the minimum time-to-live in seconds of the search artifacts if this action is triggered. If p follows <Integer>, int is the number of scheduled periods. Defaults to 86400 (24 hours).

If no actions are triggered, the artifacts have their ttl determined by dispatch.ttl in savedsearches.conf.

Valid values are Integer[p].

action.email.use_ssl Indicates whether to use SSL when communicating with the SMTP server.
action.email.use_tls Indicates whether to use TLS (transport layer security) when communicating with the SMTP server (starttls).
action.email.width_sort_columns Indicates whether columns should be sorted from least wide to most wide, left to right.

Only valid if format=plain, indicating plain text.

action.populate_lookup Indicates the state of the populate lookup action.
action.populate_lookup.command The search command (or pipeline) which is responsible for executing the action.

Generally the command is a template search pipeline which is realized with values from the saved search. To reference saved search field values wrap them in $, for example to reference the savedsearch name use $name$, to reference the search use $search$.

action.populate_lookup.dest Lookup name of path of the lookup to populate.
action.populate_lookup.hostname Sets the hostname used in the web link (url) sent in alert actions.

This value accepts two forms:

hostname (for example, splunkserver, splunkserver.example.com)

protocol://hostname:port (for example, http://splunkserver:8000, https://splunkserver.example.com:443)

See action.email.hostname for details.

action.populate_lookup.maxresults The maximum number of search results sent via alerts.
action.populate_lookup.maxtime Sets the maximum amount of time the execution of an action takes before the action is aborted. Defaults to 5m.

Valid values are: Integer[m|s|h|d]

action.populate_lookup.track_alert Indicates whether the execution of this action signifies a trackable alert.
action.populate_lookup.ttl Specifies the minimum time-to-live in seconds of the search artifacts if this action is triggered. If p follows Integer, then this specifies the number of scheduled periods. Defaults to 10p.

If no actions are triggered, the artifacts have their ttl determined by dispatch.ttl in savedsearches.conf.

Valid values are Integer[p]

action.rss Indicates the state of the RSS action.
action.rss.command The search command (or pipeline) which is responsible for executing the action.

Generally the command is a template search pipeline which is realized with values from the saved search. To reference saved search field values wrap them in $, for example to reference the savedsearch name use $name$, to reference the search use $search$.

action.rss.hostname Sets the hostname used in the web link (url) sent in alert actions.

This value accepts two forms:

hostname (for example, splunkserver, splunkserver.example.com)

protocol://hostname:port (for example, http://splunkserver:8000, https://splunkserver.example.com:443)

See action.email.hostname for details.

action.rss.maxresults Sets the maximum number of search results sent using alerts.
action.rss.maxtime Sets the maximum amount of time the execution of an action takes before the action is aborted.

Valid values are Integer[m |s |h |d].

action.rss.track_alert Indicates whether the execution of this action signifies a trackable alert.
action.rss.ttl Specifies the minimum time-to-live in seconds of the search artifacts if this action is triggered. If p follows Integer, specifies the number of scheduled periods. Defaults to 86400 (24 hours).

If no actions are triggered, the artifacts have their ttl determined by dispatch.ttl in savedsearches.conf.

Valid values are: Integer[p]

action.script Indicates the state of the script for this action.
action.script.command The search command (or pipeline) which is responsible for executing the action.

Generally the command is a template search pipeline which is realized with values from the saved search. To reference saved search field values wrap them in $, for example to reference the savedsearch name use $name$, to reference the search use $search$.

action.script.filename File name of the script to call. Required if script action is enabled
action.script.hostname Sets the hostname used in the web link (url) sent in alert actions.

This value accepts two forms:

hostname (for example, splunkserver, splunkserver.example.com)

protocol://hostname:port (for example, http://splunkserver:8000, https://splunkserver.example.com:443)

See action.email.hostname for details.

action.script.maxresults Sets the maximum number of search results sent via alerts.
action.script.maxtime Sets the maximum amount of time the execution of an action takes before the action is aborted.
action.script.track_alert Indicates whether the execution of this action signifies a trackable alert.
action.script.ttl Specifies the minimum time-to-live in seconds of the search artifacts if this action is triggered. If p follows Integer, specifies the number of scheduled periods. Defaults to 600 (10 minutes).

If no actions are triggered, the artifacts have their ttl determined by dispatch.ttl in savedsearches.conf.

Valid values are: Integer[p]

action.summary_index Indicates the state of the summary index.
action.summary_index._name Specifies the name of the summary index where the results of the scheduled search are saved.

Defaults to "summary."

action.summary_index.command The search command (or pipeline) which is responsible for executing the action.

Generally the command is a template search pipeline which is realized with values from the saved search. To reference saved search field values wrap them in $, for example to reference the savedsearch name use $name$, to reference the search use $search$.

action.summary_index.hostname Sets the hostname used in the web link (url) sent in alert actions.

This value accepts two forms:

hostname (for example, splunkserver, splunkserver.example.com)

protocol://hostname:port (for example, http://splunkserver:8000, https://splunkserver.example.com:443)

See action.email.hostname for details.

action.summary_index.inline Determines whether to execute the summary indexing action as part of the scheduled search.

Note: This option is considered only if the summary index action is enabled and is always executed (in other words, if counttype = always).

action.summary_index.maxresults Sets the maximum number of search results sent via alerts.
action.summary_index.maxtime Sets the maximum amount of time the execution of an action takes before the action is aborted. Defaults to 5m.

Valid values are: Integer[m|s|h|d]

action.summary_index.track_alert Indicates whether the execution of this action signifies a trackable alert.
action.summary_index.ttl Specifies the minimum time-to-live in seconds of the search artifacts if this action is triggered. If p follows Integer, specifies the number of scheduled periods. Defaults to 10p.

If no actions are triggered, the artifacts have their ttl determined by dispatch.ttl in savedsearches.conf.

Valid values are: Integer[p]

actions Actions triggerd by this alert.
alert.digest_mode Indicates if Splunk applies the alert actions to the entire result set or on each individual result.
alert.expires Sets the period of time to show the alert in the dashboard. Defaults to 24h.

Use [number][time-unit] to specify a time. For example: 60 = 60 seconds, 1m = 1 minute, 1h = 60 minutes = 1 hour.

Valid values: [number][time-unit]

alert.severity Valid values: (1 | 2 | 3 | 4 | 5 | 6)

Sets the alert severity level.

Valid values are:

1 DEBUG
2 INFO
3 WARN
4 ERROR
5 SEVERE
6 FATAL
alert.suppress Indicates whether alert suppression is enabled for this schedules search.
alert.suppress.fields Fields to use for suppression when doing per result alerting. Required if suppression is turned on and per result alerting is enabled.
alert.suppress.period Specifies the suppresion period. Only valid if alert.supress is enabled.

Uses [number][time-unit] to specify a time. For example: 60 = 60 seconds, 1m = 1 minute, 1h = 60 minutes = 1 hour.

alert.track Specifies whether to track the actions triggered by this scheduled search.

auto - determine whether to track or not based on the tracking setting of each action, do not track scheduled searches that always trigger actions.

true - force alert tracking.

false - disable alert tracking for this search.

alert_comparator One of the following strings: greater than, less than, equal to, rises by, drops by, rises by perc, drops by perc
alert_condition A conditional search that is evaluated against the results of the saved search. Defaults to an empty string.

Alerts are triggered if the specified search yields a non-empty search result list.

Note: If you specify an alert_condition, do not set counttype, relation, or quantity.

alert_threshold Valid values are: Integer[%]

Specifies the value to compare (see alert_comparator) before triggering the alert actions. If expressed as a percentage, indicates value to use when alert_comparator is set to "rises by perc" or "drops by perc."

alert_type What to base the alert on, overriden by alert_condition if it is specified. Valid values are: always, custom, number of events, number of hosts, number of sources
args.* Wildcard argument that accepts any saved search template argument, such as args.username=foobar when the search is search $username$.
cron_schedule The cron schedule to execute this search. For example: */5 * * * * causes the search to execute every 5 minutes.

cron lets you use standard cron notation to define your scheduled search interval. In particular, cron can accept this type of notation: 00,20,40 * * * *, which runs the search every hour at hh:00, hh:20, hh:40. Along the same lines, a cron of 03,23,43 * * * * runs the search every hour at hh:03, hh:23, hh:43.

Splunk recommends that you schedule your searches so that they are staggered over time. This reduces system load. Running all of them every 20 minutes (*/20) means they would all launch at hh:00 (20, 40) and might slow your system every 20 minutes.

Valid values: cron string

description Description of this saved search. Defaults to empty string.
disabled Indicates if this saved search is disabled.
dispatch.buckets The maximum nuber of timeline buckets.
dispatch.earliest_time A time string that specifies the earliest time for this search. Can be a relative or absolute time.

If this value is an absolute time, use the dispatch.time_format to format the value.

dispatch.latest_time A time string that specifies the latest time for the aved search. Can be a relative or absolute time.

If this value is an absolute time, use the dispatch.time_format to format the value.

dispatch.lookups Indicates if lookups are enabled for this search.
dispatch.max_count The maximum number of results before finalizing the search.
dispatch.max_time Indicates the maximum amount of time (in seconds) before finalizing the search.
dispatch.reduce_freq Specifies how frequently Splunk should run the MapReduce reduce phase on accumulated map values.
dispatch.rt_backfill Indicates whether to back fill the real time window for this search. Parameter valid only if this is a real time search
dispatch.spawn_process Indicates whether Splunk spawns a new search process when this saved search is executed.
dispatch.time_format Time format string that defines the time format that Splunk uses to specify the earliest and latest time.
dispatch.ttl Indicates the time to live (in seconds) for the artifacts of the scheduled search, if no actions are triggered.

If an action is triggered Splunk changes the ttl to that action's ttl. If multiple actions are triggered, Splunk applies the maximum ttl to the artifacts. To set the action's ttl, refer to alert_actions.conf.spec.

If the integer is followed by the letter 'p' Splunk interprets the ttl as a multiple of the scheduled search's period.

displayview Defines the default UI view name (not label) in which to load the results. Accessibility is subject to the user having sufficient permissions.
is_scheduled Indicates if this search is to be run on a schedule.
is_visible Indicates if this saved search appears in the visible saved search list.
max_concurrent The maximum number of concurrent instances of this search the scheduler is allowed to run.
next_scheduled_time The time when the scheduler runs this search again.
qualifiedSearch The exact search string that the scheduler would run.
realtime_schedule Controls the way the scheduler computes the next execution time of a scheduled search. If this value is set to 1, the scheduler bases its determination of the next scheduled search execution time on the current time.

If this value is set to 0, the scheduler bases its determination of the next scheduled search on the last search execution time. This is called continuous scheduling. If set to 0, the scheduler never skips scheduled execution periods. However, the execution of the saved search might fall behind depending on the scheduler's load. Use continuous scheduling whenever you enable the summary index option.

If set to 1, the scheduler might skip some execution periods to make sure that the scheduler is executing the searches running over the most recent time range.

The scheduler tries to execute searches that have realtime_schedule set to 1 before it executes searches that have continuous scheduling (realtime_schedule = 0).

request.ui_dispatch_app A field used by Splunk UI to denote the app this search should be dispatched in.
request.ui_dispatch_view Specifies a field used by Splunk UI to denote the view this search should be displayed in.
restart_on_searchpeer_add Indicates whether to restart a real-time search managed by the scheduler when a search peer becomes available for this saved search.

Note: The peer can be a newly added peer or a peer that has been down and has become available.

run_on_startup Indicates whether this search runs when Splunk starts. If it does not run on startup, it runs at the next scheduled time.

Splunk recommends that you set run_on_startup to true for scheduled searches that populate lookup tables.

search Search expression to filter the response. The response matches field values against the search expression. For example:

search=foo matches any object that has "foo" as a substring in a field. search=field_name%3Dfield_value restricts the match to a single field. URI-encoding is required in this example.

vsid The viewstate id associated with the UI view listed in 'displayview'.

Matches to a stanza in viewstates.conf.

Example

Creates a search, MySavedSearch.

URI-encode the search string if it contains any of the following characters: =, &, ?, %

Otherwise, these characters are interpreted as part of the HTTP request. 


curl -k -u admin:pass https://localhost:8089/servicesNS/admin/search/saved/searches \
	-d name=MySavedSearch \
	--data-urlencode search="index=_internal source=*metrics.log"



<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:s="http://dev.splunk.com/ns/rest"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>savedsearch</title>
  <id>https://localhost:8089/servicesNS/admin/search/saved/searches</id>
  <updated>2011-12-09T09:10:21-08:00</updated>
  <generator version="108769"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/servicesNS/admin/search/saved/searches/_new" rel="create"/>
  <link href="/servicesNS/admin/search/saved/searches/_reload" rel="_reload"/>
  <opensearch:totalResults>1</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
  <entry>
    <title>MySavedSearch</title>
    <id>https://localhost:8089/servicesNS/admin/search/saved/searches/MySavedSearch</id>
    <updated>2011-12-09T09:10:21-08:00</updated>
    <link href="/servicesNS/admin/search/saved/searches/MySavedSearch" rel="alternate"/>
    <author>
      <name>admin</name>
    </author>
    <!-- opensearch nodes elided for brevity. -->
    <content type="text/xml">
      <s:dict>
        <s:key name="action.email">0</s:key>
        <s:key name="action.email.auth_password">$1$o2rN8S6m+0YB</s:key>
        <s:key name="action.email.auth_username">vgenovese</s:key>
        <s:key name="action.email.bcc"></s:key>
        <s:key name="action.email.cc"></s:key>
        <s:key name="action.email.command"><![CDATA[$action.email.preprocess_results{default=""}$
          | sendemail "server=$action.email.mailserver{default=localhost}$"
          "use_ssl=$action.email.use_ssl{default=false}$"
          "use_tls=$action.email.use_tls{default=false}$" "to=$action.email.to$"
          "cc=$action.email.cc$" "bcc=$action.email.bcc$" "from=$action.email.from{default=splunk@localhost}$"
          "subject=$action.email.subject{recurse=yes}$" "format=$action.email.format{default=csv}$"
          "sssummary=Saved Search [$name$]: $counttype$($results.count$)" "sslink=$results.url$"
          "ssquery=$search$" "ssname=$name$" "inline=$action.email.inline{default=False}$"
          "sendresults=$action.email.sendresults{default=False}$" "sendpdf=$action.email.sendpdf{default=False}$"
          "pdfview=$action.email.pdfview$" "searchid=$search_id$" "graceful=$graceful{default=True}$"
          maxinputs="$action.email.maxresults{default=10000}$" maxtime="$action.email.maxtime{default=5m}$"]]>
        </s:key>
        <s:key name="action.email.format">html</s:key>
        <s:key name="action.email.from">splunk</s:key>
        <s:key name="action.email.hostname"></s:key>
        <s:key name="action.email.inline">0</s:key>
        <s:key name="action.email.mailserver">localhost</s:key>
        <s:key name="action.email.maxresults">10000</s:key>
        <s:key name="action.email.maxtime">5m</s:key>
        <s:key name="action.email.pdfview"></s:key>
        <s:key name="action.email.preprocess_results"></s:key>
        <s:key name="action.email.reportPaperOrientation">portrait</s:key>
        <s:key name="action.email.reportPaperSize">letter</s:key>
        <s:key name="action.email.reportServerEnabled">1</s:key>
        <s:key name="action.email.reportServerURL"></s:key>
        <s:key name="action.email.sendpdf">0</s:key>
        <s:key name="action.email.sendresults">0</s:key>
        <s:key name="action.email.subject">Splunk Alert: $name$</s:key>
        <s:key name="action.email.to"></s:key>
        <s:key name="action.email.track_alert">1</s:key>
        <s:key name="action.email.ttl">86400</s:key>
        <s:key name="action.email.use_ssl">0</s:key>
        <s:key name="action.email.use_tls">0</s:key>
        <s:key name="action.populate_lookup">0</s:key>
        <s:key name="action.populate_lookup.command">copyresults dest="$action.populate_lookup.dest$"  sid="$search_id$"</s:key>
        <s:key name="action.populate_lookup.dest"></s:key>
        <s:key name="action.populate_lookup.hostname"></s:key>
        <s:key name="action.populate_lookup.maxresults">10000</s:key>
        <s:key name="action.populate_lookup.maxtime">5m</s:key>
        <s:key name="action.populate_lookup.track_alert">0</s:key>
        <s:key name="action.populate_lookup.ttl">120</s:key>
        <s:key name="action.rss">0</s:key>
        <s:key name="action.rss.command">createrss "path=$name$.xml" "name=$name$" "link=$results.url$" "descr=Alert trigger:
          $name$, results.count=$results.count$ " "count=30" "graceful=$graceful{default=1}$" maxtime="$action.rss.maxtime{default=1m}$"
        </s:key>
        <s:key name="action.rss.hostname"></s:key>
        <s:key name="action.rss.maxresults">10000</s:key>
        <s:key name="action.rss.maxtime">1m</s:key>
        <s:key name="action.rss.track_alert">0</s:key>
        <s:key name="action.rss.ttl">86400</s:key>
        <s:key name="action.script">0</s:key>
        <s:key name="action.script.command">runshellscript "$action.script.filename$" "$results.count$" "$search$" "$search$" "$name$"
          "Saved Search [$name$] $counttype$($results.count$)" "$results.url$" "$deprecated_arg$" "$search_id$" "$results.file$"
          maxtime="$action.script.maxtime{default=5m}$"
        </s:key>
        <s:key name="action.script.filename"></s:key>
        <s:key name="action.script.hostname"></s:key>
        <s:key name="action.script.maxresults">10000</s:key>
        <s:key name="action.script.maxtime">5m</s:key>
        <s:key name="action.script.track_alert">1</s:key>
        <s:key name="action.script.ttl">600</s:key>
        <s:key name="action.summary_index">0</s:key>
        <s:key name="action.summary_index._name">summary</s:key>
        <s:key name="action.summary_index.command"><![CDATA[summaryindex spool=t uselb=t addtime=t index="$action.summary_index._name{required=yes}$"
          file="$name$_$#random$.stash_new" name="$name$" marker="$action.summary_index*{format=$KEY=\\\"$VAL\\\",
          key_regex="action.summary_index.(?!(?:command|inline|maxresults|maxtime|ttl|track_alert|(?:_.*))$)(.*)"}$"]]>
        </s:key>
        <s:key name="action.summary_index.hostname"></s:key>
        <s:key name="action.summary_index.inline">1</s:key>
        <s:key name="action.summary_index.maxresults">10000</s:key>
        <s:key name="action.summary_index.maxtime">5m</s:key>
        <s:key name="action.summary_index.track_alert">0</s:key>
        <s:key name="action.summary_index.ttl">120</s:key>
        <s:key name="alert.digest_mode">1</s:key>
        <s:key name="alert.expires">24h</s:key>
        <s:key name="alert.severity">3</s:key>
        <s:key name="alert.suppress"></s:key>
        <s:key name="alert.suppress.fields"></s:key>
        <s:key name="alert.suppress.period"></s:key>
        <s:key name="alert.track">auto</s:key>
        <s:key name="alert_comparator"></s:key>
        <s:key name="alert_condition"></s:key>
        <s:key name="alert_threshold"></s:key>
        <s:key name="alert_type">always</s:key>
        <s:key name="cron_schedule"></s:key>
        <s:key name="description"></s:key>
        <s:key name="disabled">0</s:key>
        <s:key name="dispatch.buckets">0</s:key>
        <s:key name="dispatch.earliest_time"></s:key>
        <s:key name="dispatch.latest_time"></s:key>
        <s:key name="dispatch.lookups">1</s:key>
        <s:key name="dispatch.max_count">500000</s:key>
        <s:key name="dispatch.max_time">0</s:key>
        <s:key name="dispatch.reduce_freq">10</s:key>
        <s:key name="dispatch.rt_backfill">0</s:key>
        <s:key name="dispatch.spawn_process">1</s:key>
        <s:key name="dispatch.time_format">%FT%T.%Q%:z</s:key>
        <s:key name="dispatch.ttl">2p</s:key>
        <s:key name="displayview"></s:key>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="is_scheduled">0</s:key>
        <s:key name="is_visible">1</s:key>
        <s:key name="max_concurrent">1</s:key>
        <s:key name="next_scheduled_time"></s:key>
        <s:key name="qualifiedSearch">search  index=_internal source=*metrics.log</s:key>
        <s:key name="realtime_schedule">1</s:key>
        <s:key name="request.ui_dispatch_app"></s:key>
        <s:key name="request.ui_dispatch_view"></s:key>
        <s:key name="restart_on_searchpeer_add">1</s:key>
        <s:key name="run_on_startup">0</s:key>
        <s:key name="search">index=_internal source=*metrics.log</s:key>
        <s:key name="vsid"></s:key>
      </s:dict>
    </content>
  </entry>
</feed>

saved/searches/{name}

DELETE saved/searches/{name}

Deletes this saved search.

Request

No parameters for this request.

Response Codes

Status Code Description
200 Deleted successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to delete saved search.
404 Saved search does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

No values returned for this request.

Example

Deletes the saved search, MySavedSearch. 


curl -k -u admin:pass --request DELETE \
	https://localhost:8089/servicesNS/admin/search/saved/searches/MySavedSearch



<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>savedsearch</title>
  <id>https://localhost:8089/servicesNS/admin/search/saved/searches</id>
  <updated>2011-07-13T12:09:05-07:00</updated>
  <generator version="102824"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/servicesNS/admin/search/saved/searches/_new" rel="create"/>
  <link href="/servicesNS/admin/search/saved/searches/_reload" rel="_reload"/>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
</feed>

GET saved/searches/{name}

Returns information on this saved search.

Request

Name Type Required Default Description
earliest_time String If the search is scheduled display scheduled times starting from this time
latest_time String If the search is scheduled display scheduled times ending at this time

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view saved search.
404 Saved search does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
action.email Indicates the state of the email action.
action.email.auth_password The password to use when authenticating with the SMTP server. Normally this value will be set when editing the email settings, however you can set a clear text password here that is encrypted on the next Splunk restart.

Defaults to empty string.

action.email.auth_username The username to use when authenticating with the SMTP server. If this is empty string, no authentication is attempted. Defaults to empty string.

Note: Your SMTP server might reject unauthenticated emails.

action.email.bcc BCC email address to use if action.email is enabled.
action.email.cc CC email address to use if action.email is enabled.
action.email.command The search command (or pipeline) which is responsible for executing the action.

Generally the command is a template search pipeline which is realized with values from the saved search. To reference saved search field values wrap them in $, for example to reference the savedsearch name use $name$, to reference the search use $search$.

action.email.format Specify the format of text in the email. This value also applies to any attachments.

Valid values: (plain | html | raw | csv)

plain indicates plain text.

action.email.from Email address from which the email action originates.
action.email.hostname Sets the hostname used in the web link (url) sent in email actions.

This value accepts two forms:

hostname (for example, splunkserver, splunkserver.example.com)

protocol://hostname:port (for example, http://splunkserver:8000, https://splunkserver.example.com:443)

When this value is a simple hostname, the protocol and port which are configured within splunk are used to construct the base of the url.

When this value begins with 'http://', it is used verbatim. Note: This means the correct port must be specified if it is not the default port for http or https. This is useful in cases when the Splunk server is not aware of how to construct an externally referencable url, such as SSO environments, other proxies, or when the Splunk server hostname is not generally resolvable.

Defaults to current hostname provided by the operating system, or if that fails "localhost." When set to empty, default behavior is used.

action.email.inline Indicates whether the search results are contained in the body of the email.

Results can be either inline or attached to an email. See action.email.sendresults.

action.email.mailserver Set the address of the MTA server to be used to send the emails.

Defaults to <LOCALHOST> (or whatever is set in alert_actions.conf).

action.email.maxresults Sets the global maximum number of search results to send when action.email is enabled.
action.email.maxtime Specifies the maximum amount of time the execution of an email action takes before the action is aborted.
action.email.preprocess_results Search string to preprocess results before emailing them. Defaults to empty string (no preprocessing).

Usually the preprocessing consists of filtering out unwanted internal fields.

action.email.reportPaperOrientation Specifies the paper orientation: portrait or landscape.
action.email.reportPaperSize Specifies the paper size for PDFs. Defaults to letter.

Valid values: (letter | legal | ledger | a2 | a3 | a4 | a5)

action.email.reportServerEnabled Indicates whether the PDF server is enabled.
action.email.reportServerURL The URL of the PDF report server, if one is set up and available on the network.

For a default locally installed report server, the URL is http://localhost:8091/

action.email.sendpdf Indicates whether to create and send the results as a PDF.
action.email.sendresults Indicates whether to attach the search results in the email.

Results can be either attached or inline. See action.email.inline.

action.email.subject Specifies an email subject.

Defaults to SplunkAlert-<savedsearchname>.

action.email.to List of recipient email addresses. Required if this search is scheduled and the email alert action is enabled.
action.email.track_alert Indicates whether the execution of this action signifies a trackable alert.
action.email.ttl Specifies the minimum time-to-live in seconds of the search artifacts if this action is triggered. If p follows <Integer>, int is the number of scheduled periods. Defaults to 86400 (24 hours).

If no actions are triggered, the artifacts have their ttl determined by dispatch.ttl in savedsearches.conf.

Valid values are Integer[p].

action.email.use_ssl Indicates whether to use SSL when communicating with the SMTP server.
action.email.use_tls Indicates whether to use TLS (transport layer security) when communicating with the SMTP server (starttls).
action.populate_lookup The state of the populate lookup action.
action.populate_lookup.command The search command (or pipeline) which is responsible for executing the action.

Generally the command is a template search pipeline which is realized with values from the saved search.

To reference saved search field values wrap them in $, for example to reference the savedsearch name use $name$, to reference the search use $search$.

action.populate_lookup.hostname Sets the hostname used in the web link (url) sent in alert actions.

This value accepts two forms:

hostname (for example, splunkserver, splunkserver.example.com)

protocol://hostname:port (for example, http://splunkserver:8000, https://splunkserver.example.com:443)

See action.email.hostname for details.

action.populate_lookup.maxresults The maximum number of search results sent using alerts.
action.populate_lookup.maxtime Sets the maximum amount of time the execution of an action takes before the action is aborted. Defaults to 5m.

Valid values are: Integer[m|s|h|d]

action.populate_lookup.track_alert Indicates whether the execution of this action signifies a trackable alert.
action.populate_lookup.ttl Specifies the minimum time-to-live in seconds of the search artifacts if this action is triggered. If p follows Integer, then this specifies the number of scheduled periods. Defaults to 10p.

If no actions are triggered, the artifacts have their ttl determined by dispatch.ttl in savedsearches.conf.

Valid values are Integer[p]

action.rss The state of the RSS action.
action.rss.command The search command (or pipeline) which is responsible for executing the action.

Generally the command is a template search pipeline which is realized with values from the saved search. To reference saved search field values wrap them in $, for example to reference the savedsearch name use $name$, to reference the search use $search$.

action.rss.hostname Sets the hostname used in the web link (url) sent in alert actions.
action.rss.maxresults Sets the maximum number of search results sent using alerts.
action.rss.maxtime Sets the maximum amount of time the execution of an action takes before the action is aborted. Defaults to 1m.
action.rss.track_alert Indicates whether the execution of this action signifies a trackable alert.
action.rss.ttl Specifies the minimum time-to-live in seconds of the search artifacts if this action is triggered. If p follows Integer, specifies the number of scheduled periods. Defaults to 86400 (24 hours).

If no actions are triggered, the artifacts have their ttl determined by dispatch.ttl in savedsearches.conf.

Valid values are: Integer[p]

action.script The state of the script action.
action.script.command The search command (or pipeline) which is responsible for executing the action.

Generally the command is a template search pipeline which is realized with values from the saved search. To reference saved search field values wrap them in $, for example to reference the savedsearch name use $name$, to reference the search use $search$.

action.script.hostname Sets the hostname used in the web link (url) sent in alert actions.

This value accepts two forms:

hostname (for example, splunkserver, splunkserver.example.com)


protocol://hostname:port (for example, http://splunkserver:8000, https://splunkserver.example.com:443)


See action.email.hostname for details.

action.script.maxresults The maximum number of search results sent using alerts.
action.script.maxtime Sets the maximum amount of time the execution of an action takes before the action is aborted.
action.script.track_alert Indicates whether the execution of this action signifies a trackable alert.
action.script.ttl Specifies the minimum time-to-live in seconds of the search artifacts if this action is triggered. If p follows Integer, specifies the number of scheduled periods. Defaults to 600 (10 minutes).

If no actions are triggered, the artifacts have their ttl determined by dispatch.ttl in savedsearches.conf.

Valid values are: Integer[p]

action.summary_index The state of the summary index action.
action.summary_index._name Specifies the name of the summary index where the results of the scheduled search are saved.

Defaults to "summary."

action.summary_index.command The search command (or pipeline) which is responsible for executing the action.

Generally the command is a template search pipeline which is realized with values from the saved search. To reference saved search field values wrap them in $, for example to reference the savedsearch name use $name$, to reference the search use $search$.

action.summary_index.hostname Specifies the name of the summary index where the results of the scheduled search are saved.

Defaults to "summary."

action.summary_index.inline Determines whether to execute the summary indexing action as part of the scheduled search.

Note: This option is considered only if the summary index action is enabled and is always executed (in other words, if counttype = always).

action.summary_index.maxresults Sets the maximum number of search results sent using alerts.
action.summary_index.maxtime Sets the maximum amount of time the execution of an action takes before the action is aborted. Defaults to 5m.
action.summary_index.track_alert Indicates whether the execution of this action signifies a trackable alert.
action.summary_index.ttl Specifies the minimum time-to-live in seconds of the search artifacts if this action is triggered. If p follows Integer, specifies the number of scheduled periods. Defaults to 10p.

If no actions are triggered, the artifacts have their ttl determined by dispatch.ttl in savedsearches.conf.

Valid values are: Integer[p]

alert.digest_mode Specifies whether Splunk applies the alert actions to the entire result set or on each individual result.
alert.expires Sets the period of time to show the alert in the dashboard. Defaults to 24h.
alert.severity Valid values: (1 | 2 | 3 | 4 | 5 | 6)

Sets the alert severity level.

Valid values are:

1 DEBUG
2 INFO
3 WARN
4 ERROR
5 SEVERE
6 FATAL
alert.suppress Indicates whether alert suppression is enabled for this schedules search.
alert.suppress.period Specifies the suppresion period. Only valid if alert.supress is enabled.

Uses [number][time-unit] to specify a time. For example: 60 = 60 seconds, 1m = 1 minute, 1h = 60 minutes = 1 hour.

alert.track Specifies whether to track the actions triggered by this scheduled search.

auto - determine whether to track or not based on the tracking setting of each action, do not track scheduled searches that always trigger actions.

true - force alert tracking.

false - disable alert tracking for this search.

alert_comparator One of the following strings:
greater than
less than
equal to
rises by
drops by
rises by perc
drops by perc

Used with alert_threshold to trigger alert actions.

alert_condition A conditional search that is evaluated against the results of the saved search. Defaults to an empty string.

Alerts are triggered if the specified search yields a non-empty search result list.

alert_threshold Valid values are: Integer[%]

Specifies the value to compare (see alert_comparator) before triggering the alert actions. If expressed as a percentage, indicates value to use when alert_comparator is set to "rises by perc" or "drops by perc."

alert_type What to base the alert on, overriden by alert_condition if it is specified. Valid values are: always, custom, number of events, number of hosts, number of sources.
cron_schedule The cron schedule to execute this search. For example: */5 * * * * causes the search to execute every 5 minutes.

cron lets you use standard cron notation to define your scheduled search interval. In particular, cron can accept this type of notation: 00,20,40 * * * *, which runs the search every hour at hh:00, hh:20, hh:40. Along the same lines, a cron of 03,23,43 * * * * runs the search every hour at hh:03, hh:23, hh:43.

Splunk recommends that you schedule your searches so that they are staggered over time. This reduces system load. Running all of them every 20 minutes (*/20) means they would all launch at hh:00 (20, 40) and might slow your system every 20 minutes.

Valid values: cron string

description Description of this saved search.
disabled Indicates if this saved search is disabled.
dispatch.buckets The maximum nuber of timeline buckets.
dispatch.earliest_time A time string that specifies the earliest time for this search. Can be a relative or absolute time.

If this value is an absolute time, use the dispatch.time_format to format the value.

dispatch.latest_time A time string that specifies the latest time for this saved search. Can be a relative or absolute time.

If this value is an absolute time, use the dispatch.time_format to format the value.

dispatch.lookups Indicates if lookups are enabled for this search.
dispatch.max_count The maximum number of results before finalizing the search.
dispatch.max_time Indicates the maximum amount of time (in seconds) before finalizing the search.
dispatch.reduce_freq Specifies how frequently Splunk should run the MapReduce reduce phase on accumulated map values.
dispatch.spawn_process Indicates whether Splunk spawns a new search process when this saved search is executed.
dispatch.time_format A time format string that defines the time format that Splunk uses to specify the earliest and latest time.
dispatch.ttl Indicates the time to live (in seconds) for the artifacts of the scheduled search, if no actions are triggered.

If an action is triggered Splunk changes the ttl to that action's ttl. If multiple actions are triggered, Splunk applies the maximum ttl to the artifacts. To set the action's ttl, refer to alert_actions.conf.spec.

If the integer is followed by the letter 'p' Splunk interprets the ttl as a multiple of the scheduled search's period.

displayview Defines the default Splunk Web view name (not label) in which to load the results. Accessibility is subject to the user having sufficient permissions.
eai:attributes See Accessing Splunk resources
earliest_time For scheduled searches display all the scheduled times starting from this time.
is_scheduled Indicates if this search is to be run on a schedule.
is_visible Indicates if this saved search appears in the visible saved search list.
latest_time For scheduled searches display all the scheduled times until this time (not just the next run time).
max_concurrent The maximum number of concurrent instances of this search the scheduler is allowed to run.
next_scheduled_time The time when the scheduler runs this search again.
qualifiedSearch The exact search command for this saved search.
realtime_schedule Controls the way the scheduler computes the next execution time of a scheduled search. If this value is set to 1, the scheduler bases its determination of the next scheduled search execution time on the current time.

If this value is set to 0, the scheduler bases its determination of the next scheduled search on the last search execution time. This is called continuous scheduling.

See the POST parameter for this attribute for details.

request.ui_dispatch_app A field used by Splunk Web to denote the app this search should be dispatched in.
request.ui_dispatch_view Specifies a field used by Splunk Web to denote the view this search should be displayed in.
restart_on_searchpeer_add Indicates whether to restart a real-time search managed by the scheduler when a search peer becomes available for this saved search.

Note: The peer can be a newly added peer or a peer that has been down and has become available.

run_on_startup Indicates whether this search runs when Splunk starts. If it does not run on startup, it runs at the next scheduled time.

Splunk recommends that you set run_on_startup to true for scheduled searches that populate lookup tables.

search Search expression to filter the response. The response matches field values against the search expression. For example:

search=foo matches any object that has "foo" as a substring in a field. search=field_name%3Dfield_value restricts the match to a single field. URI-encoding is required in this example.

vsid Defines the viewstate id associated with the UI view listed in 'displayview'.

Must match up to a stanza in viewstates.conf.

Example

Return details of the saved search, MySavedSearch, which was created in the example for the POST operation for saved/searches. 


curl -k -u admin:pass https://localhost:8089/servicesNS/admin/search/saved/searches/MySavedSearch



<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>savedsearch</title>
  <id>https://localhost:8089/servicesNS/admin/search/saved/searches</id>
  <updated>2011-07-13T11:57:54-07:00</updated>
  <generator version="102824"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/servicesNS/admin/search/saved/searches/_new" rel="create"/>
  <link href="/servicesNS/admin/search/saved/searches/_reload" rel="_reload"/>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
  <entry>
    <title>MySavedSearch</title>
    <id>https://localhost:8089/servicesNS/admin/search/saved/searches/MySavedSearch</id>
    <updated>2011-07-13T11:57:54-07:00</updated>
    <link href="/servicesNS/admin/search/saved/searches/MySavedSearch" rel="alternate"/>
    <author>
      <name>admin</name>
    </author>
    <link href="/servicesNS/admin/search/saved/searches/MySavedSearch" rel="list"/>
    <link href="/servicesNS/admin/search/saved/searches/MySavedSearch/_reload" rel="_reload"/>
    <link href="/servicesNS/admin/search/saved/searches/MySavedSearch" rel="edit"/>
    <link href="/servicesNS/admin/search/saved/searches/MySavedSearch" rel="remove"/>
    <link href="/servicesNS/admin/search/saved/searches/MySavedSearch/move" rel="move"/>
    <link href="/servicesNS/admin/search/saved/searches/MySavedSearch/disable" rel="disable"/>
    <link href="/servicesNS/admin/search/saved/searches/MySavedSearch/dispatch" rel="dispatch"/>
    <link href="/servicesNS/admin/search/saved/searches/MySavedSearch/history" rel="history"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="action.email">0</s:key>
        <s:key name="action.email.auth_password"/>
        <s:key name="action.email.auth_username"/>
        <s:key name="action.email.bcc"/>
        <s:key name="action.email.cc"/>
        <s:key name="action.email.command">
      <![CDATA[$action.email.preprocess_results{default=""}$
     | sendemail "server=$action.email.mailserver{default=localhost}$" "use_ssl=$action.email.use_ssl{default=false}$"
      "use_tls=$action.email.use_tls{default=false}$" "to=$action.email.to$" "cc=$action.email.cc$"
      "bcc=$action.email.bcc$" "from=$action.email.from{default=splunk@localhost}$" "subject=$action.email.subject{recurse=yes}$"
      "format=$action.email.format{default=csv}$" "sssummary=Saved Search [$name$]: $counttype$($results.count$)"
      "sslink=$results.url$" "ssquery=$search$" "ssname=$name$" "inline=$action.email.inline{default=False}$"
      "sendresults=$action.email.sendresults{default=False}$" "sendpdf=$action.email.sendpdf{default=False}$"
      "pdfview=$action.email.pdfview$" "searchid=$search_id$" "graceful=$graceful{default=True}$"
      maxinputs="$action.email.maxresults{default=10000}$" maxtime="$action.email.maxtime{default=5m}$"]]>
        </s:key>
        <s:key name="action.email.format">html</s:key>
        <s:key name="action.email.from">splunk</s:key>
        <s:key name="action.email.hostname"/>
        <s:key name="action.email.inline">0</s:key>
        <s:key name="action.email.mailserver">localhost</s:key>
        <s:key name="action.email.maxresults">10000</s:key>
        <s:key name="action.email.maxtime">5m</s:key>
        <s:key name="action.email.preprocess_results"/>
        <s:key name="action.email.reportPaperOrientation">portrait</s:key>
        <s:key name="action.email.reportPaperSize">letter</s:key>
        <s:key name="action.email.reportServerEnabled">0</s:key>
        <s:key name="action.email.reportServerURL"/>
        <s:key name="action.email.sendpdf">0</s:key>
        <s:key name="action.email.sendresults">0</s:key>
        <s:key name="action.email.subject">Splunk Alert: $name$</s:key>
        <s:key name="action.email.to"/>
        <s:key name="action.email.track_alert">1</s:key>
        <s:key name="action.email.ttl">86400</s:key>
        <s:key name="action.email.use_ssl">0</s:key>
        <s:key name="action.email.use_tls">0</s:key>
        <s:key name="action.populate_lookup">0</s:key>
        <s:key name="action.populate_lookup.command">
          copyresults dest="$action.populate_lookup.dest$"  sid="$search_id$"
        </s:key>
        <s:key name="action.populate_lookup.hostname"/>
        <s:key name="action.populate_lookup.maxresults">10000</s:key>
        <s:key name="action.populate_lookup.maxtime">5m</s:key>
        <s:key name="action.populate_lookup.track_alert">0</s:key>
        <s:key name="action.populate_lookup.ttl">120</s:key>
        <s:key name="action.rss">0</s:key>
        <s:key name="action.rss.command">
          createrss "path=$name$.xml" "name=$name$" "link=$results.url$"
          "descr=Alert trigger: $name$, results.count=$results.count$ " "count=30"
          "graceful=$graceful{default=1}$" maxtime="$action.rss.maxtime{default=1m}$"
        </s:key>
        <s:key name="action.rss.hostname"/>
        <s:key name="action.rss.maxresults">10000</s:key>
        <s:key name="action.rss.maxtime">1m</s:key>
        <s:key name="action.rss.track_alert">0</s:key>
        <s:key name="action.rss.ttl">86400</s:key>
        <s:key name="action.script">0</s:key>
        <s:key name="action.script.command">runshellscript "$action.script.filename$"
          "$results.count$" "$search$" "$search$" "$name$"
          "Saved Search [$name$] $counttype$($results.count$)" "$results.url$"
          "$deprecated_arg$" "$search_id$"
          maxtime="$action.script.maxtime{default=5m}$"
        </s:key>
        <s:key name="action.script.hostname"/>
        <s:key name="action.script.maxresults">10000</s:key>
        <s:key name="action.script.maxtime">5m</s:key>
        <s:key name="action.script.track_alert">1</s:key>
        <s:key name="action.script.ttl">600</s:key>
        <s:key name="action.summary_index">0</s:key>
        <s:key name="action.summary_index._name">summary</s:key>
        <s:key name="action.summary_index.command">
          <![CDATA[summaryindex spool=t uselb=t addtime=t index="$action.summary_index._name{required=yes}$"
          file="$name$_$#random$.stash_new" name="$name$"
          marker="$action.summary_index*{format=$KEY=\\\"$VAL\\\",
            key_regex="action.summary_index.(?!(?:command|inline|maxresults|maxtime|ttl|track_alert|(?:_.*))$)(.*)"}$"]]>
        </s:key>
        <s:key name="action.summary_index.hostname"/>
        <s:key name="action.summary_index.inline">1</s:key>
        <s:key name="action.summary_index.maxresults">10000</s:key>
        <s:key name="action.summary_index.maxtime">5m</s:key>
        <s:key name="action.summary_index.track_alert">0</s:key>
        <s:key name="action.summary_index.ttl">120</s:key>
        <s:key name="alert.digest_mode">1</s:key>
        <s:key name="alert.expires">24h</s:key>
        <s:key name="alert.severity">3</s:key>
        <s:key name="alert.suppress"/>
        <s:key name="alert.suppress.period"/>
        <s:key name="alert.track">auto</s:key>
        <s:key name="alert_comparator"/>
        <s:key name="alert_condition"/>
        <s:key name="alert_threshold"/>
        <s:key name="alert_type">always</s:key>
        <s:key name="cron_schedule"/>
        <s:key name="description"/>
        <s:key name="disabled">0</s:key>
        <s:key name="dispatch.buckets">0</s:key>
        <s:key name="dispatch.earliest_time"/>
        <s:key name="dispatch.latest_time"/>
        <s:key name="dispatch.lookups">1</s:key>
        <s:key name="dispatch.max_count">500000</s:key>
        <s:key name="dispatch.max_time">0</s:key>
        <s:key name="dispatch.reduce_freq">10</s:key>
        <s:key name="dispatch.spawn_process">1</s:key>
        <s:key name="dispatch.time_format">%FT%T.%Q%:z</s:key>
        <s:key name="dispatch.ttl">2p</s:key>
        <s:key name="displayview"/>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="eai:attributes">
          <s:dict>
            <s:key name="optionalFields">
              <s:list>
                <s:item>action.email</s:item>
                <s:item>action.email.auth_password</s:item>
                <s:item>action.email.auth_username</s:item>
                <s:item>action.email.bcc</s:item>
                <s:item>action.email.cc</s:item>
                <s:item>action.email.command</s:item>
                <s:item>action.email.format</s:item>
                <s:item>action.email.from</s:item>
                <s:item>action.email.hostname</s:item>
                <s:item>action.email.inline</s:item>
                <s:item>action.email.mailserver</s:item>
                <s:item>action.email.maxresults</s:item>
                <s:item>action.email.maxtime</s:item>
                <s:item>action.email.preprocess_results</s:item>
                <s:item>action.email.reportPaperOrientation</s:item>
                <s:item>action.email.reportPaperSize</s:item>
                <s:item>action.email.reportServerEnabled</s:item>
                <s:item>action.email.reportServerURL</s:item>
                <s:item>action.email.sendpdf</s:item>
                <s:item>action.email.sendresults</s:item>
                <s:item>action.email.subject</s:item>
                <s:item>action.email.to</s:item>
                <s:item>action.email.track_alert</s:item>
                <s:item>action.email.ttl</s:item>
                <s:item>action.email.use_ssl</s:item>
                <s:item>action.email.use_tls</s:item>
                <s:item>action.populate_lookup</s:item>
                <s:item>action.populate_lookup.command</s:item>
                <s:item>action.populate_lookup.hostname</s:item>
                <s:item>action.populate_lookup.maxresults</s:item>
                <s:item>action.populate_lookup.maxtime</s:item>
                <s:item>action.populate_lookup.track_alert</s:item>
                <s:item>action.populate_lookup.ttl</s:item>
                <s:item>action.rss</s:item>
                <s:item>action.rss.command</s:item>
                <s:item>action.rss.hostname</s:item>
                <s:item>action.rss.maxresults</s:item>
                <s:item>action.rss.maxtime</s:item>
                <s:item>action.rss.track_alert</s:item>
                <s:item>action.rss.ttl</s:item>
                <s:item>action.script</s:item>
                <s:item>action.script.command</s:item>
                <s:item>action.script.hostname</s:item>
                <s:item>action.script.maxresults</s:item>
                <s:item>action.script.maxtime</s:item>
                <s:item>action.script.track_alert</s:item>
                <s:item>action.script.ttl</s:item>
                <s:item>action.summary_index</s:item>
                <s:item>action.summary_index._name</s:item>
                <s:item>action.summary_index.command</s:item>
                <s:item>action.summary_index.hostname</s:item>
                <s:item>action.summary_index.inline</s:item>
                <s:item>action.summary_index.maxresults</s:item>
                <s:item>action.summary_index.maxtime</s:item>
                <s:item>action.summary_index.track_alert</s:item>
                <s:item>action.summary_index.ttl</s:item>
                <s:item>actions</s:item>
                <s:item>alert.digest_mode</s:item>
                <s:item>alert.expires</s:item>
                <s:item>alert.severity</s:item>
                <s:item>alert.suppress</s:item>
                <s:item>alert.suppress.period</s:item>
                <s:item>alert.track</s:item>
                <s:item>alert_comparator</s:item>
                <s:item>alert_condition</s:item>
                <s:item>alert_threshold</s:item>
                <s:item>alert_type</s:item>
                <s:item>cron_schedule</s:item>
                <s:item>description</s:item>
                <s:item>disabled</s:item>
                <s:item>dispatch.buckets</s:item>
                <s:item>dispatch.earliest_time</s:item>
                <s:item>dispatch.latest_time</s:item>
                <s:item>dispatch.lookups</s:item>
                <s:item>dispatch.max_count</s:item>
                <s:item>dispatch.max_time</s:item>
                <s:item>dispatch.reduce_freq</s:item>
                <s:item>dispatch.spawn_process</s:item>
                <s:item>dispatch.time_format</s:item>
                <s:item>dispatch.ttl</s:item>
                <s:item>displayview</s:item>
                <s:item>is_scheduled</s:item>
                <s:item>is_visible</s:item>
                <s:item>max_concurrent</s:item>
                <s:item>next_scheduled_time</s:item>
                <s:item>qualifiedSearch</s:item>
                <s:item>realtime_schedule</s:item>
                <s:item>request.ui_dispatch_app</s:item>
                <s:item>request.ui_dispatch_view</s:item>
                <s:item>restart_on_searchpeer_add</s:item>
                <s:item>run_on_startup</s:item>
                <s:item>vsid</s:item>
              </s:list>
            </s:key>
            <s:key name="requiredFields">
              <s:list>
                <s:item>search</s:item>
              </s:list>
            </s:key>
            <s:key name="wildcardFields">
              <s:list>
                <s:item>action\..*</s:item>
                <s:item>args\..*</s:item>
                <s:item>dispatch\..*</s:item>
              </s:list>
            </s:key>
          </s:dict>
        </s:key>
        <s:key name="is_scheduled">0</s:key>
        <s:key name="is_visible">1</s:key>
        <s:key name="max_concurrent">1</s:key>
        <s:key name="next_scheduled_time"/>
        <s:key name="qualifiedSearch">search  index</s:key>
        <s:key name="realtime_schedule">1</s:key>
        <s:key name="request.ui_dispatch_app"/>
        <s:key name="request.ui_dispatch_view"/>
        <s:key name="restart_on_searchpeer_add">1</s:key>
        <s:key name="run_on_startup">0</s:key>
        <s:key name="search">index</s:key>
        <s:key name="vsid"/>
      </s:dict>
    </content>
  </entry>
</feed>

POST saved/searches/{name}

Updates this saved search.

Request

Name Type Required Default Description
search String
✓
 The search to save.
action.* String Wildcard argument for any action.

Use this parameter to specify specific action arguments. For example, to specify the email recipients for action.email.to.

action.email Boolean 0 The state of the email action. Read-only attribute. Value ignored on POST. Use actions to specify a list of enabled actions.
action.email.auth_password String The password to use when authenticating with the SMTP server. Normally this value will be set when editing the email settings, however you can set a clear text password here and it will be encrypted on the next Splunk restart.

Defaults to empty string.

action.email.auth_username String The username to use when authenticating with the SMTP server. If this is empty string, no authentication is attempted. Defaults to empty string.

NOTE: Your SMTP server might reject unauthenticated emails.

action.email.bcc String BCC email address to use if action.email is enabled.
action.email.cc String CC email address to use if action.email is enabled.
action.email.command String The search command (or pipeline) which is responsible for executing the action.

Generally the command is a template search pipeline which is realized with values from the saved search. To reference saved search field values wrap them in $, for example to reference the savedsearch name use $name$, to reference the search use $search$.

action.email.format Enum Valid values: (plain | html | raw | csv)

Specify the format of text in the email. plain indicates plain text. This value also applies to any attachments.

action.email.from String Email address from which the email action originates.

Defaults to splunk@$LOCALHOST or whatever value is set in alert_actions.conf.

action.email.hostname String Sets the hostname used in the web link (url) sent in email actions.

This value accepts two forms:

hostname (for example, splunkserver, splunkserver.example.com)

protocol://hostname:port (for example, http://splunkserver:8000, https://splunkserver.example.com:443)

When this value is a simple hostname, the protocol and port which are configured within splunk are used to construct the base of the url.

When this value begins with 'http://', it is used verbatim. NOTE: This means the correct port must be specified if it is not the default port for http or https. This is useful in cases when the Splunk server is not aware of how to construct an externally referencable url, such as SSO environments, other proxies, or when the Splunk server hostname is not generally resolvable.

Defaults to current hostname provided by the operating system, or if that fails "localhost". When set to empty, default behavior is used.

action.email.inline Boolean Indicates whether the search results are contained in the body of the email.

Results can be either inline or attached to an email. See action.email.sendresults.

action.email.mailserver String Set the address of the MTA server to be used to send the emails.

Defaults to <LOCALHOST> (or whatever is set in alert_actions.conf).

action.email.maxresults Number Sets the global maximum number of search results to send when action.email is enabled.

Defaults to 100.

action.email.maxtime Number Valid values are Integer[m|s|h|d].

Specifies the maximum amount of time the execution of an email action takes before the action is aborted. Defaults to 5m.

action.email.pdfview String The name of the view to deliver if sendpdf is enabled
action.email.preprocess_results String Search string to preprocess results before emailing them. Defaults to empty string (no preprocessing).

Usually the preprocessing consists of filtering out unwanted internal fields.

action.email.reportPaperOrientation Enum Valid values: (portrait | landscape)

Specifies the paper orientation: portrait or landscape. Defaults to portrait.

action.email.reportPaperSize Enum Valid values: (letter | legal | ledger | a2 | a3 | a4 | a5)

Specifies the paper size for PDFs. Defaults to letter.

action.email.reportServerEnabled Boolean Indicates whether the PDF server is enabled. Defaults to false.
action.email.reportServerURL String The URL of the PDF report server, if one is set up and available on the network.

For a default locally installed report server, the URL is http://localhost:8091/

action.email.sendpdf Boolean Indicates whether to create and send the results as a PDF. Defaults to false.
action.email.sendresults Boolean Indicates whether to attach the search results in the email.

Results can be either attached or inline. See action.email.inline.

action.email.subject String Specifies an alternate email subject.

Defaults to SplunkAlert-<savedsearchname>.

action.email.to String A comma or semicolon separated list of recipient email addresses. Required if this search is scheduled and the email alert action is enabled.
action.email.track_alert Boolean Indicates whether the execution of this action signifies a trackable alert.
action.email.ttl Number Valid values are Integer[p].

Specifies the minimum time-to-live in seconds of the search artifacts if this action is triggered. If p follows <Integer>, int is the number of scheduled periods. Defaults to 86400 (24 hours).

If no actions are triggered, the artifacts have their ttl determined by dispatch.ttl in savedsearches.conf.

action.email.use_ssl Boolean Indicates whether to use SSL when communicating with the SMTP server.

Defaults to false.

action.email.use_tls Boolean Indicates whether to use TLS (transport layer security) when communicating with the SMTP server (starttls).

Defaults to false.

action.email.width_sort_columns Boolean Indicates whether columns should be sorted from least wide to most wide, left to right.

Only valid if format=plain, indicating plain text.

action.populate_lookup Boolean 0 The state of the populate lookup action. Read-only attribute. Value ignored on POST. Use actions to specify a list of enabled actions.
action.populate_lookup.command String The search command (or pipeline) which is responsible for executing the action.

Generally the command is a template search pipeline which is realized with values from the saved search. To reference saved search field values wrap them in $, for example to reference the savedsearch name use $name$, to reference the search use $search$.

action.populate_lookup.dest String Lookup name of path of the lookup to populate
action.populate_lookup.hostname String Sets the hostname used in the web link (url) sent in alert actions.

This value accepts two forms:

hostname (for example, splunkserver, splunkserver.example.com)

protocol://hostname:port (for example, http://splunkserver:8000, https://splunkserver.example.com:443)

See action.email.hostname for details.

action.populate_lookup.maxresults Number Sets the maximum number of search results sent via alerts. Defaults to 100.
action.populate_lookup.maxtime Number Valid values are: Integer[m|s|h|d]

Sets the maximum amount of time the execution of an action takes before the action is aborted. Defaults to 5m.

action.populate_lookup.track_alert Boolean Indicates whether the execution of this action signifies a trackable alert.
action.populate_lookup.ttl Number Valid values are Integer[p]

Specifies the minimum time-to-live in seconds of the search artifacts if this action is triggered. If p follows Integer, then this specifies the number of scheduled periods. Defaults to 10p.

If no actions are triggered, the artifacts have their ttl determined by dispatch.ttl in savedsearches.conf.

action.rss Boolean 0 The state of the rss action. Read-only attribute. Value ignored on POST. Use actions to specify a list of enabled actions.
action.rss.command String The search command (or pipeline) which is responsible for executing the action.

Generally the command is a template search pipeline which is realized with values from the saved search. To reference saved search field values wrap them in $, for example to reference the savedsearch name use $name$, to reference the search use $search$.

action.rss.hostname String Sets the hostname used in the web link (url) sent in alert actions.

This value accepts two forms:

hostname (for example, splunkserver, splunkserver.example.com)

protocol://hostname:port (for example, http://splunkserver:8000, https://splunkserver.example.com:443)

See action.email.hostname for details.

action.rss.maxresults Number Sets the maximum number of search results sent via alerts. Defaults to 100.
action.rss.maxtime Number Valid values are Integer[m|s|h|d].

Sets the maximum amount of time the execution of an action takes before the action is aborted. Defaults to 1m.

action.rss.track_alert Boolean Indicates whether the execution of this action signifies a trackable alert.
action.rss.ttl Number Valid values are: Integer[p]

Specifies the minimum time-to-live in seconds of the search artifacts if this action is triggered. If p follows Integer, specifies the number of scheduled periods. Defaults to 86400 (24 hours).

If no actions are triggered, the artifacts have their ttl determined by dispatch.ttl in savedsearches.conf.

action.script Boolean 0 The state of the script action. Read-only attribute. Value ignored on POST. Use actions to specify a list of enabled actions.
action.script.command String The search command (or pipeline) which is responsible for executing the action.

Generally the command is a template search pipeline which is realized with values from the saved search. To reference saved search field values wrap them in $, for example to reference the savedsearch name use $name$, to reference the search use $search$.

action.script.filename String File name of the script to call. Required if script action is enabled
action.script.hostname String Sets the hostname used in the web link (url) sent in alert actions.

This value accepts two forms:

hostname (for example, splunkserver, splunkserver.example.com)

protocol://hostname:port (for example, http://splunkserver:8000, https://splunkserver.example.com:443)

See action.email.hostname for details.

action.script.maxresults Number Sets the maximum number of search results sent via alerts. Defaults to 100.
action.script.maxtime Number Valid values are: Integer[m|s|h|d]

Sets the maximum amount of time the execution of an action takes before the action is aborted. Defaults to 5m.

action.script.track_alert Boolean Indicates whether the execution of this action signifies a trackable alert.
action.script.ttl Number Valid values are: Integer[p]

Specifies the minimum time-to-live in seconds of the search artifacts if this action is triggered. If p follows Integer, specifies the number of scheduled periods. Defaults to 600 (10 minutes).

If no actions are triggered, the artifacts have their ttl determined by dispatch.ttl in savedsearches.conf.

action.summary_index Boolean 0 The state of the summary index action. Read-only attribute. Value ignored on POST. Use actions to specify a list of enabled actions.

Defaults to 0

action.summary_index._name String Specifies the name of the summary index where the results of the scheduled search are saved.

Defaults to "summary."

action.summary_index.command String The search command (or pipeline) which is responsible for executing the action.

Generally the command is a template search pipeline which is realized with values from the saved search. To reference saved search field values wrap them in $, for example to reference the savedsearch name use $name$, to reference the search use $search$.

action.summary_index.hostname String Sets the hostname used in the web link (url) sent in alert actions.

This value accepts two forms:

hostname (for example, splunkserver, splunkserver.example.com)

protocol://hostname:port (for example, http://splunkserver:8000, https://splunkserver.example.com:443)

See action.email.hostname for details.

action.summary_index.inline Boolean Determines whether to execute the summary indexing action as part of the scheduled search.

NOTE: This option is considered only if the summary index action is enabled and is always executed (in other words, if counttype = always).

Defaults to true

action.summary_index.maxresults Number Sets the maximum number of search results sent via alerts. Defaults to 100.
action.summary_index.maxtime Number Valid values are: Integer[m|s|h|d]

Sets the maximum amount of time the execution of an action takes before the action is aborted. Defaults to 5m.

action.summary_index.track_alert Boolean Indicates whether the execution of this action signifies a trackable alert.
action.summary_index.ttl Number Valid values are: Integer[p]

Specifies the minimum time-to-live in seconds of the search artifacts if this action is triggered. If p follows Integer, specifies the number of scheduled periods. Defaults to 10p.

If no actions are triggered, the artifacts have their ttl determined by dispatch.ttl in savedsearches.conf.

actions String A comma-separated list of actions to enable.

For example: rss,email

alert.digest_mode Boolean 1 Specifies whether Splunk applies the alert actions to the entire result set or on each individual result.

Defaults to true.

alert.expires Number 24h Valid values: [number][time-unit]

Sets the period of time to show the alert in the dashboard. Defaults to 24h.

Use [number][time-unit] to specify a time. For example: 60 = 60 seconds, 1m = 1 minute, 1h = 60 minutes = 1 hour.

alert.severity Enum 3 Valid values: (1 | 2 | 3 | 4 | 5 | 6)

Sets the alert severity level.

Valid values are:

1 DEBUG 2 INFO 3 WARN 4 ERROR 5 SEVERE 6 FATAL

alert.suppress Boolean Indicates whether alert suppression is enabled for this scheduled search.
alert.suppress.fields String Comma delimited list of fields to use for suppression when doing per result alerting. Required if suppression is turned on and per result alerting is enabled.
alert.suppress.period Number Valid values: [number][time-unit]

Specifies the suppresion period. Only valid if alert.supress is enabled.

Use [number][time-unit] to specify a time. For example: 60 = 60 seconds, 1m = 1 minute, 1h = 60 minutes = 1 hour.

alert.track Enum auto Valid values: (true | false | auto)

Specifies whether to track the actions triggered by this scheduled search.

auto - determine whether to track or not based on the tracking setting of each action, do not track scheduled searches that always trigger actions.

true - force alert tracking.

false - disable alert tracking for this search.

alert_comparator String One of the following strings: greater than, less than, equal to, rises by, drops by, rises by perc, drops by perc

Used with alert_threshold to trigger alert actions.

alert_condition String Contains a conditional search that is evaluated against the results of the saved search. Defaults to an empty string.

Alerts are triggered if the specified search yields a non-empty search result list.

NOTE: If you specify an alert_condition, do not set counttype, relation, or quantity.

alert_threshold Number Valid values are: Integer[%]

Specifies the value to compare (see alert_comparator) before triggering the alert actions. If expressed as a percentage, indicates value to use when alert_comparator is set to "rises by perc" or "drops by perc."

alert_type String What to base the alert on, overriden by alert_condition if it is specified. Valid values are: always, custom, number of events, number of hosts, number of sources
args.* String Wildcard argument that accepts any saved search template argument, such as args.username=foobar when the search is search $username$.
cron_schedule String Valid values: cron string

The cron schedule to execute this search. For example: */5 * * * * causes the search to execute every 5 minutes.

cron lets you use standard cron notation to define your scheduled search interval. In particular, cron can accept this type of notation: 00,20,40 * * * *, which runs the search every hour at hh:00, hh:20, hh:40. Along the same lines, a cron of 03,23,43 * * * * runs the search every hour at hh:03, hh:23, hh:43.

Splunk recommends that you schedule your searches so that they are staggered over time. This reduces system load. Running all of them every 20 minutes (*/20) means they would all launch at hh:00 (20, 40) and might slow your system every 20 minutes.

description String Human-readable description of this saved search. Defaults to empty string.
disabled Boolean 0 Indicates if the saved search is enabled.

Disabled saved searches are not visible in Splunk Web.

dispatch.* String Wildcard argument that accepts any dispatch related argument.
dispatch.buckets Number 0 The maximum number of timeline buckets.
dispatch.earliest_time String A time string that specifies the earliest time for this search. Can be a relative or absolute time.

If this value is an absolute time, use the dispatch.time_format to format the value.

dispatch.latest_time String A time string that specifies the latest time for this saved search. Can be a relative or absolute time.

If this value is an absolute time, use the dispatch.time_format to format the value.

dispatch.lookups Boolean 1 Enables or disables the lookups for this search.
dispatch.max_count Number 500000 The maximum number of results before finalizing the search.
dispatch.max_time Number 0 Indicates the maximum amount of time (in seconds) before finalizing the search.
dispatch.reduce_freq Number 10 Specifies, in seconds, how frequently Splunk should run the MapReduce reduce phase on accumulated map values.
dispatch.rt_backfill Boolean 0 Whether to back fill the real time window for this search. Parameter valid only if this is a real time search
dispatch.spawn_process Boolean 1 Specifies whether Splunk spawns a new search process when this saved search is executed.

Searches against indexes must run in a separate process.

dispatch.time_format String  %FT%T.%Q%:z A time format string that defines the time format that Splunk uses to specify the earliest and latest time.
dispatch.ttl Number 2p Valid values: Integer[p]

Indicates the time to live (in seconds) for the artifacts of the scheduled search, if no actions are triggered.

If an action is triggered Splunk changes the ttl to that action's ttl. If multiple actions are triggered, Splunk applies the maximum ttl to the artifacts. To set the action's ttl, refer to alert_actions.conf.spec.

If the integer is followed by the letter 'p' Splunk interprets the ttl as a multiple of the scheduled search's period.

displayview String Defines the default UI view name (not label) in which to load the results. Accessibility is subject to the user having sufficient permissions.
is_scheduled Boolean Whether this search is to be run on a schedule
is_visible Boolean 1 Specifies whether this saved search should be listed in the visible saved search list.
max_concurrent Number 1 The maximum number of concurrent instances of this search the scheduler is allowed to run.
next_scheduled_time String Read-only attribute. Value ignored on POST. There are some old clients who still send this value
qualifiedSearch String Read-only attribute. Value ignored on POST. Splunk computes this value during runtime.
realtime_schedule Boolean 1 Controls the way the scheduler computes the next execution time of a scheduled search. If this value is set to 1, the scheduler bases its determination of the next scheduled search execution time on the current time.

If this value is set to 0, the scheduler bases its determination of the next scheduled search on the last search execution time. This is called continuous scheduling. If set to 0, the scheduler never skips scheduled execution periods. However, the execution of the saved search might fall behind depending on the scheduler's load. Use continuous scheduling whenever you enable the summary index option.

If set to 1, the scheduler might skip some execution periods to make sure that the scheduler is executing the searches running over the most recent time range.

The scheduler tries to execute searches that have realtime_schedule set to 1 before it executes searches that have continuous scheduling (realtime_schedule = 0).

request.ui_dispatch_app String Specifies a field used by Splunk UI to denote the app this search should be dispatched in.
request.ui_dispatch_view String Specifies a field used by Splunk UI to denote the view this search should be displayed in.
restart_on_searchpeer_add Boolean 1 Specifies whether to restart a real-time search managed by the scheduler when a search peer becomes available for this saved search.

NOTE: The peer can be a newly added peer or a peer that has been down and has become available.

run_on_startup Boolean 0 Indicates whether this search runs when Splunk starts. If it does not run on startup, it runs at the next scheduled time.

Splunk recommends that you set run_on_startup to true for scheduled searches that populate lookup tables.

vsid String Defines the viewstate id associated with the UI view listed in 'displayview'.

Must match up to a stanza in viewstates.conf.

Response Codes

Status Code Description
200 Updated successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
402 The Splunk license in use has disabled this feature.
403 Insufficient permissions to edit saved search.
404 Saved search does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.
503 This feature has been disabled in Splunk configuration files.

Returned Values

Attribute Description
action.email Indicates the state of the email action.
action.email.auth_password The password to use when authenticating with the SMTP server. Normally this value will be set when editing the email settings, however you can set a clear text password here that is encrypted on the next Splunk restart.

Defaults to empty string.

action.email.auth_username The username to use when authenticating with the SMTP server. If this is empty string, no authentication is attempted. Defaults to empty string.

Note: Your SMTP server might reject unauthenticated emails.

action.email.bcc BCC email address to use if action.email is enabled.
action.email.cc CC email address to use if action.email is enabled.
action.email.command The search command (or pipeline) which is responsible for executing the action.

Generally the command is a template search pipeline which is realized with values from the saved search. To reference saved search field values wrap them in $, for example to reference the savedsearch name use $name$, to reference the search use $search$.

action.email.format Specify the format of text in the email. This value also applies to any attachments.<

Valid values: (plain | html | raw | csv)

plain indicates plain text.

action.email.from Email address from which the email action originates.

Defaults to splunk@$LOCALHOST or whatever value is set in alert_actions.conf.

action.email.hostname Sets the hostname used in the web link (url) sent in email actions.

This value accepts two forms:

hostname (for example, splunkserver, splunkserver.example.com)

protocol://hostname:port (for example, http://splunkserver:8000, https://splunkserver.example.com:443)

When this value is a simple hostname, the protocol and port which are configured within splunk are used to construct the base of the url.

When this value begins with 'http://', it is used verbatim. NOTE: This means the correct port must be specified if it is not the default port for http or https. This is useful in cases when the Splunk server is not aware of how to construct an externally referencable url, such as SSO environments, other proxies, or when the Splunk server hostname is not generally resolvable.

Defaults to current hostname provided by the operating system, or if that fails "localhost". When set to empty, default behavior is used.

action.email.inline Indicates whether the search results are contained in the body of the email.

Results can be either inline or attached to an email. See action.email.sendresults.

action.email.mailserver Set the address of the MTA server to be used to send the emails.

Defaults to <LOCALHOST> (or whatever is set in alert_actions.conf).

action.email.maxresults A conditional search that is evaluated against the results of the saved search. Defaults to an empty string.

Alerts are triggered if the specified search yields a non-empty search result list.

Note: If you specify an alert_condition, do not set counttype, relation, or quantity.

action.email.maxtime Specifies the maximum amount of time the execution of an email action takes before the action is aborted.
action.email.pdfview The name of the view to deliver if sendpdf is enabled
action.email.preprocess_results Search string to preprocess results before emailing them. Defaults to empty string (no preprocessing).

Usually the preprocessing consists of filtering out unwanted internal fields.

action.email.reportPaperOrientation Specifies the paper orientation: portrait or landscape.
action.email.reportPaperSize Specifies the paper size for PDFs. Defaults to letter.

Valid values: (letter | legal | ledger | a2 | a3 | a4 | a5)

action.email.reportServerEnabled Indicates whether the PDF server is enabled.
action.email.reportServerURL The URL of the PDF report server, if one is set up and available on the network.

For a default locally installed report server, the URL is http://localhost:8091/

action.email.sendpdf Indicates whether to create and send the results as a PDF.
action.email.sendresults Indicates whether to attach the search results in the email.

Results can be either attached or inline. See action.email.inline.

action.email.subject Specifies an email subject.

Defaults to SplunkAlert-<savedsearchname>.

action.email.to List of recipient email addresses. Required if this search is scheduled and the email alert action is enabled.
action.email.track_alert Indicates whether the execution of this action signifies a trackable alert.
action.email.ttl Specifies the minimum time-to-live in seconds of the search artifacts if this action is triggered. If p follows <Integer>, int is the number of scheduled periods. Defaults to 86400 (24 hours).

If no actions are triggered, the artifacts have their ttl determined by dispatch.ttl in savedsearches.conf.

Valid values are Integer[p].

action.email.use_ssl Indicates whether to use SSL when communicating with the SMTP server.
action.email.use_tls Indicates whether to use TLS (transport layer security) when communicating with the SMTP server (starttls).
action.email.width_sort_columns Indicates whether columns should be sorted from least wide to most wide, left to right.

Only valid if format=plain, indicating plain text.

action.populate_lookup Indicates the state of the populate lookup action.
action.populate_lookup.command The search command (or pipeline) which is responsible for executing the action.

Generally the command is a template search pipeline which is realized with values from the saved search. To reference saved search field values wrap them in $, for example to reference the savedsearch name use $name$, to reference the search use $search$.

action.populate_lookup.dest Lookup name of path of the lookup to populate.
action.populate_lookup.hostname Sets the hostname used in the web link (url) sent in alert actions.

This value accepts two forms:

hostname (for example, splunkserver, splunkserver.example.com)

protocol://hostname:port (for example, http://splunkserver:8000, https://splunkserver.example.com:443)

See action.email.hostname for details.

action.populate_lookup.maxresults The maximum number of search results sent via alerts.
action.populate_lookup.maxtime The search command (or pipeline) which is responsible for executing the action.

Generally the command is a template search pipeline which is realized with values from the saved search. To reference saved search field values wrap them in $, for example to reference the savedsearch name use $name$, to reference the search use $search$.

action.populate_lookup.track_alert Indicates whether the execution of this action signifies a trackable alert.
action.populate_lookup.ttl Specifies the minimum time-to-live in seconds of the search artifacts if this action is triggered. If p follows Integer, then this specifies the number of scheduled periods. Defaults to 10p.

If no actions are triggered, the artifacts have their ttl determined by dispatch.ttl in savedsearches.conf.

Valid values are Integer[p]

action.rss Indicates the state of the RSS action.
action.rss.command The search command (or pipeline) which is responsible for executing the action.

Generally the command is a template search pipeline which is realized with values from the saved search. To reference saved search field values wrap them in $, for example to reference the savedsearch name use $name$, to reference the search use $search$.

action.rss.hostname Sets the hostname used in the web link (url) sent in alert actions.

This value accepts two forms:

hostname (for example, splunkserver, splunkserver.example.com)

protocol://hostname:port (for example, http://splunkserver:8000, https://splunkserver.example.com:443)

See action.email.hostname for details.

action.rss.maxresults Sets the maximum number of search results sent using alerts.
action.rss.maxtime Sets the maximum amount of time the execution of an action takes before the action is aborted. Defaults to 1m.
action.rss.track_alert Indicates whether the execution of this action signifies a trackable alert.
action.rss.ttl Specifies the minimum time-to-live in seconds of the search artifacts if this action is triggered. If p follows Integer, specifies the number of scheduled periods. Defaults to 86400 (24 hours).

If no actions are triggered, the artifacts have their ttl determined by dispatch.ttl in savedsearches.conf.

Valid values are: Integer[p]

action.script Indicates the state of the script for this action.
action.script.command The search command (or pipeline) which is responsible for executing the action.

Generally the command is a template search pipeline which is realized with values from the saved search. To reference saved search field values wrap them in $, for example to reference the savedsearch name use $name$, to reference the search use $search$.

action.script.filename File name of the script to call. Required if script action is enabled
action.script.hostname Sets the hostname used in the web link (url) sent in alert actions.

This value accepts two forms:

hostname (for example, splunkserver, splunkserver.example.com)


protocol://hostname:port (for example, http://splunkserver:8000, https://splunkserver.example.com:443)


See action.email.hostname for details.

action.script.maxresults Sets the maximum number of search results sent via alerts.
action.script.maxtime Sets the maximum amount of time the execution of an action takes before the action is aborted.
action.script.track_alert Specifies the name of the summary index where the results of the scheduled search are saved.

Defaults to "summary."

action.script.ttl Specifies the minimum time-to-live in seconds of the search artifacts if this action is triggered. If p follows Integer, specifies the number of scheduled periods. Defaults to 600 (10 minutes).

If no actions are triggered, the artifacts have their ttl determined by dispatch.ttl in savedsearches.conf.

Valid values are: Integer[p]

action.summary_index Indicates the state of the summary index.
action.summary_index._name Specifies the name of the summary index where the results of the scheduled search are saved.

Defaults to "summary."

action.summary_index.command The search command (or pipeline) which is responsible for executing the action.

Generally the command is a template search pipeline which is realized with values from the saved search. To reference saved search field values wrap them in $, for example to reference the savedsearch name use $name$, to reference the search use $search$.

action.summary_index.hostname Sets the hostname used in the web link (url) sent in alert actions.

This value accepts two forms:

hostname (for example, splunkserver, splunkserver.example.com)

protocol://hostname:port (for example, http://splunkserver:8000, https://splunkserver.example.com:443)

See action.email.hostname for details.

action.summary_index.inline Determines whether to execute the summary indexing action as part of the scheduled search.

Note: This option is considered only if the summary index action is enabled and is always executed (in other words, if counttype = always).

action.summary_index.maxresults Sets the maximum number of search results sent via alerts.
action.summary_index.maxtime Sets the maximum amount of time the execution of an action takes before the action is aborted. Defaults to 5m.

Valid values are: Integer[m|s|h|d]

action.summary_index.track_alert Indicates whether the execution of this action signifies a trackable alert.
action.summary_index.ttl Specifies the minimum time-to-live in seconds of the search artifacts if this action is triggered. If p follows Integer, specifies the number of scheduled periods. Defaults to 10p.

If no actions are triggered, the artifacts have their ttl determined by dispatch.ttl in savedsearches.conf.

Valid values are: Integer[p]

actions Actions to enable.
alert.digest_mode Indicates if Splunk applies the alert actions to the entire result set or on each individual result.
alert.expires Sets the period of time to show the alert in the dashboard. Defaults to 24h.

Use [number][time-unit] to specify a time. For example: 60 = 60 seconds, 1m = 1 minute, 1h = 60 minutes = 1 hour.

Valid values: [number][time-unit]

alert.severity Valid values: (1 | 2 | 3 | 4 | 5 | 6)

Sets the alert severity level.

Valid values are:

1 DEBUG
2 INFO
3 WARN
4 ERROR
5 SEVERE
6 FATAL
alert.suppress Indicates whether alert suppression is enabled for this schedules search.
alert.suppress.fields Fields to use for suppression when doing per result alerting. Required if suppression is turned on and per result alerting is enabled.
alert.suppress.period Specifies the suppresion period. Only valid if alert.supress is enabled.

Uses [number][time-unit] to specify a time. For example: 60 = 60 seconds, 1m = 1 minute, 1h = 60 minutes = 1 hour.

alert.track Specifies whether to track the actions triggered by this scheduled search.

auto - determine whether to track or not based on the tracking setting of each action, do not track scheduled searches that always trigger actions.

true - force alert tracking.

false - disable alert tracking for this search.

alert_comparator One of the following strings: greater than, less than, equal to, rises by, drops by, rises by perc, drops by perc

Used with alert_threshold to trigger alert actions.

alert_condition A conditional search that is evaluated against the results of the saved search. Defaults to an empty string.

Alerts are triggered if the specified search yields a non-empty search result list.

Note: If you specify an alert_condition, do not set counttype, relation, or quantity.

alert_threshold Valid values are: Integer[%]

Specifies the value to compare (see alert_comparator) before triggering the alert actions. If expressed as a percentage, indicates value to use when alert_comparator is set to "rises by perc" or "drops by perc."

alert_type What to base the alert on, overriden by alert_condition if it is specified. Valid values are: always, custom, number of events, number of hosts, number of sources.
args.* Wildcard argument that accepts any saved search template argument, such as args.username=foobar when the search is search $username$.
cron_schedule The cron schedule to execute this search. For example: */5 * * * * causes the search to execute every 5 minutes.

cron lets you use standard cron notation to define your scheduled search interval. In particular, cron can accept this type of notation: 00,20,40 * * * *, which runs the search every hour at hh:00, hh:20, hh:40. Along the same lines, a cron of 03,23,43 * * * * runs the search every hour at hh:03, hh:23, hh:43.

Splunk recommends that you schedule your searches so that they are staggered over time. This reduces system load. Running all of them every 20 minutes (*/20) means they would all launch at hh:00 (20, 40) and might slow your system every 20 minutes.

Valid values: cron string

description Description of this saved search.
disabled Indicates if the saved search is disnabled.

Disabled saved searches are not visible in Splunk Web.

dispatch.buckets The maximum nuber of timeline buckets.
dispatch.earliest_time A time string that specifies the earliest time for this search. Can be a relative or absolute time.

If this value is an absolute time, use the dispatch.time_format to format the value.

dispatch.latest_time A time string that specifies the latest time for this saved search. Can be a relative or absolute time.

If this value is an absolute time, use the dispatch.time_format to format the value.

dispatch.lookups Indicates if lookups are enabled for this search.
dispatch.max_count The maximum number of results before finalizing the search.
dispatch.max_time Indicates the maximum amount of time (in seconds) before finalizing the search.
dispatch.reduce_freq Specifies how frequently Splunk should run the MapReduce reduce phase on accumulated map values.
dispatch.rt_backfill Indicates whether to back fill the real time window for this search. Parameter valid only if this is a real time search
dispatch.spawn_process Indicates whether Splunk spawns a new search process when this saved search is executed.
dispatch.time_format Time format string that defines the time format that Splunk uses to specify the earliest and latest time.
dispatch.ttl Indicates the time to live (in seconds) for the artifacts of the scheduled search, if no actions are triggered.

If an action is triggered Splunk changes the ttl to that action's ttl. If multiple actions are triggered, Splunk applies the maximum ttl to the artifacts. To set the action's ttl, refer to alert_actions.conf.spec.

If the integer is followed by the letter 'p' Splunk interprets the ttl as a multiple of the scheduled search's period.

displayview Defines the default UI view name (not label) in which to load the results. Accessibility is subject to the user having sufficient permissions.
is_scheduled Indicates if this search is to be run on a schedule.
is_visible Indicates if this saved search appears in the visible saved search list.
max_concurrent The maximum number of concurrent instances of this search the scheduler is allowed to run.
next_scheduled_time The time when the scheduler runs this search again.
qualifiedSearch The exact search command for this saved search.
realtime_schedule Controls the way the scheduler computes the next execution time of a scheduled search. If this value is set to 1, the scheduler bases its determination of the next scheduled search execution time on the current time.

If this value is set to 0, the scheduler bases its determination of the next scheduled search on the last search execution time. This is called continuous scheduling. If set to 0, the scheduler never skips scheduled execution periods. However, the execution of the saved search might fall behind depending on the scheduler's load. Use continuous scheduling whenever you enable the summary index option.

If set to 1, the scheduler might skip some execution periods to make sure that the scheduler is executing the searches running over the most recent time range.

The scheduler tries to execute searches that have realtime_schedule set to 1 before it executes searches that have continuous scheduling (realtime_schedule = 0).

request.ui_dispatch_app A field used by Splunk UI to denote the app this search should be dispatched in.
request.ui_dispatch_view Specifies a field used by Splunk UI to denote the view this search should be displayed in.
restart_on_searchpeer_add Indicates whether to restart a real-time search managed by the scheduler when a search peer becomes available for this saved search.

Note: The peer can be a newly added peer or a peer that has been down and has become available.

run_on_startup Indicates whether this search runs when Splunk starts. If it does not run on startup, it runs at the next scheduled time.

Splunk recommends that you set run_on_startup to true for scheduled searches that populate lookup tables.

search Search expression to filter the response. The response matches field values against the search expression. For example:

search=foo matches any object that has "foo" as a substring in a field. search=field_name%3Dfield_value restricts the match to a single field. URI-encoding is required in this example.

vsid Defines the viewstate id associated with the UI view listed in 'displayview'.

Must match up to a stanza in viewstates.conf.

Example

Update MySavedSearch to enable email action and provide email addresses for the action. (The example for the POST operation for saved/searches creates MySavedSearch.)

URI-encode the search string if it contains any of the following characters: =, &, ?, %

Otherwise, these characters can be interpreted as part of the HTTP request. 


curl -k -u admin:pass https://localhost:8089/servicesNS/admin/search/saved/searches/MySavedSearch \
	-d actions=email \
	-d action.email.to="nobody@example.com, info@example.com" \
	-d search="my search here"



<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:s="http://dev.splunk.com/ns/rest"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>savedsearch</title>
  <id>https://localhost:8089/servicesNS/admin/search/saved/searches</id>
  <updated>2011-07-26T18:20:14-04:00</updated>
  <generator version="104601"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/servicesNS/admin/search/saved/searches/_new" rel="create"/>
  <link href="/servicesNS/admin/search/saved/searches/_reload" rel="_reload"/>
  <opensearch:totalResults>1</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
  <entry>
    <title>MySavedSearch</title>
    <id>https://localhost:8089/servicesNS/admin/search/saved/searches/MySavedSearch</id>
    <updated>2011-07-26T18:20:14-04:00</updated>
    <link href="/servicesNS/admin/search/saved/searches/MySavedSearch" rel="alternate"/>
    <author>
      <name>admin</name>
    </author>
    <link href="/servicesNS/admin/search/saved/searches/MySavedSearch" rel="list"/>
    <link href="/servicesNS/admin/search/saved/searches/MySavedSearch/_reload" rel="_reload"/>
    <link href="/servicesNS/admin/search/saved/searches/MySavedSearch" rel="edit"/>
    <link href="/servicesNS/admin/search/saved/searches/MySavedSearch" rel="remove"/>
    <link href="/servicesNS/admin/search/saved/searches/MySavedSearch/move" rel="move"/>
    <link href="/servicesNS/admin/search/saved/searches/MySavedSearch/disable" rel="disable"/>
    <link href="/servicesNS/admin/search/saved/searches/MySavedSearch/dispatch" rel="dispatch"/>
    <link href="/servicesNS/admin/search/saved/searches/MySavedSearch/history" rel="history"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="action.email">1</s:key>
        <s:key name="action.email.auth_password"></s:key>
        <s:key name="action.email.auth_username"></s:key>
        <s:key name="action.email.bcc"></s:key>
        <s:key name="action.email.cc"></s:key>
        <s:key name="action.email.command">
          <![CDATA[$action.email.preprocess_results{default=""}$ |
                    sendemail "server=$action.email.mailserver{default=localhost}$" "use_ssl=$action.email.use_ssl{default=false}$"
                    "use_tls=$action.email.use_tls{default=false}$" "to=$action.email.to$" "cc=$action.email.cc$"
                    "bcc=$action.email.bcc$" "from=$action.email.from{default=splunk@localhost}$"
                    "subject=$action.email.subject{recurse=yes}$" "format=$action.email.format{default=csv}$"
                    "sssummary=Saved Search [$name$]: $counttype$($results.count$)" "sslink=$results.url$"
                    "ssquery=$search$" "ssname=$name$" "inline=$action.email.inline{default=False}$"
                    "sendresults=$action.email.sendresults{default=False}$" "sendpdf=$action.email.sendpdf{default=False}$"
                    "pdfview=$action.email.pdfview$" "searchid=$search_id$"
                    "graceful=$graceful{default=True}$" maxinputs="$action.email.maxresults{default=10000}$"
                    maxtime="$action.email.maxtime{default=5m}$"]]>
        </s:key>
        <s:key name="action.email.format">html</s:key>
        <s:key name="action.email.from">splunk</s:key>
        <s:key name="action.email.hostname"></s:key>
        <s:key name="action.email.inline">0</s:key>
        <s:key name="action.email.mailserver">localhost</s:key>
        <s:key name="action.email.maxresults">10000</s:key>
        <s:key name="action.email.maxtime">5m</s:key>
        <s:key name="action.email.preprocess_results"></s:key>
        <s:key name="action.email.reportPaperOrientation">portrait</s:key>
        <s:key name="action.email.reportPaperSize">letter</s:key>
        <s:key name="action.email.reportServerEnabled">0</s:key>
        <s:key name="action.email.reportServerURL"></s:key>
        <s:key name="action.email.sendpdf">0</s:key>
        <s:key name="action.email.sendresults">0</s:key>
        <s:key name="action.email.subject">Splunk Alert: $name$</s:key>
        <s:key name="action.email.to">nobody@example.com,info@example.com</s:key>
        <s:key name="action.email.track_alert">1</s:key>
        <s:key name="action.email.ttl">86400</s:key>
        <s:key name="action.email.use_ssl">0</s:key>
        <s:key name="action.email.use_tls">0</s:key>
        <s:key name="action.populate_lookup">0</s:key>
        <s:key name="action.populate_lookup.command">copyresults dest="$action.populate_lookup.dest$"  sid="$search_id$"</s:key>
        <s:key name="action.populate_lookup.hostname"></s:key>
        <s:key name="action.populate_lookup.maxresults">10000</s:key>
        <s:key name="action.populate_lookup.maxtime">5m</s:key>
        <s:key name="action.populate_lookup.track_alert">0</s:key>
        <s:key name="action.populate_lookup.ttl">120</s:key>
        <s:key name="action.rss">0</s:key>
        <s:key name="action.rss.command">createrss "path=$name$.xml" "name=$name$" "link=$results.url$" "descr=Alert trigger: $name$, results.count=$results.count$ " "count=30" "graceful=$graceful{default=1}$" maxtime="$action.rss.maxtime{default=1m}$"</s:key>
        <s:key name="action.rss.hostname"></s:key>
        <s:key name="action.rss.maxresults">10000</s:key>
        <s:key name="action.rss.maxtime">1m</s:key>
        <s:key name="action.rss.track_alert">0</s:key>
        <s:key name="action.rss.ttl">86400</s:key>
        <s:key name="action.script">0</s:key>
        <s:key name="action.script.command">runshellscript "$action.script.filename$" "$results.count$" "$search$" "$search$" "$name$" "Saved Search [$name$] $counttype$($results.count$)" "$results.url$" "$deprecated_arg$" "$search_id$" "$results.file$" maxtime="$action.script.maxtime{default=5m}$"</s:key>
        <s:key name="action.script.hostname"></s:key>
        <s:key name="action.script.maxresults">10000</s:key>
        <s:key name="action.script.maxtime">5m</s:key>
        <s:key name="action.script.track_alert">1</s:key>
        <s:key name="action.script.ttl">600</s:key>
        <s:key name="action.summary_index">0</s:key>
        <s:key name="action.summary_index._name">summary</s:key>
        <s:key name="action.summary_index.command"><![CDATA[summaryindex spool=t uselb=t addtime=t index="$action.summary_index._name{required=yes}$" file="$name$_$#random$.stash_new" name="$name$" marker="$action.summary_index*{format=$KEY=\\\"$VAL\\\", key_regex="action.summary_index.(?!(?:command|inline|maxresults|maxtime|ttl|track_alert|(?:_.*))$)(.*)"}$"]]></s:key>
        <s:key name="action.summary_index.hostname"></s:key>
        <s:key name="action.summary_index.inline">1</s:key>
        <s:key name="action.summary_index.maxresults">10000</s:key>
        <s:key name="action.summary_index.maxtime">5m</s:key>
        <s:key name="action.summary_index.track_alert">0</s:key>
        <s:key name="action.summary_index.ttl">120</s:key>
        <s:key name="actions">email</s:key>
        <s:key name="alert.digest_mode">1</s:key>
        <s:key name="alert.expires">24h</s:key>
        <s:key name="alert.severity">3</s:key>
        <s:key name="alert.suppress"></s:key>
        <s:key name="alert.suppress.period"></s:key>
        <s:key name="alert.track">auto</s:key>
        <s:key name="alert_comparator"></s:key>
        <s:key name="alert_condition"></s:key>
        <s:key name="alert_threshold"></s:key>
        <s:key name="alert_type">always</s:key>
        <s:key name="cron_schedule"></s:key>
        <s:key name="description"></s:key>
        <s:key name="disabled">0</s:key>
        <s:key name="dispatch.buckets">0</s:key>
        <s:key name="dispatch.earliest_time"></s:key>
        <s:key name="dispatch.latest_time"></s:key>
        <s:key name="dispatch.lookups">1</s:key>
        <s:key name="dispatch.max_count">500000</s:key>
        <s:key name="dispatch.max_time">0</s:key>
        <s:key name="dispatch.reduce_freq">10</s:key>
        <s:key name="dispatch.rt_backfill">0</s:key>
        <s:key name="dispatch.spawn_process">1</s:key>
        <s:key name="dispatch.time_format">%FT%T.%Q%:z</s:key>
        <s:key name="dispatch.ttl">2p</s:key>
        <s:key name="displayview"></s:key>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="is_scheduled">0</s:key>
        <s:key name="is_visible">1</s:key>
        <s:key name="max_concurrent">1</s:key>
        <s:key name="next_scheduled_time"></s:key>
        <s:key name="qualifiedSearch">search  my seach here</s:key>
        <s:key name="realtime_schedule">1</s:key>
        <s:key name="request.ui_dispatch_app"></s:key>
        <s:key name="request.ui_dispatch_view"></s:key>
        <s:key name="restart_on_searchpeer_add">1</s:key>
        <s:key name="run_on_startup">0</s:key>
        <s:key name="search">my search here</s:key>
        <s:key name="vsid"></s:key>
      </s:dict>
    </content>
  </entry>
</feed>

saved/searches/{name}/acknowledge

POST saved/searches/{name}/acknowledge

Acknowledge the suppression of the alerts from this saved search and resume alerting. Action available only with POST

Request

No parameters for this request.

Response Codes

Status Code Description
200 Suppression was acknowledged successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
402 The Splunk license in use has disabled this feature.
403 Insufficient permissions to acknowledge the suppression.
404 Named save search does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.
503 This feature has been disabled in Splunk configuration files.

Returned Values

No values returned for this request.

Example

Acknowledge the suppression of an alert and resume alerting 


curl -k -u admin:pass \
	https://localhost:8089/servicesNS/admin/search/saved/searches/MyAlert/acknowledge -X POST



<feed xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>savedsearch</title>
  <id>https://localhost:8089/servicesNS/admin/search/saved/searches</id>
  <updated>2011-07-26T18:31:07-04:00</updated>
  <generator version="104601"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/servicesNS/admin/search/saved/searches/_new" rel="create"/>
  <link href="/servicesNS/admin/search/saved/searches/_reload" rel="_reload"/>
  <opensearch:totalResults>0</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
</feed>

saved/searches/{name}/dispatch

POST saved/searches/{name}/dispatch

Dispatch the saved search just like the scheduler would. Action available only through POST. The following optional arguments are accepted:

dispatch.now: [time] dispatch the search as if it this was the current time
dispatch.*: any dispatch.* field of the search can be overriden
now: [time] deprecated, same as dispatch.now use that instead
trigger_actions: [bool] whether to trigger alert actions
force_dispatch: [bool] should a new search be started even if another instance of this search is already running

Request

No parameters for this request.

Response Codes

Status Code Description
200 Dispatched the saved search successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
402 The Splunk license in use has disabled this feature.
403 Insufficient permissions to dispatch the saved search.
404 Named save search does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.
503 This feature has been disabled in Splunk configuration files.

Returned Values

No values returned for this request.

Example

Dispatch the saved search and trigger alert actions. 


curl -k -u admin:pass \
	https://localhost:8089/servicesNS/admin/search/saved/searches/MySavedSearch/dispatch \
	-d trigger_actions=1



<?xml version='1.0' encoding='UTF-8'?>
<response><sid>admin__admin__search__MySavedSearch_at_1311797437_d831d980832e3e89</sid></response>

saved/searches/{name}/history

GET saved/searches/{name}/history

Get a list of available search jobs created from this saved search

Request

No parameters for this request.

Response Codes

Status Code Description
200 Retrieved the dispatch history successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to retrieve dispatch history for this saved search.
404 Named save search does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
earliest_time The earliest time a search job is configured to start.
isDone Indicates if the search has completed.
isFinalized Indicates if the search was finalized (stopped before completion).
isRealTimeSearch Indicates if the search is a real time search.
isSaved Indicates if the search is saved idefinitely.
isScheduled Indicates if the search is a scheduled search.
isZombie Indicates if the process running the search is dead, but with the search not finished.
latest_time The latest time a search job is configured to start.
ttl The time to live, or time before the search job expires after it completes.

Example

Retrive the dispatch history of a scheduled search. 


curl -k -u admin:pass \
	https://localhost:8089/servicesNS/admin/search/saved/searches/MySavedSearch/history



<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:s="http://dev.splunk.com/ns/rest"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>MySavedSearch</title>
  <id>https://localhost:8089/servicesNS/admin/search/saved/searches</id>
  <updated>2011-07-26T18:13:20-04:00</updated>
  <generator version="104601"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/servicesNS/admin/search/saved/searches/_new" rel="create"/>
  <link href="/servicesNS/admin/search/saved/searches/_reload" rel="_reload"/>
  <opensearch:totalResults>2</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
  <entry>
    <title>scheduler__admin__search_MySavedSearch_at_1311718380_4270ba99c46128d2</title>
    <id>https://localhost:8089/servicesNS/nobody/search/search/jobs/scheduler__admin__search_MySavedSearch_at_1311718380_4270ba99c46128d2</id>
    <updated>2011-07-26T18:13:18-04:00</updated>
    <link href="/servicesNS/nobody/search/search/jobs/scheduler__admin__search_MySavedSearch_at_1311718380_4270ba99c46128d2" rel="alternate"/>
    <author>
      <name>admin</name>
    </author>
    <published>2011-07-26T18:13:01-04:00</published>
    <link href="/servicesNS/nobody/search/search/jobs/scheduler__admin__search_MySavedSearch_at_1311718380_4270ba99c46128d2" rel="list"/>
    <link href="/servicesNS/nobody/search/search/jobs/scheduler__admin__search_MySavedSearch_at_1311718380_4270ba99c46128d2/_reload" rel="_reload"/>
    <link href="/servicesNS/nobody/search/search/jobs/scheduler__admin__search_MySavedSearch_at_1311718380_4270ba99c46128d2" rel="edit"/>
    <link href="/servicesNS/nobody/search/search/jobs/scheduler__admin__search_MySavedSearch_at_1311718380_4270ba99c46128d2" rel="remove"/>
    <content type="text/xml">
      <s:dict>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="isDone">1</s:key>
        <s:key name="isFinalized">0</s:key>
        <s:key name="isRealTimeSearch">0</s:key>
        <s:key name="isSaved">0</s:key>
        <s:key name="isScheduled">1</s:key>
        <s:key name="isZombie">0</s:key>
        <s:key name="ttl">86382</s:key>
      </s:dict>
    </content>
  </entry>
  <entry>
    <title>scheduler__admin__search_MySavedSearch_at_1311717060_7d9aa142eba2437b</title>
    <id>https://localhost:8089/servicesNS/nobody/search/search/jobs/scheduler__admin__search_MySavedSearch_at_1311717060_7d9aa142eba2437b</id>
    <updated>2011-07-26T17:51:23-04:00</updated>
    <link href="/servicesNS/nobody/search/search/jobs/scheduler__admin__search_MySavedSearch_at_1311717060_7d9aa142eba2437b" rel="alternate"/>
    <author>
      <name>admin</name>
    </author>
    <published>2011-07-26T17:51:01-04:00</published>
    <link href="/servicesNS/nobody/search/search/jobs/scheduler__admin__search_MySavedSearch_at_1311717060_7d9aa142eba2437b" rel="list"/>
    <link href="/servicesNS/nobody/search/search/jobs/scheduler__admin__search_MySavedSearch_at_1311717060_7d9aa142eba2437b/_reload" rel="_reload"/>
    <link href="/servicesNS/nobody/search/search/jobs/scheduler__admin__search_MySavedSearch_at_1311717060_7d9aa142eba2437b" rel="edit"/>
    <link href="/servicesNS/nobody/search/search/jobs/scheduler__admin__search_MySavedSearch_at_1311717060_7d9aa142eba2437b" rel="remove"/>
    <content type="text/xml">
      <s:dict>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="isDone">1</s:key>
        <s:key name="isFinalized">0</s:key>
        <s:key name="isRealTimeSearch">0</s:key>
        <s:key name="isSaved">0</s:key>
        <s:key name="isScheduled">1</s:key>
        <s:key name="isZombie">0</s:key>
        <s:key name="ttl">85062</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

saved/searches/{name}/scheduled_times

GET saved/searches/{name}/scheduled_times

Returns the scheduled times for a saved search. Specify a time range for the data returned using earliest_time and latest_time parameters.

Request

No parameters for this request.

Response Codes

Status Code Description
200 Scheduled times returned successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to get scheduled times.
404 Scheduled times do not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
action.email Indicates the state of the email action.
action.email.auth_password The password to use when authenticating with the SMTP server. Normally this value will be set when editing the email settings, however you can set a clear text password here that is encrypted on the next Splunk restart.

Defaults to empty string.

action.email.auth_username The username to use when authenticating with the SMTP server. If this is empty string, no authentication is attempted. Defaults to empty string.

Note: Your SMTP server might reject unauthenticated emails.

action.email.pdfview The name of the view to deliver if sendpdf is enabled.
action.email.subject Specifies an email subject.

Defaults to SplunkAlert-<savedsearchname>.

action.email.to List of recipient email addresses. Required if this search is scheduled and the email alert action is enabled.
action.summary_index The state of the summary index action.
action.summary_index._name The state of the summary index action.
actions Actions triggerd by this alert.
alert.digest_mode Indicates if Splunk applies the alert actions to the entire result set or on each individual result.
alert.expires Sets the period of time to show the alert in the dashboard. Defaults to 24h.

Uses [number][time-unit] to specify a time. For example: 60 = 60 seconds, 1m = 1 minute, 1h = 60 minutes = 1 hour.

alert.severity Valid values: (1 | 2 | 3 | 4 | 5 | 6)

Sets the alert severity level.

Valid values are:

1 DEBUG 2 INFO 3 WARN 4 ERROR 5 SEVERE 6 FATAL

alert.suppress Indicates whether alert suppression is enabled for this schedules search.
alert.suppress.fields Fields to use for suppression when doing per result alerting. Required if suppression is turned on and per result alerting is enabled.
alert.suppress.period Specifies the suppresion period. Only valid if alert.supress is enabled.

Use [number][time-unit] to specify a time. For example: 60 = 60 seconds, 1m = 1 minute, 1h = 60 minutes = 1 hour.

alert.track Specifies whether to track the actions triggered by this scheduled search.

auto - determine whether to track or not based on the tracking setting of each action, do not track scheduled searches that always trigger actions.

true - force alert tracking.

false - disable alert tracking for this search.

alert_comparator Valid values are: Integer[%]

Specifies the value to compare (see alert_comparator) before triggering the alert actions. If expressed as a percentage, indicates value to use when alert_comparator is set to "rises by perc" or "drops by perc."

alert_condition A conditional search that is evaluated against the results of the saved search. Defaults to an empty string.

Alerts are triggered if the specified search yields a non-empty search result list.

Note: If you specify an alert_condition, do not set counttype, relation, or quantity.

alert_threshold Valid values are: Integer[%]

Specifies the value to compare (see alert_comparator) before triggering the alert actions. If expressed as a percentage, indicates value to use when alert_comparator is set to "rises by perc" or "drops by perc."

alert_type What to base the alert on, overriden by alert_condition if it is specified. Valid values are: always, custom, number of events, number of hosts, number of sources.
cron_schedule The cron schedule to execute this search. For example: */5 * * * * causes the search to execute every 5 minutes.

cron lets you use standard cron notation to define your scheduled search interval. In particular, cron can accept this type of notation: 00,20,40 * * * *, which runs the search every hour at hh:00, hh:20, hh:40. Along the same lines, a cron of 03,23,43 * * * * runs the search every hour at hh:03, hh:23, hh:43.

Splunk recommends that you schedule your searches so that they are staggered over time. This reduces system load. Running all of them every 20 minutes (*/20) means they would all launch at hh:00 (20, 40) and might slow your system every 20 minutes.

Valid values: cron string

description Description of the saved search.
disabled Indicates if this saved search is disabled.
dispatch.buckets The maximum number of timeline buckets.
dispatch.earliest_time A time string that specifies the earliest time for this search. Can be a relative or absolute time.

If this value is an absolute time, use the dispatch.time_format to format the value.

dispatch.latest_time A time string that specifies the latest time for this saved search. Can be a relative or absolute time.

If this value is an absolute time, use the dispatch.time_format to format the value.

dispatch.lookups Indicates if lookups are enabled for this search.
dispatch.max_count The maximum number of results before finalizing the search.
dispatch.max_time Indicates the maximum amount of time (in seconds) before finalizing the search
earliest_time For scheduled searches display all the scheduled times starting from this time.
is_scheduled Indicates if this search is to be run on a schedule.
is_visible Indicates if this saved search appears in the visible saved search list.
latest_time A time string that specifies the latest time for this saved search. Can be a relative or absolute time.

If this value is an absolute time, use the dispatch.time_format to format the value.

max_concurrent The maximum number of concurrent instances of this search the scheduler is allowed to run.
next_scheduled_time The time when the scheduler runs this search again.
qualifiedSearch The exact search command for this saved search.
realtime_schedule Controls the way the scheduler computes the next execution time of a scheduled search. If this value is set to 1, the scheduler bases its determination of the next scheduled search execution time on the current time.

If this value is set to 0, the scheduler bases its determination of the next scheduled search on the last search execution time. This is called continuous scheduling. If set to 0, the scheduler never skips scheduled execution periods. However, the execution of the saved search might fall behind depending on the scheduler's load. Use continuous scheduling whenever you enable the summary index option.

If set to 1, the scheduler might skip some execution periods to make sure that the scheduler is executing the searches running over the most recent time range.

The scheduler tries to execute searches that have realtime_schedule set to 1 before it executes searches that have continuous scheduling (realtime_schedule = 0).

request.ui_dispatch_app A field used by Splunk Web to denote the app this search should be dispatched in.
request.ui_dispatch_view A field used by Splunk Web to denote the app this search should be dispatched in.
restart_on_searchpeer_add Indicates whether to restart a real-time search managed by the scheduler when a search peer becomes available for this saved search.

Note: The peer can be a newly added peer or a peer that has been down and has become available.

run_on_startup Indicates whether this search runs when Splunk starts. If it does not run on startup, it runs at the next scheduled time.

Splunk recommends that you set run_on_startup to true for scheduled searches that populate lookup tables.

scheduled_times The times when the scheduler runs the search.
search Search expression to filter the response. The response matches field values against the search expression. For example:

search=foo matches any object that has "foo" as a substring in a field. search=field_name%3Dfield_value restricts the match to a single field. URI-encoding is required in this example.

vsid The viewstate id associated with the Splunk Web view listed in 'displayview'.

Matches to a stanza in viewstates.conf.

Example

Returns information about a saved search, including information about the scheduled times for emailing a PDF of the scheduled view.

The response to this example has many keys elided to show most of the entries relevant to the scheduled times. 

curl -k -u admin:pass \
	https://localhost:8089/services/saved/searches/_ScheduledView__dashboard_live/scheduled_times --get \
	-d earliest_time=-5h \
	-d latest_time=-3h

<feed xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>savedsearch</title>
  <id>https://localhost:8089/services/saved/searches</id>
  <updated>2011-12-02T11:12:55-08:00</updated>
  <generator version="108769"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/saved/searches/_new" rel="create"/>
  <link href="/services/saved/searches/_reload" rel="_reload"/>
  <opensearch:totalResults>1</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
  <entry>
    <title>_ScheduledView__dashboard_live</title>
    <id>https://localhost:8089/servicesNS/admin/search/saved/searches/_ScheduledView__dashboard_live</id>
    <updated>2011-12-02T11:12:55-08:00</updated>
    <link href="/servicesNS/admin/search/saved/searches/_ScheduledView__dashboard_live" rel="alternate"/>
    <author>
      <name>admin</name>
    </author>
    <!-- opensearch nodes elided for brevity. -->
    <content type="text/xml">
      <s:dict>
        <s:key name="action.email">1</s:key>
        <s:key name="action.email.auth_password">$1$o2rN8S6m+0YB</s:key>
        <s:key name="action.email.auth_username">vgenovese</s:key>
        . . .
        <s:key name="action.email.pdfview">dashboard_live</s:key>
        . . .
        <s:key name="action.email.subject">Splunk Alert: $name$</s:key>
        <s:key name="action.email.to">vgenove@example.com</s:key>
        . . .
         <s:key name="action.summary_index">0</s:key>
        <s:key name="action.summary_index._name">summary</s:key>
        . . .
        <s:key name="actions">email</s:key>
        <s:key name="alert.digest_mode">1</s:key>
        <s:key name="alert.expires">24h</s:key>
        <s:key name="alert.severity">3</s:key>
        <s:key name="alert.suppress"></s:key>
        <s:key name="alert.suppress.fields"></s:key>
        <s:key name="alert.suppress.period"></s:key>
        <s:key name="alert.track">auto</s:key>
        <s:key name="alert_comparator"></s:key>
        <s:key name="alert_condition"></s:key>
        <s:key name="alert_threshold"></s:key>
        <s:key name="alert_type">always</s:key>
        <s:key name="cron_schedule">*/30 * * * *</s:key>
        <s:key name="description">scheduled search for view name=dashboard_live</s:key>
        <s:key name="disabled">0</s:key>
        <s:key name="dispatch.buckets">0</s:key>
        <s:key name="dispatch.earliest_time">1</s:key>
        <s:key name="dispatch.latest_time">2</s:key>
        <s:key name="dispatch.lookups">1</s:key>
        <s:key name="dispatch.max_count">500000</s:key>
        <s:key name="dispatch.max_time">0</s:key>
        . . .
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="is_scheduled">1</s:key>
        <s:key name="is_visible">0</s:key>
        <s:key name="max_concurrent">1</s:key>
        <s:key name="next_scheduled_time">2011-12-02 11:30:00 PST</s:key>
        <s:key name="qualifiedSearch"> noop</s:key>
        <s:key name="realtime_schedule">1</s:key>
        <s:key name="request.ui_dispatch_app"></s:key>
        <s:key name="request.ui_dispatch_view"></s:key>
        <s:key name="restart_on_searchpeer_add">1</s:key>
        <s:key name="run_on_startup">0</s:key>
        <s:key name="scheduled_times"><s:list><s:item>1322836200</s:item><s:item>1322838000</s:item><s:item>1322839800</s:item><s:item>1322841600</s:item></s:list></s:key>
        <s:key name="search">| noop</s:key>
        <s:key name="vsid"></s:key>
      </s:dict>
    </content>
  </entry>
</feed>

saved/searches/{name}/suppress

GET saved/searches/{name}/suppress

Check the suppression state of alerts from this saved search.

Request

No parameters for this request.

Response Codes

Status Code Description
200 Retrieved/updated the suppression state successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to retrieve/update the suppression state.
404 Named save search does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
earliest_time For scheduled searches display all the scheduled times starting from this time.
expiration Sets the period of time to show the alert in the dashboard. Defaults to 24h.

Uses [number][time-unit] to specify a time. For example: 60 = 60 seconds, 1m = 1 minute, 1h = 60 minutes = 1 hour.

latest_time A time string that specifies the latest time for this saved search. Can be a relative or absolute time.

If this value is an absolute time, use the dispatch.time_format to format the value.

suppressed Indicates if alert suppression is enabled for this search.
suppressionKey A combination of all the values of the suppression fields (or the combinations MD5), if fields were specified.

Example

Retrieve or update the suppression state for the given alert, MySavedSeach 


curl -k -u admin:pass \
	https://localhost:8089/servicesNS/admin/search/saved/searches/MySavedSearch/suppress



<feed xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>savedsearch</title>
  <id>https://localhost:8089/servicesNS/admin/search/saved/searches</id>
  <updated>2011-07-26T18:22:51-04:00</updated>
  <generator version="104601"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/servicesNS/admin/search/saved/searches/_new" rel="create"/>
  <link href="/servicesNS/admin/search/saved/searches/_reload" rel="_reload"/>
  <opensearch:totalResults>1</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
  <entry>
    <title>MySavedSearch</title>
    <id>https://localhost:8089/servicesNS/admin/search/saved/searches/MySavedSearch</id>
    <updated>2011-07-26T18:22:51-04:00</updated>
    <link href="/servicesNS/admin/search/saved/searches/MySavedSearch" rel="alternate"/>
    <author>
      <name>admin</name>
    </author>
    <link href="/servicesNS/admin/search/saved/searches/MySavedSearch" rel="list"/>
    <link href="/servicesNS/admin/search/saved/searches/MySavedSearch/_reload" rel="_reload"/>
    <link href="/servicesNS/admin/search/saved/searches/MySavedSearch" rel="edit"/>
    <link href="/servicesNS/admin/search/saved/searches/MySavedSearch" rel="remove"/>
    <content type="text/xml">
      <s:dict>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="expiration">13811</s:key>
        <s:key name="suppressed">1</s:key>
        <s:key name="suppressionKey">admin;search;MySavedSearch;;</s:key>
      </s:dict>
    </content>
  </entry>
</feed>


scheduled/views

Allows for management of scheduled (for pdf delivery) views. Scheduled views are dummy/noop scheduled saved searches that email a pdf version of a view

GET scheduled/views

Lists all scheduled view objects

Request

Name Type Required Default Description
count Number 30 Indicates the maximum number of entries to return. To return all entries, specify 0.
offset Number 0 Index for first item to return.
search String Search expression to filter the response. The response matches field values against the search expression. For example:

search=foo matches any object that has "foo" as a substring in a field. search=field_name%3Dfield_value restricts the match to a single field. URI-encoding is required in this example.

sort_dir Enum asc Valid values: (asc | desc)

Indicates whether to sort returned entries in ascending or descending order.

sort_key String name Field to use for sorting.
sort_mode Enum auto Valid values: (auto | alpha | alpha_case | num)

Indicates the collating sequence for sorting the returned entries. auto: If all values of the field are numbers, collate numerically. Otherwise, collate alphabetically. alpha: Collate alphabetically. alpha_case: Collate alphabetically, case-sensitive. num: Collate numerically.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view scheduled view.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
action.email Indicates the state of the email action.
action.email.pdfview Name of the view to send as a PDF.
action.email.sendpdf Indicates whether to create and send the results as a PDF.
action.email.sendresults Indicates whether the search results are included in the email. The results can be attached or inline.
action.email.to List of recipient email addresses. Required if the email alert action is enabled.
action.email.ttl Specifies the minimum time-to-live in seconds of the search artifacts if this action is triggered. If p follows <Integer>, int is the number of scheduled periods. Defaults to 86400 (24 hours).

If no actions are triggered, the artifacts have their ttl determined by dispatch.ttl in savedsearches.conf.

Valid values are Integer[p].

cron_schedule The cron schedule to use for delivering the view. Scheduled views are dummy/noop scheduled saved searches that email a pdf version of a view

For example: */5 * * * * causes the search to execute every 5 minutes.

cron lets you use standard cron notation to define your scheduled search interval. In particular, cron can accept this type of notation: 00,20,40 * * * *, which runs the search every hour at hh:00, hh:20, hh:40. Along the same lines, a cron of 03,23,43 * * * * runs the search every hour at hh:03, hh:23, hh:43.

Splunk recommends that you schedule your searches so that they are staggered over time. This reduces system load. Running all of them every 20 minutes (*/20) means they would all launch at hh:00 (20, 40) and might slow your system every 20 minutes.

description Description of this scheduled view object.
disabled Indicates if the scheduled view is disabled.
is_scheduled Indicates if PDF delivery of this view is scheduled.
next_scheduled_time The next time when the view is delivered.

Example

List all scheduled views 


curl -k -u admin:pass https://localhost:8089/services/scheduled/views



<feed xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>scheduledviews</title>
  <id>https://localhost:8089/servicesNS/admin/search/admin/scheduledviews</id>
  <updated>2011-07-27T16:27:55-04:00</updated>
  <generator version="104601"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/servicesNS/admin/search/admin/scheduledviews/_reload" rel="_reload"/>
  <opensearch:totalResults>1</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
  <entry>
    <title>_ScheduledView__MyView</title>
    <id>https://localhost:8089/servicesNS/admin/search/admin/scheduledviews/_ScheduledView__MyView</id>
    <updated>2011-07-27T16:27:55-04:00</updated>
    <link href="/servicesNS/admin/search/admin/scheduledviews/_ScheduledView__MyView" rel="alternate"/>
    <author>
      <name>admin</name>
    </author>
    <link href="/servicesNS/admin/search/admin/scheduledviews/_ScheduledView__MyView" rel="list"/>
    <link href="/servicesNS/admin/search/admin/scheduledviews/_ScheduledView__MyView/_reload" rel="_reload"/>
    <link href="/servicesNS/admin/search/admin/scheduledviews/_ScheduledView__MyView" rel="edit"/>
    <link href="/servicesNS/admin/search/admin/scheduledviews/_ScheduledView__MyView" rel="remove"/>
    <link href="/servicesNS/admin/search/admin/scheduledviews/_ScheduledView__MyView/move" rel="move"/>
    <link href="/servicesNS/admin/search/admin/scheduledviews/_ScheduledView__MyView/disable" rel="disable"/>
    <link href="/servicesNS/admin/search/admin/scheduledviews/_ScheduledView__MyView/dispatch" rel="dispatch"/>
    <link href="/servicesNS/admin/search/admin/scheduledviews/_ScheduledView__MyView/history" rel="history"/>
    <link href="/servicesNS/admin/search/admin/scheduledviews/_ScheduledView__MyView/notify" rel="notify"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="action.email">1</s:key>
        <s:key name="action.email.pdfview">MyView</s:key>
        <s:key name="action.email.sendpdf">1</s:key>
        <s:key name="action.email.sendresults"></s:key>
        <s:key name="action.email.to">email@example.com</s:key>
        <s:key name="action.email.ttl">10</s:key>
        <s:key name="cron_schedule">* * * * *</s:key>
        <s:key name="description">scheduled search for view name=MyView</s:key>
        <s:key name="disabled">0</s:key>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="is_scheduled">1</s:key>
        <s:key name="next_scheduled_time">2011-07-27 16:28:00 EDT</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

scheduled/views/{name}

DELETE scheduled/views/{name}

Delete a scheduled view

Request

No parameters for this request.

Response Codes

Status Code Description
200 Deleted successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to delete scheduled view.
404 Scheduled view does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

No values returned for this request.

Example

Delete MyView scheduled view 

curl -k -u admin:pass --request DELETE \
	https://localhost:8089/servicesNS/admin/search/scheduled/views/MyView



<feed xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>scheduledviews</title>
  <id>https://localhost:8089/servicesNS/admin/search/admin/scheduledviews</id>
  <updated>2011-07-27T16:16:02-04:00</updated>
  <generator version="104601"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/servicesNS/admin/search/admin/scheduledviews/_reload" rel="_reload"/>
  <opensearch:totalResults>0</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
</feed>

GET scheduled/views/{name}

List one scheduled view object

Request

No parameters for this request.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view scheduled view.
404 Scheduled view does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
action.email Indicates the sate of the email action.
action.email.auth_password The password to use when authenticating with the SMTP server. Normally this value will be set when editing the email settings, however you can set a clear text password here and it will be encrypted on the next Splunk restart.

Defaults to empty string.

action.email.auth_username The username to use when authenticating with the SMTP server. If this is empty string, no authentication is attempted. Defaults to empty string.

Note: Your SMTP server might reject unauthenticated emails.

action.email.bcc "BCC email address to use if action.email is enabled.
action.email.cc CC email address to use if action.email is enabled.
action.email.command The search command (or pipeline) which is responsible for executing the action.

Generally the command is a template search pipeline which is realized with values from the saved search. To reference saved search field values wrap them in $, for example to reference the savedsearch name use $name$, to reference the search use $search$.

action.email.format Specify the format of text in the email. This value also applies to any attachments.<

Valid values: (plain | html | raw | csv)

plain indicates plain text.

action.email.from Email address from which the email action originates.

Defaults to splunk@$LOCALHOST or whatever value is set in alert_actions.conf.

action.email.hostname Sets the hostname used in the web link (url) sent in email actions.

This value accepts two forms:

hostname (for example, splunkserver, splunkserver.example.com)

protocol://hostname:port (for example, http://splunkserver:8000, https://splunkserver.example.com:443)

When this value is a simple hostname, the protocol and port which are configured within splunk are used to construct the base of the url.

When this value begins with 'http://', it is used verbatim. NOTE: This means the correct port must be specified if it is not the default port for http or https. This is useful in cases when the Splunk server is not aware of how to construct an externally referencable url, such as SSO environments, other proxies, or when the Splunk server hostname is not generally resolvable.

Defaults to current hostname provided by the operating system, or if that fails "localhost". When set to empty, default behavior is used.

action.email.inline Indicates whether the search results are contained in the body of the email.

Results can be either inline or attached to an email. See action.email.sendresults.

action.email.mailserver Set the address of the MTA server to be used to send the emails.

Defaults to <LOCALHOST> (or whatever is set in alert_actions.conf).

action.email.maxresults Sets the global maximum number of search results to send when action.email is enabled.
action.email.maxtime Specifies the maximum amount of time the execution of an email action takes before the action is aborted.
action.email.pdfview The name of the view to deliver if sendpdf is enabled.
action.email.preprocess_results Search string to preprocess results before emailing them. Defaults to empty string (no preprocessing).

Usually the preprocessing consists of filtering out unwanted internal fields.

action.email.reportPaperOrientation Specifies the paper orientation: portrait or landscape.
action.email.reportPaperSize Specifies the paper size for PDFs. Defaults to letter.

Valid values: (letter | legal | ledger | a2 | a3 | a4 | a5)

action.email.reportServerEnabled Indicates whether the PDF server is enabled.
action.email.reportServerURL The URL of the PDF report server, if one is set up and available on the network.

For a default locally installed report server, the URL is http://localhost:8091/

action.email.sendpdf Indicates whether to create and send the results as a PDF.
action.email.sendresults Indicates whether to attach the search results in the email.

Results can be either attached or inline. See action.email.inline.

action.email.subject Specifies the email subject.

Defaults to SplunkAlert-<savedsearchname>.

action.email.to List of recipient email addresses. Required if this search is scheduled and the email alert action is enabled.
action.email.track_alert Indicates whether the execution of this action signifies a trackable alert.
action.email.ttl Specifies the minimum time-to-live in seconds of the search artifacts if this action is triggered. If p follows <Integer>, int is the number of scheduled periods. Defaults to 86400 (24 hours).

If no actions are triggered, the artifacts have their ttl determined by dispatch.ttl in savedsearches.conf.

Valid values are Integer[p].

action.email.use_ssl Indicates whether to use SSL when communicating with the SMTP server
action.email.use_tls Indicates whether to use TLS (transport layer security) when communicating with the SMTP server (starttls).
cron_schedule The cron schedule to execute this search. For example: */5 * * * * causes the search to execute every 5 minutes.

cron lets you use standard cron notation to define your scheduled search interval. In particular, cron can accept this type of notation: 00,20,40 * * * *, which runs the search every hour at hh:00, hh:20, hh:40. Along the same lines, a cron of 03,23,43 * * * * runs the search every hour at hh:03, hh:23, hh:43.

Splunk recommends that you schedule your searches so that they are staggered over time. This reduces system load. Running all of them every 20 minutes (*/20) means they would all launch at hh:00 (20, 40) and might slow your system every 20 minutes.

Valid values: cron string

description Description of this saved search for this view.
disabled Indicates if the saved search for this view is disabled.
eai:attributes See Accessing Splunk resources
is_scheduled Indicates if this search is to be run on a schedule.
next_scheduled_time The next time when the view is delivered.

Example

View the details of the MyView scheduled view 

curl -k -u admin:pass https://localhost:8089/servicesNS/admin/search/scheduled/views/MyView



<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:s="http://dev.splunk.com/ns/rest"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>scheduledviews</title>
  <id>https://localhost:8089/servicesNS/admin/search/scheduled/views</id>
  <updated>2011-07-27T17:12:11-04:00</updated>
  <generator version="104601"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/servicesNS/admin/search/scheduled/views/_reload" rel="_reload"/>
  <opensearch:totalResults>1</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
  <entry>
    <title>_ScheduledView__MyView</title>
    <id>https://localhost:8089/servicesNS/admin/search/scheduled/views/_ScheduledView__MyView</id>
    <updated>2011-07-27T17:12:11-04:00</updated>
    <link href="/servicesNS/admin/search/scheduled/views/_ScheduledView__MyView" rel="alternate"/>
    <author>
      <name>admin</name>
    </author>
    <link href="/servicesNS/admin/search/scheduled/views/_ScheduledView__MyView" rel="list"/>
    <link href="/servicesNS/admin/search/scheduled/views/_ScheduledView__MyView/_reload" rel="_reload"/>
    <link href="/servicesNS/admin/search/scheduled/views/_ScheduledView__MyView" rel="edit"/>
    <link href="/servicesNS/admin/search/scheduled/views/_ScheduledView__MyView" rel="remove"/>
    <link href="/servicesNS/admin/search/scheduled/views/_ScheduledView__MyView/move" rel="move"/>
    <link href="/servicesNS/admin/search/scheduled/views/_ScheduledView__MyView/disable" rel="disable"/>
    <link href="/servicesNS/admin/search/scheduled/views/_ScheduledView__MyView/dispatch" rel="dispatch"/>
    <link href="/servicesNS/admin/search/scheduled/views/_ScheduledView__MyView/history" rel="history"/>
    <link href="/servicesNS/admin/search/scheduled/views/_ScheduledView__MyView/notify" rel="notify"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="action.email">1</s:key>
        <s:key name="action.email.auth_password"></s:key>
        <s:key name="action.email.auth_username"></s:key>
        <s:key name="action.email.bcc"></s:key>
        <s:key name="action.email.cc"></s:key>
        <s:key name="action.email.command">
          <![CDATA[$action.email.preprocess_results{default=""}$ |
                   sendemail "server=$action.email.mailserver{default=localhost}$" "use_ssl=$action.email.use_ssl{default=false}$"
                   "use_tls=$action.email.use_tls{default=false}$" "to=$action.email.to$" "cc=$action.email.cc$"
                   "bcc=$action.email.bcc$" "from=$action.email.from{default=splunk@localhost}$"
                   "subject=$action.email.subject{recurse=yes}$" "format=$action.email.format{default=csv}$"
                   "sssummary=Saved Search [$name$]: $counttype$($results.count$)" "sslink=$results.url$"
                   "ssquery=$search$" "ssname=$name$" "inline=$action.email.inline{default=False}$"
                   "sendresults=$action.email.sendresults{default=False}$" "sendpdf=$action.email.sendpdf{default=False}$"
                   "pdfview=$action.email.pdfview$" "searchid=$search_id$" "graceful=$graceful{default=True}$"
                   maxinputs="$action.email.maxresults{default=10000}$" maxtime="$action.email.maxtime{default=5m}$"]]>
        </s:key>
        <s:key name="action.email.format">html</s:key>
        <s:key name="action.email.from">splunk</s:key>
        <s:key name="action.email.hostname"></s:key>
        <s:key name="action.email.inline">0</s:key>
        <s:key name="action.email.mailserver">localhost</s:key>
        <s:key name="action.email.maxresults">10000</s:key>
        <s:key name="action.email.maxtime">5m</s:key>
        <s:key name="action.email.pdfview">MyView</s:key>
        <s:key name="action.email.preprocess_results"></s:key>
        <s:key name="action.email.reportPaperOrientation">portrait</s:key>
        <s:key name="action.email.reportPaperSize">letter</s:key>
        <s:key name="action.email.reportServerEnabled">0</s:key>
        <s:key name="action.email.reportServerURL"></s:key>
        <s:key name="action.email.sendpdf">1</s:key>
        <s:key name="action.email.sendresults">0</s:key>
        <s:key name="action.email.subject">Splunk Alert: $name$</s:key>
        <s:key name="action.email.to">info@example.com</s:key>
        <s:key name="action.email.track_alert">1</s:key>
        <s:key name="action.email.ttl">10</s:key>
        <s:key name="action.email.use_ssl">0</s:key>
        <s:key name="action.email.use_tls">0</s:key>
        <s:key name="cron_schedule">* * * * *</s:key>
        <s:key name="description">scheduled search for view name=MyView</s:key>
        <s:key name="disabled">0</s:key>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="eai:attributes">
          <s:dict>
            <s:key name="optionalFields">
              <s:list>
                <s:item>description</s:item>
                <s:item>disabled</s:item>
                <s:item>next_scheduled_time</s:item>
              </s:list>
            </s:key>
            <s:key name="requiredFields">
              <s:list>
                <s:item>action.email.to</s:item>
                <s:item>cron_schedule</s:item>
                <s:item>is_scheduled</s:item>
              </s:list>
            </s:key>
            <s:key name="wildcardFields">
              <s:list><s:item>action\.email.*</s:item></s:list>
            </s:key>
          </s:dict>
        </s:key>
        <s:key name="is_scheduled">1</s:key>
        <s:key name="next_scheduled_time">2011-07-27 17:13:00 EDT</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

POST scheduled/views/{name}

Edit a scheduled view, e.g. change schedule, enable disable schedule etc

Request

Name Type Required Default Description
action.email.to String
✓
 Comma or semicolon separated list of email addresses to send the view to
cron_schedule String
✓
 The cron schedule to use for delivering the view. Scheduled views are dummy/noop scheduled saved searches that email a pdf version of a view.

For example: */5 * * * * causes the search to execute every 5 minutes.

cron lets you use standard cron notation to define your scheduled search interval. In particular, cron can accept this type of notation: 00,20,40 * * * *, which runs the search every hour at hh:00, hh:20, hh:40. Along the same lines, a cron of 03,23,43 * * * * runs the search every hour at hh:03, hh:23, hh:43.

Splunk recommends that you schedule your searches so that they are staggered over time. This reduces system load. Running all of them every 20 minutes (*/20) means they would all launch at hh:00 (20, 40) and might slow your system every 20 minutes.

is_scheduled Boolean
✓
 Whether this pdf delivery should be scheduled
action.email* String Wildcard argument that accepts any email action.
description String User readable description of this scheduled view object
disabled Boolean 0 Whether this object is enabled or disabled
next_scheduled_time String The next time when the view will be delivered. Ignored on edit, here only for backwards compatability

Response Codes

Status Code Description
200 Updated successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
402 The Splunk license in use has disabled this feature.
403 Insufficient permissions to edit scheduled view.
404 Scheudled view does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.
503 This feature has been disabled in Splunk configuration files.

Returned Values

Attribute Description
action.email Indicates the status of the email action.
action.email.auth_password The password to use when authenticating with the SMTP server. Normally this value will be set when editing the email settings, however you can set a clear text password here that is encrypted on the next Splunk restart.

Defaults to empty string.

action.email.auth_username The username to use when authenticating with the SMTP server. If this is empty string, no authentication is attempted. Defaults to empty string.

Note: Your SMTP server might reject unauthenticated emails.

action.email.bcc BCC email address to use if action.email is enabled.
action.email.cc CC email address to use if action.email is enabled.
action.email.command The search command (or pipeline) which is responsible for executing the action.

Generally the command is a template search pipeline which is realized with values from the saved search. To reference saved search field values wrap them in $, for example to reference the savedsearch name use $name$, to reference the search use $search$.

action.email.format Specify the format of text in the email. This value also applies to any attachments.<

Valid values: (plain | html | raw | csv)

plain indicates plain text.

action.email.from Email address from which the email action originates
action.email.hostname Sets the hostname used in the web link (url) sent in email actions.

This value accepts two forms:

hostname (for example, splunkserver, splunkserver.example.com)

protocol://hostname:port (for example, http://splunkserver:8000, https://splunkserver.example.com:443)

When this value is a simple hostname, the protocol and port which are configured within splunk are used to construct the base of the url.

When this value begins with 'http://', it is used verbatim. NOTE: This means the correct port must be specified if it is not the default port for http or https. This is useful in cases when the Splunk server is not aware of how to construct an externally referencable url, such as SSO environments, other proxies, or when the Splunk server hostname is not generally resolvable.

Defaults to current hostname provided by the operating system, or if that fails "localhost". When set to empty, default behavior is used.

action.email.inline Indicates whether the search results are contained in the body of the email.

Results can be either inline or attached to an email. See action.email.sendresults.

action.email.mailserver Set the address of the MTA server to be used to send the emails.

Defaults to <LOCALHOST> (or whatever is set in alert_actions.conf).

action.email.maxresults Sets the maximum number of search results sent using alerts.
action.email.maxtime Specifies the maximum amount of time the execution of an email action takes before the action is aborted.
action.email.pdfview The name of the view to deliver if sendpdf is enabled.
action.email.preprocess_results Search string to preprocess results before emailing them. Defaults to empty string (no preprocessing).

Usually the preprocessing consists of filtering out unwanted internal fields.

action.email.reportPaperOrientation Specifies the paper orientation: portrait or landscape.
action.email.reportPaperSize Specifies the paper size for PDFs. Defaults to letter.

Valid values: (letter | legal | ledger | a2 | a3 | a4 | a5)

action.email.reportServerEnabled Indicates whether the PDF server is enabled.
action.email.reportServerURL The URL of the PDF report server, if one is set up and available on the network.

For a default locally installed report server, the URL is http://localhost:8091/

action.email.sendpdf Indicates whether to create and send the results as a PDF.
action.email.sendresults Indicates whether to attach the search results in the email.

Results can be either attached or inline. See action.email.inline.

action.email.subject Specifies an email subject.

Defaults to SplunkAlert-<savedsearchname>.

action.email.to List of recipient email addresses. Required if this search is scheduled and the email alert action is enabled.
action.email.track_alert Indicates whether the execution of this action signifies a trackable alert.
action.email.ttl Specifies the minimum time-to-live in seconds of the search artifacts if this action is triggered. If p follows <Integer>, int is the number of scheduled periods. Defaults to 86400 (24 hours).

If no actions are triggered, the artifacts have their ttl determined by dispatch.ttl in savedsearches.conf.

Valid values are Integer[p].

action.email.use_ssl Indicates whether to use SSL when communicating with the SMTP server.
action.email.use_tls Indicates whether to use TLS (transport layer security) when communicating with the SMTP server (starttls).
cron_schedule The cron schedule to execute this search. For example: */5 * * * * causes the search to execute every 5 minutes.

cron lets you use standard cron notation to define your scheduled search interval. In particular, cron can accept this type of notation: 00,20,40 * * * *, which runs the search every hour at hh:00, hh:20, hh:40. Along the same lines, a cron of 03,23,43 * * * * runs the search every hour at hh:03, hh:23, hh:43.

Splunk recommends that you schedule your searches so that they are staggered over time. This reduces system load. Running all of them every 20 minutes (*/20) means they would all launch at hh:00 (20, 40) and might slow your system every 20 minutes.

Valid values: cron string

description Description of the saved search for this view.
disabled Indicates if the saved search for this view is disabled.
is_scheduled Indicates if this search is to be run on a schedule.
next_scheduled_time The next time when the view is delivered.

Example

Edit scheduled view to email to info@example.com every hour on the hour and update the description 


curl -k -u admin:pass https://localhost:8089/servicesNS/admin/search/scheduled/views/MyVew \
	-d action.email.to="info@example.com" \
	-d cron_schedule="0 * * * *" \
	-d is_scheduled=1 \
	-d description="New description"



<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:s="http://dev.splunk.com/ns/rest"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>scheduledviews</title>
  <id>https://localhost:8089/servicesNS/admin/search/scheduled/views</id>
  <updated>2011-07-27T17:59:32-04:00</updated>
  <generator version="104601"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/servicesNS/admin/search/scheduled/views/_reload" rel="_reload"/>
  <opensearch:totalResults>1</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
  <entry>
    <title>_ScheduledView__MyView</title>
    <id>https://localhost:8089/servicesNS/admin/search/scheduled/views/_ScheduledView__MyView</id>
    <updated>2011-07-27T17:59:32-04:00</updated>
    <link href="/servicesNS/admin/search/scheduled/views/_ScheduledView__MyView" rel="alternate"/>
    <author>
      <name>admin</name>
    </author>
    <link href="/servicesNS/admin/search/scheduled/views/_ScheduledView__MyView" rel="list"/>
    <link href="/servicesNS/admin/search/scheduled/views/_ScheduledView__MyView/_reload" rel="_reload"/>
    <link href="/servicesNS/admin/search/scheduled/views/_ScheduledView__MyView" rel="edit"/>
    <link href="/servicesNS/admin/search/scheduled/views/_ScheduledView__MyView" rel="remove"/>
    <link href="/servicesNS/admin/search/scheduled/views/_ScheduledView__MyView/move" rel="move"/>
    <link href="/servicesNS/admin/search/scheduled/views/_ScheduledView__MyView/disable" rel="disable"/>
    <link href="/servicesNS/admin/search/scheduled/views/_ScheduledView__MyView/dispatch" rel="dispatch"/>
    <link href="/servicesNS/admin/search/scheduled/views/_ScheduledView__MyView/history" rel="history"/>
    <link href="/servicesNS/admin/search/scheduled/views/_ScheduledView__MyView/notify" rel="notify"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="action.email">1</s:key>
        <s:key name="action.email.auth_password"></s:key>
        <s:key name="action.email.auth_username"></s:key>
        <s:key name="action.email.bcc"></s:key>
        <s:key name="action.email.cc"></s:key>
        <s:key name="action.email.command">
          <![CDATA[$action.email.preprocess_results{default=""}$ |
                   sendemail "server=$action.email.mailserver{default=localhost}$" "use_ssl=$action.email.use_ssl{default=false}$"
                   "use_tls=$action.email.use_tls{default=false}$" "to=$action.email.to$" "cc=$action.email.cc$"
                   "bcc=$action.email.bcc$" "from=$action.email.from{default=splunk@localhost}$"
                   "subject=$action.email.subject{recurse=yes}$" "format=$action.email.format{default=csv}$"
                   "sssummary=Saved Search [$name$]: $counttype$($results.count$)" "sslink=$results.url$"
                   "ssquery=$search$" "ssname=$name$" "inline=$action.email.inline{default=False}$"
                   "sendresults=$action.email.sendresults{default=False}$" "sendpdf=$action.email.sendpdf{default=False}$"
                   "pdfview=$action.email.pdfview$" "searchid=$search_id$" "graceful=$graceful{default=True}$"
                   maxinputs="$action.email.maxresults{default=10000}$" maxtime="$action.email.maxtime{default=5m}$"]]>
        </s:key>
        <s:key name="action.email.format">html</s:key>
        <s:key name="action.email.from">splunk</s:key>
        <s:key name="action.email.hostname"></s:key>
        <s:key name="action.email.inline">0</s:key>
        <s:key name="action.email.mailserver">localhost</s:key>
        <s:key name="action.email.maxresults">10000</s:key>
        <s:key name="action.email.maxtime">5m</s:key>
        <s:key name="action.email.pdfview">MyView</s:key>
        <s:key name="action.email.preprocess_results"></s:key>
        <s:key name="action.email.reportPaperOrientation">portrait</s:key>
        <s:key name="action.email.reportPaperSize">letter</s:key>
        <s:key name="action.email.reportServerEnabled">0</s:key>
        <s:key name="action.email.reportServerURL"></s:key>
        <s:key name="action.email.sendpdf">1</s:key>
        <s:key name="action.email.sendresults">0</s:key>
        <s:key name="action.email.subject">Splunk Alert: $name$</s:key>
        <s:key name="action.email.to">info@example.com</s:key>
        <s:key name="action.email.track_alert">1</s:key>
        <s:key name="action.email.ttl">10</s:key>
        <s:key name="action.email.use_ssl">0</s:key>
        <s:key name="action.email.use_tls">0</s:key>
        <s:key name="cron_schedule">0 * * * *</s:key>
        <s:key name="description">New Description</s:key>
        <s:key name="disabled">0</s:key>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="is_scheduled">1</s:key>
        <s:key name="next_scheduled_time">2011-07-27 18:00:00 EDT</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

scheduled/views/{name}/dispatch

POST scheduled/views/{name}/dispatch

Dispatch the scheduled search (powering the scheduled view) just like the scheduler would. Action available only through POST. The following optional arguments are accepted:

dispatch.now: [time] dispatch the search as if it this was the current time

dispatch.*: any dispatch.* field of the search can be overriden

now: [time] deprecated, same as dispatch.now use that instead

trigger_actions: [bool] whether to trigger the alert actions

force_dispatch: [bool] should a new search be started even if another instance of this search is already running

Request

No parameters for this request.

Response Codes

Status Code Description
200 Dispatched the scheduled view successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
402 The Splunk license in use has disabled this feature.
403 Insufficient permissions to dispatch a scheduled view.
404 Named view does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.
503 This feature has been disabled in Splunk configuration files.

Returned Values

No values returned for this request.

Example

Dispatch the scheduled view and deliver the email (trigger the action) for MyView view 


curl -k -u admin:pass https://localhost:8089/servicesNS/admin/search/scheduled/views/MyView/dispatch \
	-d trigger_actions=1



<?xml version='1.0' encoding='UTF-8'?>
<response><sid>admin__admin__search_X1NjaGVkdWxlZFZpZXdfX015Vmlldw_at_1311805021_c24ff1ea77ad714b</sid></response>

scheduled/views/{name}/history

GET scheduled/views/{name}/history

Get a list of search jobs used to deliver this scheduled view

Request

No parameters for this request.

Response Codes

Status Code Description
200 Retrieved scheduled view history successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to retrieve scheduled view history.
404 Named view does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

No values returned for this request.

Example

Get the delivery history of the scheduled view MyView 

curl -k -u admin:pass https://localhost:8089/servicesNS/admin/search/scheduled/views/MyVew/history



<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:s="http://dev.splunk.com/ns/rest"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>_ScheduledView__MyView</title>
  <id>https://localhost:8089/servicesNS/admin/search/scheduled/views</id>
  <updated>2011-07-27T16:25:22-04:00</updated>
  <generator version="104601"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/servicesNS/admin/search/scheduled/views/_reload" rel="_reload"/>
  <opensearch:totalResults>1</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
  <entry>
    <title>scheduler__admin__search_X1NjaGVkdWxlZFZpZXdfX015Vmlldw_at_1311798300_842d7ca298ab521a</title>
    <id>https://localhost:8089/servicesNS/nobody/search/search/jobs/scheduler__admin__search_X1NjaGVkdWxlZFZpZXdfX015Vmlldw_at_1311798300_842d7ca298ab521a</id>
    <updated>2011-07-27T16:25:15-04:00</updated>
    <link href="/servicesNS/nobody/search/search/jobs/scheduler__admin__search_X1NjaGVkdWxlZFZpZXdfX015Vmlldw_at_1311798300_842d7ca298ab521a" rel="alternate"/>
    <author>
      <name>admin</name>
    </author>
    <published>2011-07-27T16:25:15-04:00</published>
    <link href="/servicesNS/nobody/search/search/jobs/scheduler__admin__search_X1NjaGVkdWxlZFZpZXdfX015Vmlldw_at_1311798300_842d7ca298ab521a" rel="list"/>
    <link href="/servicesNS/nobody/search/search/jobs/scheduler__admin__search_X1NjaGVkdWxlZFZpZXdfX015Vmlldw_at_1311798300_842d7ca298ab521a/_reload" rel="_reload"/>
    <link href="/servicesNS/nobody/search/search/jobs/scheduler__admin__search_X1NjaGVkdWxlZFZpZXdfX015Vmlldw_at_1311798300_842d7ca298ab521a" rel="edit"/>
    <link href="/servicesNS/nobody/search/search/jobs/scheduler__admin__search_X1NjaGVkdWxlZFZpZXdfX015Vmlldw_at_1311798300_842d7ca298ab521a" rel="remove"/>
    <content type="text/xml">
      <s:dict>
        <!-- eai:acl nodes elided for brevity. -->
      </s:dict>
    </content>
  </entry>
</feed>

scheduled/views/{name}/scheduled_times

GET scheduled/views/{name}/scheduled_times

Returns the scheduled times for a scheduled view. Specify a time range for the data returned using earliest_time and latest_time parameters.

Request

No parameters for this request.

Response Codes

Status Code Description
200 Scheduled times returned successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to access scheduled times.
404 Scheudled times do not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
action.email Indicates the state of the email action.
action.email.auth_password The password to use when authenticating with the SMTP server. Normally this value will be set when editing the email settings, however you can set a clear text password here that is encrypted on the next Splunk restart.

Defaults to empty string.

action.email.auth_username The username to use when authenticating with the SMTP server. If this is empty string, no authentication is attempted. Defaults to empty string.

Note: Your SMTP server might reject unauthenticated emails.

action.email.bcc BCC email address to use if action.email is enabled.
action.email.cc CC email address to use if action.email is enabled.
action.email.command The search command (or pipeline) which is responsible for executing the action.

Generally the command is a template search pipeline which is realized with values from the saved search. To reference saved search field values wrap them in $, for example to reference the savedsearch name use $name$, to reference the search use $search$.

action.email.format Specify the format of text in the email. This value also applies to any attachments.<

Valid values: (plain | html | raw | csv)

plain indicates plain text.

action.email.from Email address from which the email action originates.
action.email.hostname Sets the hostname used in the web link (url) sent in email actions.

This value accepts two forms:

hostname (for example, splunkserver, splunkserver.example.com)

protocol://hostname:port (for example, http://splunkserver:8000, https://splunkserver.example.com:443)

When this value is a simple hostname, the protocol and port which are configured within splunk are used to construct the base of the url.

When this value begins with 'http://', it is used verbatim. NOTE: This means the correct port must be specified if it is not the default port for http or https. This is useful in cases when the Splunk server is not aware of how to construct an externally referencable url, such as SSO environments, other proxies, or when the Splunk server hostname is not generally resolvable.

Defaults to current hostname provided by the operating system, or if that fails "localhost". When set to empty, default behavior is used.

action.email.inline Indicates whether the search results are contained in the body of the email.

Results can be either inline or attached to an email. See action.email.sendresults.

action.email.mailserver Set the address of the MTA server to be used to send the emails.

Defaults to <LOCALHOST> (or whatever is set in alert_actions.conf).

action.email.maxresults Sets the maximum number of search results sent using alerts.
action.email.maxtime Specifies the maximum amount of time the execution of an email action takes before the action is aborted.
action.email.pdfview The name of the view to deliver if sendpdf is enabled.
action.email.preprocess_results Search string to preprocess results before emailing them. Defaults to empty string (no preprocessing).

Usually the preprocessing consists of filtering out unwanted internal fields.

action.email.reportPaperOrientation Specifies the paper orientation: portrait or landscape.
action.email.reportPaperSize Specifies the paper size for PDFs. Defaults to letter.

Valid values: (letter | legal | ledger | a2 | a3 | a4 | a5)

action.email.reportServerEnabled Indicates whether the PDF server is enabled.
action.email.reportServerURL The URL of the PDF report server, if one is set up and available on the network.

For a default locally installed report server, the URL is http://localhost:8091

action.email.sendpdf Indicates whether to create and send the results as a PDF.
action.email.sendresults Indicates whether to attach the search results in the email.

Results can be either attached or inline. See action.email.inline.

action.email.subject Specifies an email subject.

Defaults to SplunkAlert-<savedsearchname>.

action.email.to List of recipient email addresses. Required if this search is scheduled and the email alert action is enabled.
action.email.track_alert Indicates whether the execution of this action signifies a trackable alert.
action.email.ttl Specifies the minimum time-to-live in seconds of the search artifacts if this action is triggered. If p follows <Integer>, int is the number of scheduled periods. Defaults to 86400 (24 hours).

If no actions are triggered, the artifacts have their ttl determined by dispatch.ttl in savedsearches.conf.

Valid values are Integer[p].

action.email.use_ssl Indicates whether to use SSL when communicating with the SMTP server.
action.email.use_tls Indicates whether to use TLS (transport layer security) when communicating with the SMTP server (starttls).
action.email.width_sort_columns Indicates whether columns should be sorted from least wide to most wide, left to right.

Only valid if format=plain, indicating plain text.

cron_schedule The cron schedule to execute this search. For example: */5 * * * * causes the search to execute every 5 minutes.

cron lets you use standard cron notation to define your scheduled search interval. In particular, cron can accept this type of notation: 00,20,40 * * * *, which runs the search every hour at hh:00, hh:20, hh:40. Along the same lines, a cron of 03,23,43 * * * * runs the search every hour at hh:03, hh:23, hh:43.

Splunk recommends that you schedule your searches so that they are staggered over time. This reduces system load. Running all of them every 20 minutes (*/20) means they would all launch at hh:00 (20, 40) and might slow your system every 20 minutes.

Valid values: cron string

description Description of the saved search for this view.
disabled Indicates if the saved search for this view is disnabled.

Disabled saved searches are not visible in Splunk Web.

is_scheduled Indicates if this search is to be run on a schedule.
next_scheduled_time The next time when the view is delivered.

Example

Display the scheduled views for the specified time frame. 

curl -k -u admin:admin \
	https://localhost:8089/services/scheduled/views/_ScheduledView__dashboard_live/scheduled_times --get \
	-d earliest_time=-5h \
	-d latest_time=-3h

<feed xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>scheduledviews</title>
  <id>https://wma-mbp15:8089/services/scheduled/views</id>
  <updated>2011-12-01T14:40:18-08:00</updated>
  <generator version="112383"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/scheduled/views/_reload" rel="_reload"/>
  <opensearch:totalResults>1</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
  <entry>
    <title>_ScheduledView__dashboard_live</title>
    <id>https://wma-mbp15:8089/servicesNS/admin/search/scheduled/views/_ScheduledView__dashboard_live</id>
    <updated>2011-12-01T14:40:18-08:00</updated>
    <link href="/servicesNS/admin/search/scheduled/views/_ScheduledView__dashboard_live" rel="alternate"/>
    <author>
      <name>admin</name>
    </author>
    <!-- opensearch nodes elided for brevity. -->
    <content type="text/xml">
      <s:dict>
        <s:key name="action.email">1</s:key>
        <s:key name="action.email.auth_password"></s:key>
        <s:key name="action.email.auth_username"></s:key>
        <s:key name="action.email.bcc"></s:key>
        <s:key name="action.email.cc"></s:key>
        <s:key name="action.email.command"><![CDATA[$action.email.preprocess_results{default=""}$ | sendemail "server=$action.email.mailserver{default=localhost}$" "use_ssl=$action.email.use_ssl{default=false}$" "use_tls=$action.email.use_tls{default=false}$" "to=$action.email.to$" "cc=$action.email.cc$" "bcc=$action.email.bcc$" "from=$action.email.from{default=splunk@localhost}$" "subject=$action.email.subject{recurse=yes}$" "format=$action.email.format{default=csv}$" "sssummary=Saved Search [$name$]: $counttype$($results.count$)" "sslink=$results.url$" "ssquery=$search$" "ssname=$name$" "inline=$action.email.inline{default=False}$" "sendresults=$action.email.sendresults{default=False}$" "sendpdf=$action.email.sendpdf{default=False}$" "pdfview=$action.email.pdfview$" "searchid=$search_id$" "width_sort_columns=$action.email.width_sort_columns$" "graceful=$graceful{default=True}$" maxinputs="$action.email.maxresults{default=10000}$" maxtime="$action.email.maxtime{default=5m}$"]]></s:key>
        <s:key name="action.email.format">html</s:key>
        <s:key name="action.email.from">splunk</s:key>
        <s:key name="action.email.hostname"></s:key>
        <s:key name="action.email.inline">0</s:key>
        <s:key name="action.email.mailserver">localhost</s:key>
        <s:key name="action.email.maxresults">10000</s:key>
        <s:key name="action.email.maxtime">5m</s:key>
        <s:key name="action.email.pdfview">dashboard_live</s:key>
        <s:key name="action.email.preprocess_results"></s:key>
        <s:key name="action.email.reportPaperOrientation">portrait</s:key>
        <s:key name="action.email.reportPaperSize">letter</s:key>
        <s:key name="action.email.reportServerEnabled">1</s:key>
        <s:key name="action.email.reportServerURL"> </s:key>
        <s:key name="action.email.sendpdf">1</s:key>
        <s:key name="action.email.sendresults">0</s:key>
        <s:key name="action.email.subject">Splunk Alert: $name$</s:key>
        <s:key name="action.email.to">wma@splunk.com</s:key>
        <s:key name="action.email.track_alert">1</s:key>
        <s:key name="action.email.ttl">10</s:key>
        <s:key name="action.email.use_ssl">0</s:key>
        <s:key name="action.email.use_tls">0</s:key>
        <s:key name="action.email.width_sort_columns">1</s:key>
        <s:key name="cron_schedule">/5 * * * *</s:key>
        <s:key name="description">scheduled search for view name=dashboard_live</s:key>
        <s:key name="disabled">0</s:key>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="is_scheduled">1</s:key>
        <s:key name="next_scheduled_time">2011-12-01 15:00:00 PST</s:key>
      </s:dict>
    </content>
  </entry>
</feed>


search/jobs

Provides listings for search jobs.

Refer to Creating searches using the REST API for information on using this endpoint and other search endpoints.

GET search/jobs

Returns details of all current searches. The user ID is implied by the authentication to the call.

Information returned for each entry includes the search job properties, such as eventCount (number of events returned), runDuration (time the search took to complete), and others. The parameters to POST /search/jobs provides details on search job properties when creating a search. Search job properties are also described in the Search Reference.

You can specify optional arguments based on the search job properties to filter the entries returned. For example, specify search=eventCount>100 as an argument to the GET operation to return searches with event counts greater than 100.

The dispatchState property is of particular interest to determine the state of a search, and can contain the following values:

QUEUED
PARSING
RUNNING
PAUSED
FINALIZING
FAILED
DONE

This operation also returns performance information for the search. Refer to Execution costs in the Search Reference for more information.

For more information on searches in Splunk, refer to the Splunk Search Reference.

Request

No parameters for this request.

Response Codes

Status Code Description
200 Listed successfully.

Returned Values

Attribute Description
cursorTime The earliest time from which no events are later scanned.

Can be used to indicate progress. See description for doneProgress.

delegate For saved searches, specifies jobs that were started by the user. Defaults to scheduler.
diskUsage The total amount of disk space used, in bytes.
dispatchState The state of the search. Can be any of QUEUED, PARSING, RUNNING, PAUSED, FINALIZING, FAILED, DONE.
doneProgress A number between 0 and 1.0 that indicates the approximate progress of the search.

doneProgress = (latestTime – cursorTime) / (latestTime – earliestTime)

dropCount For real-time searches only, the number of possible events that were dropped due to the rt_queue_size (default to 100000).
eai:acl See Access control lists for Splunk objects
earliestTime The earliest time a search job is configured to start.

Can be used to indicate progress. See description for doneProgress.

eventAvailableCount The number of events that are available for export.
eventCount The number of events returned by the search.
eventFieldCount The number of fields found in the search results.
eventIsStreaming Indicates if the events of this search are being streamed.
eventIsTruncated Indicates if events of the search have not been stored, and thus not available from the events endpoint for the search.
eventSearch Subset of the entire search that is before any transforming commands. The timeline and events endpoint represents the result of this part of the search.
eventSorting Indicates if the events of this search are sorted, and in which order.

asc = ascending;

desc = descending;

none = not sorted

isDone Indicates if the search has completed.
isFailed Indicates if there was a fatal error executing the search. For example, if the search string had invalid syntax.
isFinalized Indicates if the search was finalized (stopped before completion).
isPaused Indicates if the search has been paused.
isPreviewEnabled Indicates if previews are enabled.
isRealTimeSearch Indicates if the search is a real time search.
isRemoteTimeline Indicates if the remote timeline feature is enabled.
isSaved Indicates if the search is saved indefinitely.
isSavedSearch Indicates if this is a saved search run using the scheduler.
isZombie Indicates if the process running the search is dead, but with the search not finished.
keywords All positive keywords used by this search. A positive keyword is a keyword that is not in a NOT clause.
label Custom name created for this search.
latestTime The latest time a search job is configured to start.

Can be used to indicate progress. See description for doneProgress.

messages Errors and debug messages.
numPreviews Number of previews that have been generated so far for this search job.
performance A representation of the execution costs.
priority An integer between 0-10 that indicates the search's priority.

The priority is mapped to the OS process priority. The higher the number the higher the priority. The priority can be changed using action parameter for POST search/jobs/{search_id}/control. For example, for the action parameter, specify priority=5.

Note: In *nix systems, non-privileged users can only reduce the priority of a process.

remoteSearch The search string that is sent to every search peer.
reportSearch If reporting commands are used, the reporting search.
request GET arguments that the search sends to splunkd.
resultCount The total number of results returned by the search. In other words, this is the subset of scanned events (represented by the scanCount) that actually matches the search terms.
resultIsStreaming Indicates if the final results of the search are available using streaming (for example, no transforming operations).
resultPreviewCount The number of result rows in the latest preview results.
runDuration Time in seconds that the search took to complete.
scanCount The number of events that are scanned or read off disk.
searchEarliestTime Specifies the earliest time for a search, as specified in the search command rather than the earliestTime parameter. It does not snap to the indexed data time bounds for all-time searches (something that earliestTime/latestTime does).
searchLatestTime Specifies the latest time for a search, as specified in the search command rather than the latestTime parameter. It does not snap to the indexed data time bounds for all-time searches (something that earliestTime/latestTime does).
searchProviders A list of all the search peers that were contacted.
sid The search ID number.
statusBuckets Maximum number of timeline buckets.
ttl The time to live, or time before the search job expires after it completes.

Example

Shows an entry from the listing for all search jobs whose eventCount is greater than 100. 


curl -k -u admin:pass https://localhost:8089/services/search/jobs --get \
	-d search="eventCount>100"



<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:s="http://dev.splunk.com/ns/rest"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>jobs</title>
  <id>https://localhost:8089/services/search/jobs</id>
  <updated>2011-06-21T10:12:22-07:00</updated>
  <generator version="100492"/>
  <author>
    <name>Splunk</name>
  </author>
  <opensearch:totalResults>8</opensearch:totalResults>
  <opensearch:itemsPerPage>0</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <entry>
    <title>search  index=_internal (source=*/metrics.log* OR source=*\\metrics.log*) group=per_sourcetype_thruput
        | chart sum(kb) by series | sort -sum(kb) | head 5</title>
    <id>https://localhost:8089/services/search/jobs/scheduler__nobody__search_VG9wIGZpdmUgc291cmNldHlwZXM_at_1308676200_22702c154383bbe4</id>
    <updated>2011-06-21T10:10:31.000-07:00</updated>
    <link href="/services/search/jobs/scheduler__nobody__search_VG9wIGZpdmUgc291cmNldHlwZXM_at_1308676200_22702c154383bbe4" rel="alternate"/>
    <published>2011-06-21T10:10:23.000-07:00</published>
    <link href="/services/search/jobs/scheduler__nobody__search_VG9wIGZpdmUgc291cmNldHlwZXM_at_1308676200_22702c154383bbe4/search.log" rel="log"/>
    <link href="/services/search/jobs/scheduler__nobody__search_VG9wIGZpdmUgc291cmNldHlwZXM_at_1308676200_22702c154383bbe4/events" rel="events"/>
    <link href="/services/search/jobs/scheduler__nobody__search_VG9wIGZpdmUgc291cmNldHlwZXM_at_1308676200_22702c154383bbe4/results" rel="results"/>
    <link href="/services/search/jobs/scheduler__nobody__search_VG9wIGZpdmUgc291cmNldHlwZXM_at_1308676200_22702c154383bbe4/results_preview" rel="results_preview"/>
    <link href="/services/search/jobs/scheduler__nobody__search_VG9wIGZpdmUgc291cmNldHlwZXM_at_1308676200_22702c154383bbe4/timeline" rel="timeline"/>
    <link href="/services/search/jobs/scheduler__nobody__search_VG9wIGZpdmUgc291cmNldHlwZXM_at_1308676200_22702c154383bbe4/summary" rel="summary"/>
    <link href="/services/search/jobs/scheduler__nobody__search_VG9wIGZpdmUgc291cmNldHlwZXM_at_1308676200_22702c154383bbe4/control" rel="control"/>
    <author>
      <name>splunk-system-user</name>
    </author>
    <content type="text/xml">
      <s:dict>
        <s:key name="cursorTime">1969-12-31T16:00:00.000-08:00</s:key>
        <s:key name="delegate">scheduler</s:key>
        <s:key name="diskUsage">73728</s:key>
        <s:key name="dispatchState">DONE</s:key>
        <s:key name="doneProgress">1.00000</s:key>
        <s:key name="dropCount">0</s:key>
        <s:key name="earliestTime">2011-06-20T10:10:00.000-07:00</s:key>
        <s:key name="eventAvailableCount">0</s:key>
        <s:key name="eventCount">1363</s:key>
        <s:key name="eventFieldCount">0</s:key>
        <s:key name="eventIsStreaming">1</s:key>
        <s:key name="eventIsTruncated">1</s:key>
        <s:key name="eventSearch">search index=_internal (source=*/metrics.log* OR source=*\\metrics.log*) group=per_sourcetype_thruput </s:key>
        <s:key name="eventSorting">none</s:key>
        <s:key name="isDone">1</s:key>
        <s:key name="isFailed">0</s:key>
        <s:key name="isFinalized">0</s:key>
        <s:key name="isPaused">0</s:key>
        <s:key name="isPreviewEnabled">0</s:key>
        <s:key name="isRealTimeSearch">0</s:key>
        <s:key name="isRemoteTimeline">0</s:key>
        <s:key name="isSaved">0</s:key>
        <s:key name="isSavedSearch">1</s:key>
        <s:key name="isZombie">0</s:key>
        <s:key name="keywords">group::per_sourcetype_thruput index::_internal source::*/metrics.log* source::*\metrics.log*</s:key>
        <s:key name="label">Top five sourcetypes</s:key>
        <s:key name="latestTime">2011-06-21T10:10:00.000-07:00</s:key>
        <s:key name="numPreviews">0</s:key>
        <s:key name="priority">5</s:key>
        <s:key name="remoteSearch">litsearch index=_internal ( source=*/metrics.log* OR source=*\\metrics.log* )
                group=per_sourcetype_thruput | addinfo  type=count label=prereport_events
                | fields  keepcolorder=t "kb" "prestats_reserved_*" "psrsvd_*" "series"
                | convert  num("kb")  | prestats  sum(kb) AS "sum(kb)" by series</s:key>
        <s:key name="reportSearch">chart  sum(kb) by series  | sort  -sum(kb)  | head  5</s:key>
        <s:key name="resultCount">4</s:key>
        <s:key name="resultIsStreaming">0</s:key>
        <s:key name="resultPreviewCount">4</s:key>
        <s:key name="runDuration">0.259000</s:key>
        <s:key name="scanCount">1363</s:key>
        <s:key name="searchEarliestTime">1308589800.000000000</s:key>
        <s:key name="searchLatestTime">1308676200.000000000</s:key>
        <s:key name="sid">scheduler__nobody__search_VG9wIGZpdmUgc291cmNldHlwZXM_at_1308676200_22702c154383bbe4</s:key>
        <s:key name="statusBuckets">0</s:key>
        <s:key name="ttl">489</s:key>
        <s:key name="performance">
          <s:dict>
            <s:key name="command.addinfo">
              <s:dict>
                <s:key name="duration_secs">0.005</s:key>
                <s:key name="invocations">5</s:key>
                <s:key name="input_count">1363</s:key>
                <s:key name="output_count">1363</s:key>
              </s:dict>
            </s:key>
            <s:key name="command.chart">
              <s:dict>
                <s:key name="duration_secs">0.003</s:key>
                <s:key name="invocations">1</s:key>
                <s:key name="input_count">100000</s:key>
                <s:key name="output_count">4</s:key>
              </s:dict>
            </s:key>
            <s:key name="command.convert">
              <s:dict>
                <s:key name="duration_secs">0.006</s:key>
                <s:key name="invocations">5</s:key>
                <s:key name="input_count">1363</s:key>
                <s:key name="output_count">1363</s:key>
              </s:dict>
            </s:key>
            <s:key name="command.fields">
              <s:dict>
                <s:key name="duration_secs">0.005</s:key>
                <s:key name="invocations">5</s:key>
                <s:key name="input_count">1363</s:key>
                <s:key name="output_count">1363</s:key>
              </s:dict>
            </s:key>
            <s:key name="command.head">
              <s:dict>
                <s:key name="duration_secs">0.001</s:key>
                <s:key name="invocations">1</s:key>
                <s:key name="input_count">4</s:key>
                <s:key name="output_count">4</s:key>
              </s:dict>
            </s:key>
            <s:key name="command.presort">
              <s:dict>
                <s:key name="duration_secs">0.001</s:key>
                <s:key name="invocations">1</s:key>
                <s:key name="input_count">4</s:key>
                <s:key name="output_count">4</s:key>
              </s:dict>
            </s:key>
            <s:key name="command.prestats">
              <s:dict>
                <s:key name="duration_secs">0.014</s:key>
                <s:key name="invocations">5</s:key>
                <s:key name="input_count">1363</s:key>
                <s:key name="output_count">12</s:key>
              </s:dict>
            </s:key>
            <s:key name="command.search">
              <s:dict>
                <s:key name="duration_secs">0.058</s:key>
                <s:key name="invocations">5</s:key>
                <s:key name="input_count">0</s:key>
                <s:key name="output_count">1363</s:key>
              </s:dict>
            </s:key>
            <s:key name="command.search.fieldalias">
              <s:dict>
                <s:key name="duration_secs">0.003</s:key>
                <s:key name="invocations">3</s:key>
                <s:key name="input_count">1363</s:key>
                <s:key name="output_count">1363</s:key>
              </s:dict>
            </s:key>
            <s:key name="command.search.filter">
              <s:dict>
                <s:key name="duration_secs">0.004</s:key>
                <s:key name="invocations">3</s:key>
              </s:dict>
            </s:key>
            <s:key name="command.search.index">
              <s:dict>
                <s:key name="duration_secs">0.010</s:key>
                <s:key name="invocations">5</s:key>
              </s:dict>
            </s:key>
            <s:key name="command.search.kv">
              <s:dict>
                <s:key name="duration_secs">0.011</s:key>
                <s:key name="invocations">3</s:key>
              </s:dict>
            </s:key>
            <s:key name="command.search.lookups">
              <s:dict>
                <s:key name="duration_secs">0.003</s:key>
                <s:key name="invocations">3</s:key>
                <s:key name="input_count">1363</s:key>
                <s:key name="output_count">1363</s:key>
              </s:dict>
            </s:key>
            <s:key name="command.search.rawdata">
              <s:dict>
                <s:key name="duration_secs">0.034</s:key>
                <s:key name="invocations">3</s:key>
              </s:dict>
            </s:key>
            <s:key name="command.search.tags">
              <s:dict>
                <s:key name="duration_secs">0.005</s:key>
                <s:key name="invocations">5</s:key>
                <s:key name="input_count">1363</s:key>
                <s:key name="output_count">1363</s:key>
              </s:dict>
            </s:key>
            <s:key name="command.search.typer">
              <s:dict>
                <s:key name="duration_secs">0.005</s:key>
                <s:key name="invocations">5</s:key>
                <s:key name="input_count">1363</s:key>
                <s:key name="output_count">1363</s:key>
              </s:dict>
            </s:key>
            <s:key name="command.sort">
              <s:dict>
                <s:key name="duration_secs">0.001</s:key>
                <s:key name="invocations">1</s:key>
                <s:key name="input_count">4</s:key>
                <s:key name="output_count">4</s:key>
              </s:dict>
            </s:key>
            <s:key name="dispatch.createProviderQueue">
              <s:dict>
                <s:key name="duration_secs">0.067</s:key>
                <s:key name="invocations">1</s:key>
              </s:dict>
            </s:key>
            <s:key name="dispatch.evaluate">
              <s:dict>
                <s:key name="duration_secs">0.038</s:key>
                <s:key name="invocations">1</s:key>
              </s:dict>
            </s:key>
            <s:key name="dispatch.evaluate.chart">
              <s:dict>
                <s:key name="duration_secs">0.001</s:key>
                <s:key name="invocations">1</s:key>
              </s:dict>
            </s:key>
            <s:key name="dispatch.evaluate.head">
              <s:dict>
                <s:key name="duration_secs">0.001</s:key>
                <s:key name="invocations">1</s:key>
              </s:dict>
            </s:key>
            <s:key name="dispatch.evaluate.search">
              <s:dict>
                <s:key name="duration_secs">0.037</s:key>
                <s:key name="invocations">1</s:key>
              </s:dict>
            </s:key>
            <s:key name="dispatch.evaluate.sort">
              <s:dict>
                <s:key name="duration_secs">0.001</s:key>
                <s:key name="invocations">1</s:key>
              </s:dict>
            </s:key>
            <s:key name="dispatch.fetch">
              <s:dict>
                <s:key name="duration_secs">0.126</s:key>
                <s:key name="invocations">6</s:key>
              </s:dict>
            </s:key>
            <s:key name="dispatch.stream.local">
              <s:dict>
                <s:key name="duration_secs">0.070</s:key>
                <s:key name="invocations">5</s:key>
              </s:dict>
            </s:key>
          </s:dict>
        </s:key>
        <s:key name="messages">
          <s:dict/>
        </s:key>
        <s:key name="request">
          <s:dict>
            <s:key name="ui_dispatch_app"></s:key>
            <s:key name="ui_dispatch_view"></s:key>
          </s:dict>
        </s:key>
        <s:key name="eai:acl">
          <s:dict>
            <s:key name="perms">
              <s:dict>
                <s:key name="read">
                  <s:list>
                    <s:item>admin</s:item>
                  </s:list>
                </s:key>
                <s:key name="write">
                  <s:list>
                    <s:item>admin</s:item>
                  </s:list>
                </s:key>
              </s:dict>
            </s:key>
            <s:key name="owner">nobody</s:key>
            <s:key name="modifiable">true</s:key>
            <s:key name="sharing">global</s:key>
            <s:key name="app">search</s:key>
            <s:key name="can_write">true</s:key>
          </s:dict>
        </s:key>
        <s:key name="searchProviders">
          <s:list>
            <s:item>vgenovese-mbp15.splunk.com-vgenovese</s:item>
          </s:list>
        </s:key>
      </s:dict>
    </content>
  </entry>
  . . .
</feed>


POST search/jobs

Starts a new search, returning the search ID (<sid>). Refer to Creating searches using the REST API for information on using this endpoint and other search endpoints.

The search parameter is a search language string that specifies the search. Often you create a search specifying just the search parameter. Use the other parameters to customize a search to specific needs.

Use the returned (<sid>) in the following endpoints to view and manage the search:

search/jobs/{search_id}: View the status of this search job.
search/jobs/{search_id}/control: Execute job control commands, such as pause, cancel, preview, and others.
search/jobs/{search_id}/events: View a set of untransformed events for the search.
search/jobs/{search_id}/results: View results of the search.
search/jobs/{search_id}/results_preview: Preview results of a search that has not completed
search/jobs/{search_id}/search.log: View the log file generated by the search.
search/jobs/{search_id}/summary: View field summary information
search/jobs/{search_id}/timeline: View event distribution over time.

For more information on searches in Splunk, refer to the Splunk Search Reference.

Request

Name Type Required Default Description
search String
✓
 The search language string to execute, taking results from the local and remote servers.

Examples:

"search *"
"search * | outputcsv"
auto_cancel Number 0 If specified, the job automatically cancels after this many seconds of inactivity. (0 means never auto-cancel)
auto_finalize_ec Number 0 Auto-finalize the search after at least this many events have been processed.

Specify 0 to indicate no limit.

auto_pause Number 0 If specified, the job automatically cancels after this many seconds of inactivity. (0 means never auto-pause)
earliest_time String Specify a time string. Sets 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. (Also see comment for the search_mode variable.)

enable_lookups Boolean true Indicates whether lookups should be applied to events.

Specifying true (the default) may slow searches significantly depending on the nature of the lookups.

exec_mode Enum normal Valid values: (blocking | oneshot | normal)

If set to normal, runs an asynchronous search.

If set to blocking, returns the sid when the job is complete.

If set to oneshot, returns results in the same call.

force_bundle_replication Boolean false Specifies whether this search should cause (and wait depending on the value of sync_bundle_replication) for bundle synchronization with all search peers.
id String Optional string to specify the search ID (<sid>). If unspecified, a random ID is generated.
latest_time String Specify a time string. Sets 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. (Also see comment for the search_mode variable.)

max_count Number 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, codeoffset+count <= max_count.

max_time Number 0 The number of seconds to run this search before finalizing. Specify 0 to never finalize.
namespace String The application namespace in which to restrict searches.

The namespace corresponds to the identifier recognized in the /services/apps/local endpoint.

now String current system time Specify a time string to set the absolute time used for any relative time specifier in the search. Defaults to the current system time.

You can specify a relative time modifier for this parameter. For example, specify +2d to specify the current time plus two days.

If you specify a relative time modifier both in this parameter and in the search string, the search string modifier takes precedence.

Refer to Time modifiers for search for details on specifying relative time modifiers.

reduce_freq Number 0 Determines how frequently to run the MapReduce reduce phase on accumulated map values.
reload_macros Boolean true Specifies whether to reload macro definitions from macros.conf.

Default is true.

remote_server_list String empty list Comma-separated list of (possibly wildcarded) servers from which raw events should be pulled. This same server list is to be used in subsearches.
required_field_list String empty list Deprecated. Use rf instead.

A comma-separated list of required fields that, even if not referenced or used directly by the search, is still included by the events and summary endpoints. Splunk Web uses these fields to prepopulate panels in the Search view.

rf String Adds a required field to the search. There can be multiple rf POST arguments to the search.

These fields, even if not referenced or used directly by the search, are still included by the events and summary endpoints. Splunk Web uses these fields to prepopulate panels in the Search view.

Consider using this form of passing the required fields to the search instead of the deprecated required_field_list. If both rf and required_field_list are supplied, the union of the two lists is used.

rt_blocking Boolean false For a realtime search, indicates if the indexer blocks if the queue for this search is full.
rt_indexfilter Boolean true For a realtime search, indicates if the indexer prefilters events.
rt_maxblocksecs Number 60 For a realtime search with rt_blocking set to true, the maximum time to block.

Specify 0 to indicate no limit.

rt_queue_size Number 10000 events For a realtime search, the queue size (in events) that the indexer should use for this search.
search_listener String Registers a search state listener with the search.

Use the format:

search_state;results_condition;http_method;uri;

For example:

search_listener=onResults;true;POST;/servicesNS/admin/search/saved/search/foobar/notify;

search_mode Enum normal Valid values: (normal | realtime)

If set to realtime, search runs over live data. A realtime search may also be indicated by earliest_time and latest_time variables starting with 'rt' even if the search_mode is set to normal or is unset. For a real-time search, if both earliest_time and latest_time are both exactly 'rt', the search represents all appropriate live data received since the start of the search.

Additionally, if earliest_time and/or latest_time are 'rt' followed by a relative time specifiers then a sliding window is used where the time bounds of the window are determined by the relative time specifiers and are continuously updated based on the wall-clock time.

spawn_process Boolean true Specifies whether the search should run in a separate spawned process. Default is true.

Searches against indexes must run in a separate process.

status_buckets Number 0 The most status buckets to generate.

0 indicates to not generate timeline information.

sync_bundle_replication Boolean Specifies whether this search should wait for bundle replication to complete.
time_format String ISO-8601 Used to convert a formatted time string from {start,end}_time into UTC seconds. It defaults to ISO-8601.
timeout Number 86400 The number of seconds to keep this search after processing has stopped.

Response Codes

Status Code Description
201 Created successfully.

Returned Values

No values returned for this request.

Example

Starts a new search, specifying the search ID (<sid>) to use. By default, the search you create returns a maximum of 10000 events. This search overrides the default, specifying 50000 events for max_count.

This search also specifies status_buckets=300. This allows you to access summary and timeline information from search/jobs/{search_id}/summary and search/jobs/{search_id}/timeline endpoints. When creating a search from the REST API, status_buckets by default are set to zero.

The search string for the search parameter must be prefixed with "search." Thus, it is in the form:

search search_string

URI-encode the search string if it contains any of the following characters: =, &, ?, %

Otherwise, these characters can be interpreted as part of the HTTP request. 


curl -k -u admin:pass https://localhost:8089/servicesNS/admin/search/search/jobs \
	--data-urlencode search="search index=_internal source=*/metrics.log" \
	-d id=mysearch_02151949 \
	-d max_count=50000 \
	-d status_buckets=300



<response><sid>mysearch_02151949</sid></response>

search/jobs/export

Allows for streaming of search results as they become available.

GET search/jobs/export

Performs a search identical to POST search/jobs, except the search does not create a search ID (<sid>) and the search streams results as they become available. Streaming of results is based on the search string.

For non-streaming searches, previews of the final results are available if preview is enabled. If preview is not enabled, it is better to use search/jobs with exec_mode=oneshot.

Request

Note: Paramaters available for GET search/jobs/{search_id}/events and GET search/jobs/{search_id}/results can also be supplied to this endpoint.

Name Type Required Default Description
search String
✓
 Same as for POST search/jobs.
auto_cancel Number Same as for POST search/jobs.
auto_finalize_ec Number Same as for POST search/jobs.
auto_pause Number Same as for POST search/jobs.
earliest_time String Same as for POST search/jobs.
enable_lookups Bool Same as for POST search/jobs.
force_bundle_replication Bool Same as for POST search/jobs.
id String Same as for POST search/jobs.
latest_time String Same as for POST search/jobs.
max_time Number Same as for POST search/jobs.
namespace String Same as for POST search/jobs.
now String Same as for POST search/jobs.
output_mode Enum xml Valid values: (csv | raw | xml | json)

Specifies the format for the returned output.

reduce_freq Number Same as for POST search/jobs.
reload_macros Bool Same as for POST search/jobs.
remote_server_list String Same as for POST search/jobs.
required_field_list String Same as for POST search/jobs.
rf String Same as for POST search/jobs.
rt_blocking Bool Same as for POST search/jobs.
rt_indexfilter Bool Same as for POST search/jobs.
rt_maxblocksecs Number Same as for POST search/jobs.
rt_queue_size Number Same as for POST search/jobs.
search_listener String Same as for POST search/jobs.
search_mode Enum Same as for POST search/jobs.
sync_bundle_replication Bool Same as for POST search/jobs.
time_format String Same as for POST search/jobs.
timeout Number Same as for POST search/jobs.

Response Codes

Status Code Description
200 Searched successfully.

Returned Values

No values returned for this request.

Example

Performs a blocking search for the most recent events in the internal index.

The search string for the search parameter must be prefixed with "search." Thus, it is in the form: 

 search search_string

URI-encode the search string to make sure characters such as the equals sign or path separators are interpreted correctly. This example replaces the equals sign,'=', with '%3D'. 

search="search index=_internal | head 1"

with 

search="search index%3D_internal | head 1"


curl -k -u admin:pass https://localhost:8089/servicesNS/admin/search/search/jobs/export \
	-d search="search index%3D_internal | head 1"



<results preview='0'>
<meta>
<fieldOrder>
<field>_cd</field>
<field>_indextime</field>
<field>_raw</field>
<field>_serial</field>
<field>_si</field>
<field>_sourcetype</field>
<field>_subsecond</field>
<field>_time</field>
<field>host</field>
<field>index</field>
<field>linecount</field>
<field>source</field>
<field>sourcetype</field>
<field>splunk_server</field>
</fieldOrder>
</meta>
<messages>
  <msg type="DEBUG">base lispy: [ AND index::_internal ]</msg>
  <msg type="DEBUG">search context: user="admin", app="search", bs-pathname="/Applications/splunk/etc"</msg>
  <msg type="INFO">Your timerange was substituted based on your search string</msg>
</messages>

	<result offset='0'>
		<field k='_cd'>
			<value><text>50:59480</text></value>
		</field>
		<field k='_indextime'>
			<value><text>1333739623</text></value>
		</field>
		<field k='_raw'><v xml:space='preserve' trunc='0'>127.0.0.1 - admin [06/Apr/2012:12:13:42.943 -0700] "POST /servicesNS/admin/search/search/jobs/export HTTP/1.1" 200 2063 - - - 317ms</v></field>
		<field k='_serial'>
			<value><text>0</text></value>
		</field>
		<field k='_si'>
			<value><text>vgenovese-mbp15.splunk.com</text></value>
			<value><text>_internal</text></value>
		</field>
		<field k='_sourcetype'>
			<value><text>splunkd_access</text></value>
		</field>
		<field k='_subsecond'>
			<value><text>.943</text></value>
		</field>
		<field k='_time'>
			<value><text>2012-04-06 12:13:42.943 PDT</text></value>
		</field>
		<field k='host'>
			<value><text>vgenovese-mbp15.splunk.com</text></value>
		</field>
		<field k='index'>
			<value h='1'><text>_internal</text></value>
		</field>
		<field k='linecount'>
			<value><text>1</text></value>
		</field>
		<field k='source'>
			<value><text>/Applications/splunk/var/log/splunk/splunkd_access.log</text></value>
		</field>
		<field k='sourcetype'>
			<value><text>splunkd_access</text></value>
		</field>
		<field k='splunk_server'>
			<value><text>vgenovese-mbp15.splunk.com</text></value>
		</field>
	</result>
</results>

search/jobs/{search_id}

DELETE search/jobs/{search_id}

Deletes the search job specified by {search_id}.

{search_id} is the <sid> field returned from the GET operation for the search/jobs endpoint.

Request

No parameters for this request.

Response Codes

Status Code Description
200 Deleted successfully.
404 Search job does not exist.

Returned Values

No values returned for this request.

Example

Deletes the specified search job. The {search_id} was obtained from the <sid> field returned by the GET operation for /search/jobs.

This example uses the <sid> created for the example for the POST operation to search/jobs. 


curl -k -u admin:pass --request DELETE https://localhost:8089/services/search/jobs/mysearch_02151949



<response><messages><msg type='INFO'>Search job cancelled.</msg></messages></response>

GET search/jobs/{search_id}

Return details about the search job specified by {search_id}.

The user ID is implied by the authentication to the call.

Information returned includes the search job properties, such as eventCount (number of events returned), runDuration (time the search took to complete), and others. The parameters to POST /search/jobs provides details on search job properties when creating a search. Search job properties are also described in the Search Reference.

The dispatchState property is of particular interest to determine the state of a search, and can contain the following values:

QUEUED
PARSING
RUNNING
PAUSED
FINALIZING
FAILED
DONE

This operation also returns performance information for the search. Refer to Execution costs in the Search Reference for more information.

For more information on searches in Splunk, refer to the Splunk Search Reference.

POST /search/jobs returns a <sid> for a search. You can also get a search ID from the <sid> field returned from GET search/jobs.

Request

No parameters for this request.

Response Codes

Status Code Description
200 Listed successfully.
404 Search job does not exist.

Returned Values

No values returned for this request.

Example

Lists summary information about a search job. The {search_id} was obtained from the <sid> field returned by the GET operation for /search/jobs.

This example uses the search ID (<sid>) created for the example for the POST operation to search/jobs. 


curl -k -u admin:pass https://localhost:8089/services/search/jobs/mysearch_02151949



<entry
       xmlns="http://www.w3.org/2005/Atom"
       xmlns:s="http://dev.splunk.com/ns/rest"
       xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>search index</title>
  <id>https://localhost:8089/services/search/jobs/mysearch_02151949</id>
  <updated>2011-07-07T20:49:58.000-07:00</updated>
  <link href="/services/search/jobs/mysearch_02151949" rel="alternate"/>
  <published>2011-07-07T20:49:57.000-07:00</published>
  <link href="/services/search/jobs/mysearch_02151949/search.log" rel="search.log"/>
  <link href="/services/search/jobs/mysearch_02151949/events" rel="events"/>
  <link href="/services/search/jobs/mysearch_02151949/results" rel="results"/>
  <link href="/services/search/jobs/mysearch_02151949/results_preview" rel="results_preview"/>
  <link href="/services/search/jobs/mysearch_02151949/timeline" rel="timeline"/>
  <link href="/services/search/jobs/mysearch_02151949/summary" rel="summary"/>
  <link href="/services/search/jobs/mysearch_02151949/control" rel="control"/>
  <author>
    <name>admin</name>
  </author>
  <content type="text/xml">
    <s:dict>
      <s:key name="cursorTime">1969-12-31T16:00:00.000-08:00</s:key>
      <s:key name="delegate"></s:key>
      <s:key name="diskUsage">2174976</s:key>
      <s:key name="dispatchState">DONE</s:key>
      <s:key name="doneProgress">1.00000</s:key>
      <s:key name="dropCount">0</s:key>
      <s:key name="earliestTime">2011-07-07T11:18:08.000-07:00</s:key>
      <s:key name="eventAvailableCount">287</s:key>
      <s:key name="eventCount">287</s:key>
      <s:key name="eventFieldCount">6</s:key>
      <s:key name="eventIsStreaming">1</s:key>
      <s:key name="eventIsTruncated">0</s:key>
      <s:key name="eventSearch">search index</s:key>
      <s:key name="eventSorting">desc</s:key>
      <s:key name="isDone">1</s:key>
      <s:key name="isFailed">0</s:key>
      <s:key name="isFinalized">0</s:key>
      <s:key name="isPaused">0</s:key>
      <s:key name="isPreviewEnabled">0</s:key>
      <s:key name="isRealTimeSearch">0</s:key>
      <s:key name="isRemoteTimeline">0</s:key>
      <s:key name="isSaved">0</s:key>
      <s:key name="isSavedSearch">0</s:key>
      <s:key name="isZombie">0</s:key>
      <s:key name="keywords">index</s:key>
      <s:key name="label"></s:key>
      <s:key name="latestTime">1969-12-31T16:00:00.000-08:00</s:key>
      <s:key name="numPreviews">0</s:key>
      <s:key name="priority">5</s:key>
      <s:key name="remoteSearch">litsearch index | fields  keepcolorder=t "host" "index" "linecount" "source" "sourcetype" "splunk_server"</s:key>
      <s:key name="reportSearch"></s:key>
      <s:key name="resultCount">287</s:key>
      <s:key name="resultIsStreaming">1</s:key>
      <s:key name="resultPreviewCount">287</s:key>
      <s:key name="runDuration">1.004000</s:key>
      <s:key name="scanCount">287</s:key>
      <s:key name="sid">mysearch_02151949</s:key>
      <s:key name="statusBuckets">0</s:key>
      <s:key name="ttl">516</s:key>
      <s:key name="performance">
        <s:dict>
          <s:key name="command.fields">
            <s:dict>
              <s:key name="duration_secs">0.004</s:key>
              <s:key name="invocations">4</s:key>
              <s:key name="input_count">287</s:key>
              <s:key name="output_count">287</s:key>
            </s:dict>
          </s:key>
          <s:key name="command.search">
            <s:dict>
              <s:key name="duration_secs">0.089</s:key>
              <s:key name="invocations">4</s:key>
              <s:key name="input_count">0</s:key>
              <s:key name="output_count">287</s:key>
            </s:dict>
          </s:key>
          <s:key name="command.search.fieldalias">
            <s:dict>
              <s:key name="duration_secs">0.002</s:key>
              <s:key name="invocations">2</s:key>
              <s:key name="input_count">287</s:key>
              <s:key name="output_count">287</s:key>
            </s:dict>
          </s:key>
          <s:key name="command.search.index">
            <s:dict>
              <s:key name="duration_secs">0.005</s:key>
              <s:key name="invocations">4</s:key>
            </s:dict>
          </s:key>
          <s:key name="command.search.kv">
            <s:dict>
              <s:key name="duration_secs">0.002</s:key>
              <s:key name="invocations">2</s:key>
            </s:dict>
          </s:key>
          <s:key name="command.search.lookups">
            <s:dict>
              <s:key name="duration_secs">0.002</s:key>
              <s:key name="invocations">2</s:key>
              <s:key name="input_count">287</s:key>
              <s:key name="output_count">287</s:key>
            </s:dict>
          </s:key>
          <s:key name="command.search.rawdata">
            <s:dict>
              <s:key name="duration_secs">0.083</s:key>
              <s:key name="invocations">2</s:key>
            </s:dict>
          </s:key>
          <s:key name="command.search.tags">
            <s:dict>
              <s:key name="duration_secs">0.004</s:key>
              <s:key name="invocations">4</s:key>
              <s:key name="input_count">287</s:key>
              <s:key name="output_count">287</s:key>
            </s:dict>
          </s:key>
          <s:key name="command.search.typer">
            <s:dict>
              <s:key name="duration_secs">0.004</s:key>
              <s:key name="invocations">4</s:key>
              <s:key name="input_count">287</s:key>
              <s:key name="output_count">287</s:key>
            </s:dict>
          </s:key>
          <s:key name="dispatch.createProviderQueue">
            <s:dict>
              <s:key name="duration_secs">0.059</s:key>
              <s:key name="invocations">1</s:key>
            </s:dict>
          </s:key>
          <s:key name="dispatch.evaluate">
            <s:dict>
              <s:key name="duration_secs">0.037</s:key>
              <s:key name="invocations">1</s:key>
            </s:dict>
          </s:key>
          <s:key name="dispatch.evaluate.search">
            <s:dict>
              <s:key name="duration_secs">0.036</s:key>
              <s:key name="invocations">1</s:key>
            </s:dict>
          </s:key>
          <s:key name="dispatch.fetch">
            <s:dict>
              <s:key name="duration_secs">0.092</s:key>
              <s:key name="invocations">5</s:key>
            </s:dict>
          </s:key>
          <s:key name="dispatch.readEventsInResults">
            <s:dict>
              <s:key name="duration_secs">0.110</s:key>
              <s:key name="invocations">1</s:key>
            </s:dict>
          </s:key>
          <s:key name="dispatch.stream.local">
            <s:dict>
              <s:key name="duration_secs">0.089</s:key>
              <s:key name="invocations">4</s:key>
            </s:dict>
          </s:key>
          <s:key name="dispatch.timeline">
            <s:dict>
              <s:key name="duration_secs">0.359</s:key>
              <s:key name="invocations">5</s:key>
            </s:dict>
          </s:key>
        </s:dict>
      </s:key>
      <s:key name="messages">
        <s:dict/>
      </s:key>
      <s:key name="request">
        <s:dict>
          <s:key name="id">mysearch_02151949</s:key>
          <s:key name="search">search index</s:key>
        </s:dict>
      </s:key>
      <s:key name="eai:acl">
        <s:dict>
          <s:key name="perms">
            <s:dict>
              <s:key name="read">
                <s:list>
                  <s:item>admin</s:item>
                </s:list>
              </s:key>
              <s:key name="write">
                <s:list>
                  <s:item>admin</s:item>
                </s:list>
              </s:key>
            </s:dict>
          </s:key>
          <s:key name="owner">admin</s:key>
          <s:key name="modifiable">true</s:key>
          <s:key name="sharing">global</s:key>
          <s:key name="app">search</s:key>
          <s:key name="can_write">true</s:key>
        </s:dict>
      </s:key>
      <s:key name="searchProviders">
        <s:list>
          <s:item>vgenovese-mbp15.splunk.com</s:item>
        </s:list>
      </s:key>
    </s:dict>
  </content>
</entry>

search/jobs/{search_id}/control

POST search/jobs/{search_id}/control

Executes a job control command for the search specified by {search_id}.

Request

Name Type Required Default Description
action Enum
✓
 Valid values: (pause | unpause | finalize | cancel | touch | setttl | setpriority | enablepreview | disablepreview)

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.

touch: Extends the expiration time of the search to now + ttl

setttl: Change the ttl of the search. Arguments: ttl=<number>

setpriority: Sets the priority of the search process. Arguments: priority=<0-10>

enablepreview: Enable preview generation (may slow search considerably).

disablepreview: Disable preview generation.

Response Codes

Status Code Description
200 Updated successfully.
403 Insufficient permissions to edit control action for search job.
404 Search job does not exist.

Returned Values

No values returned for this request.

Example

Pauses the search specified by the search ID (<sid>) mysearch_02151949. 


curl -k -u admin:pass https://localhost:8089/services/search/jobs/mysearch_02151949/control \
	-d action=pause



<response><messages><msg type='INFO'>Search job paused.</msg></messages></response>

search/jobs/{search_id}/events

GET search/jobs/{search_id}/events

Returns the events of the search specified by {search_id}. These events are the data from the search pipeline before the first "transforming" search command. This is the primary method for a client to fetch a set of UNTRANSFORMED events for the search job.

This endpoint is only valid if the status_buckets > 0 or the search has no transforming commands.


Request

Note: These parameters can also be passed to GET search/jobs/export.

Name Type Required Default Description
count Number 100 The maximum number of results to return. If value is set to 0, then all available results are returned. Default value is 100.
earliest_time String A time string representing the earliest (inclusive), respectively, time bounds for the results to be returned. If not specified, the range applies to all results found.
f String A field to return for the event set.

You can pass multiple POST f arguments if multiple field are required. If field_list and f are provided, the union of the lists is used.

field_list String * Deprecated. Consider using f.

A comma-separated list of the fields to return for the event set.

latest_time String A time string representing the latest (exclusive), respectively, time bounds for the results to be returned. If not specified, the range applies to all results found.
max_lines Number 0 The maximum lines that any single event's _raw field should contain.

Specify 0 to specify no limit.

offset Number 0 The first result (inclusive) from which to begin returning data.

This value is 0-indexed. Default value is 0.

In 4.1+, negative offsets are allowed and are added to count to compute the absolute offset (for example, offset=-1 is the last available offset. Offsets in the results are always absolute and never negative.

output_mode Enum xml Valid values: (csv | raw | xml | json)

Specifies what format the output should be returned in.

output_time_format String time_format Formats a UTC time. Defaults to what is specified in time_format.
search String The post processing search to apply to results. Can be any valid search language string.
segmentation String raw The type of segmentation to perform on the data. This incudes an option to perform k/v segmentation.
time_format String  %m/%d/%Y:%H:%M:%S Expression to convert a formatted time string from {start,end}_time into UTC seconds.

It defaults to %m/%d/%Y:%H:%M:%S

truncation_mode String abstract Specifies how "max_lines" should be achieved.

Valid values are {abstract, truncate}. Default value is abstract.

Response Codes

Status Code Description
200 Listed successfully.
204 Search was found, but events are not yet ready. Retry request.
404 Search job does not exist.

Returned Values

No values returned for this request.

Example

Returns a set of untransformed events, listing the fields arch, build, connectionType and date_hour in the default XML format.

This example returns three sets of results. By default, this endpoint returns 100 sets of events. 


curl -k -u admin:pass https://localhost:8089/services/search/jobs/1312313809.20/events --get \
	-d f=arch \
	-d f=build \
	-d f=connectionType \
	-d r \
	-d count=3



<results preview='0'>
<meta>
<fieldOrder>
<field>arch</field>
<field>build</field>
<field>connectionType</field>
<field>date_hour</field>
</fieldOrder>
</meta>
	<result offset='0'>
		<field k='arch'>
			<value><text>i686</text></value>
		</field>
		<field k='build'>
			<value><text>98164</text></value>
		</field>
		<field k='connectionType'>
			<value><text>cooked</text></value>
		</field>
		<field k='date_hour'>
			<value><text>19</text></value>
		</field>
	</result>
	<result offset='1'>
		<field k='arch'>
			<value><text>i686</text></value>
		</field>
		<field k='build'>
			<value><text>98164</text></value>
		</field>
		<field k='connectionType'>
			<value><text>cooked</text></value>
		</field>
		<field k='date_hour'>
			<value><text>19</text></value>
		</field>
	</result>
	<result offset='2'>
		<field k='arch'>
			<value><text>i686</text></value>
		</field>
		<field k='build'>
			<value><text>98164</text></value>
		</field>
		<field k='connectionType'>
			<value><text>cooked</text></value>
		</field>
		<field k='date_hour'>
			<value><text>19</text></value>
		</field>
	</result>
</results>

search/jobs/{search_id}/results

GET search/jobs/{search_id}/results

Returns the results of the search specified by {search_id}. This is the table that exists after all processing from the search pipeline has completed.

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, however with fewer options.

Request

Note: These parameters can also be passed to GET search/jobs/export.

Name Type Required Default Description
count Number 100 The maximum number of results to return. If value is set to 0, then all available results are returned.
f String A field to return for the event set.

You can pass multiple POST f arguments if multiple field are required. If field_list and f are provided the union of the lists is used.

field_list String * Specify a comma-separated list of the fields to return for the event set.
offset Number 0 The first result (inclusive) from which to begin returning data.

This value is 0-indexed. Default value is 0.

In 4.1+, negative offsets are allowed and are added to count to compute the absolute offset (for example, offset=-1 is the last available offset).

Offsets in the results are always absolute and never negative.

output_mode Enum xml Valid values: (csv | raw | xml | json)

Specifies what format the output should be returned in.

search String The post processing search to apply to results. Can be any valid search language string.

Response Codes

Status Code Description
200 Listed successfully.
204 Search was found, but events are not yet ready. Retry request.
404 Search job does not exist.

Returned Values

No values returned for this request.

Example

Returns a set of transformed events for the search, listing the fields index, source, and sourcetype in JSON format.

This example returns three sets of results. By default, this endpoint returns 100 sets of events. 


curl -k -u admin:pass https://localhost:8089/services/search/jobs/mysearch_02151949/results --get \
	-d f=index \
	-d f=source \
	-d f=sourcetype \
	-d count=3 \
	-d output_mode=json



[
	{
		"index": "os",
		"source": "lsof",
		"sourcetype": "lsof"
	},
	{
		"index": "os",
		"source": "lsof",
		"sourcetype": "lsof"
	},
	{
		"index": "os",
		"source": "lsof",
		"sourcetype": "lsof"
	}
]

search/jobs/{search_id}/results_preview

GET search/jobs/{search_id}/results_preview

Provides preview results for search jobs.

Returns the intermediate preview results of the search specified by {search_id}. When the job is complete, this gives the same response as /search/jobs/{search_id}/results. Preview is enabled for realtime searches and for searches where status_buckets > 0.

Request

Name Type Required Default Description
count Number 100 The maximum number of results to return.

If value is set to 0, then all available results are returned.

f String A field to return for the event set.

You can pass multiple POST f arguments if multiple field are required. If field_list and f are provided the union of the lists is used.

field_list String Specify a comma-separated list of the fields to return for the event set.
offset Number 0 The first result (inclusive) from which to begin returning data.

This value is 0-indexed. Default value is 0.

In 4.1+, negative offsets are allowed and are added to count to compute the absolute offset (for example, offset=-1 is the last available offset).

Offsets in the results are always absolute and never negative.

output_mode String xml Valid values: (csv | raw | xml | json)

Specifies what format the output should be returned in.

search String The post processing search to apply to results. Can be any valid search language string.

Response Codes

Status Code Description
200 Listed successfully.
204 Search was found, but events are not yet ready. Retry request.
404 Search job does not exist.

Returned Values

No values returned for this request.

Example

Returns preview results for the search, listing the fields index, source, and sourcetype in JSON format.

This example returns three sets of results. By default, this endpoint returns 100 sets of events. 


curl -k -u admin:pass \
	https://localhost:8089/services/search/jobs/mysearch_02151949/results_preview --get \
	-d f=index \
	-d f=source \
	-d f=sourcetype \
	-d count=3 \
	-d output_mode=json



[
	{
		"index": "os",
		"source": "lsof",
		"sourcetype": "lsof"
	},
	{
		"index": "os",
		"source": "lsof",
		"sourcetype": "lsof"
	},
	{
		"index": "os",
		"source": "lsof",
		"sourcetype": "lsof"
	}
]

search/jobs/{search_id}/search.log

GET search/jobs/{search_id}/search.log

Returns the search.log for the search job specified by {search_id}.

Request

Name Type Required Default Description
attachment Boolean false If true, returns search.log as an attachment. Otherwise, streams search.log.

Response Codes

Status Code Description
200 Listed successfully.
204 Search was found, but events are not yet ready. Retry request.
404 Search log does not exist.

Returned Values

No values returned for this request.

Example

Returns the search log for the search specified by mysearch_02151949.

Only a few lines of the search log are listed in the response. 


curl -k -u admin:pass https://localhost:8089/services/search/jobs/mysearch_02151949/search.log



07-07-2011 21:36:22.066 INFO  ApplicationManager - Found application directory: /Applications/splunk4.3/etc/apps/user-prefs
07-07-2011 21:36:22.066 INFO  ApplicationManager - Initialized at least 12 applications: /Applications/splunk4.3/etc/apps
07-07-2011 21:36:22.066 INFO  ApplicationManager - Found 5 application(s) that might have global exports
07-07-2011 21:36:22.073 INFO  dispatchRunner - initing LicenseMgr in search process: nonPro=0
07-07-2011 21:36:22.074 INFO  LicenseMgr - Initing LicenseMgr
07-07-2011 21:36:22.075 INFO  ServerConfig - My GUID is "1F3A34AE-75DA-4680-B184-5BF309843919".
07-07-2011 21:36:22.075 INFO  ServerConfig - My hostname is "ombroso-mbp15.local".
07-07-2011 21:36:22.076 INFO  SSLCommon - added zlib compression
07-07-2011 21:36:22.077 INFO  ServerConfig - Default output queue for file-based input: parsingQueue.
07-07-2011 21:36:22.077 INFO  LMConfig - serverName=ombroso-mbp15.splunk.com guid=1F3A34AE-75DA-4680-B184-5BF309843919 
07-07-2011 21:36:22.077 INFO  LMConfig - connection_timeout=30
07-07-2011 21:36:22.077 INFO  LMConfig - send_timeout=30
07-07-2011 21:36:22.077 INFO  LMConfig - receive_timeout=30
. . .

search/jobs/{search_id}/summary

GET search/jobs/{search_id}/summary

Returns "getFieldsAndStats" output of the so-far-read events.

This endpoint is only valid when status_buckets > 0. To guarantee a set of fields in the summary, when creating the search, use the required_fields_list or rf parameters.

Request

Name Type Required Default Description
earliest_time String Time string representing 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. (Also see comment for the search_mode variable.)

f String A field to return for the event set.

You can pass multiple POST f arguments if multiple field are required. If field_list and f are provided, the union of the lists is used.

field_list String Deprecated. Consider using f.

A comma-separated list of the fields to return for the event set.

latest_time String Time string representing 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. (Also see comment for the search_mode variable.)

min_freq Number 0 For each key, the fraction of results this key must occur in to be displayed.

Express the fraction as a number between 0 and 1.

output_time_format String  %FT%T.%Q%:z Formats a UTC time. Defaults to what is specified in time_format.
search String Empty string Specifies a substring that all returned events should contain either in one of their values or tags.
time_format String  %m/%d/%Y:%H:%M:% Expression to convert a formatted time string from {start,end}_time into UTC seconds.

It defaults to %m/%d/%Y:%H:%M:%S

top_count Number 10 For each key, specfies how many of the most frequent items to return.

Response Codes

Status Code Description
200 Listed successfully.
403 Insufficient permissions to view summary for search job.
404 Summary for search job does not exist.

Returned Values

No values returned for this request.

Example

Returns the field summary information that is usually used to populate the fields picker in the default search view. This examples returns the summary in XML format for only the fields source, sourcetype, and host. For each field, also return the 5 most common values for the field. The summary information is over the entire timerange of the search. 

curl -k -u admin:pass https://localhost:8089/services/search/jobs/mytestsid/summary --get \
	-d f=source \
	-d f=sourcetype \
	-d f=host \
	-d top_count=5



<?xml version='1.0' encoding='UTF-8'?>
<summary earliest_time='1969-12-31T16:00:00.000-08:00' latest_time='1969-12-31T16:00:00.464-08:00' duration='0' c='150375'>
	<field k='host' c='150375' nc='0' dc='1' exact='1'>
		<modes>
			<value c='150375' exact='1'><text>tiny</text></value>		</modes>
	</field>
	<field k='source' c='150375' nc='0' dc='13' exact='1'>
		<modes>
			<value c='136107' exact='1'><text>/mnt/scsi/steveyz/splunksi/var/log/splunk/metrics.log</text></value>			<value c='6682' exact='1'><text>/mnt/scsi/steveyz/splunksi/var/log/splunk/splunkd_access.log</text></value>			<value c='4656' exact='1'><text>/mnt/scsi/steveyz/splunksi/var/log/splunk/scheduler.log</text></value>			<value c='1714' exact='1'><text>/mnt/scsi/steveyz/splunksi/var/log/splunk/web_access.log</text></value>			<value c='937' exact='1'><text>/mnt/scsi/steveyz/splunksi/var/log/splunk/splunkd.log</text></value>		</modes>
	</field>
	<field k='sourcetype' c='150375' nc='0' dc='10' exact='1'>
		<modes>
			<value c='137053' exact='1'><text>splunkd</text></value>			<value c='6682' exact='1'><text>splunkd_access</text></value>			<value c='4656' exact='1'><text>scheduler</text></value>			<value c='1714' exact='1'><text>splunk_web_access</text></value>			<value c='193' exact='1'><text>splunk_web_service</text></value>		</modes>
	</field>
</summary>

search/jobs/{search_id}/timeline

GET search/jobs/{search_id}/timeline

Returns event distribution over time of the so-far-read untransformed events.

This endpoint is only valid when status_buckets > 0. To guarantee a set of fields in the summary, when creating the search, use the required_fields_list or rf parameters.

Request

Name Type Required Default Description
output_time_format String  %FT%T.%Q%:z Formats a UTC time. Defaults to what is specified in time_format.
time_format String  %m/%d/%Y:%H:%M:%S Expression to convert a formatted time string from {start,end}_time into UTC seconds.

It defaults to %m/%d/%Y:%H:%M:%S

Response Codes

The output from this endpoint provides values for the following fields:

Field Description
c Event count
a Available. Not all events in a bucket are retrievable. Generally capped at 10000.
t Time in epoch seconds
d Bucket size (time)
f Indicates if the search finished scanning events from the time range of this bucket.
etz Timezone offset, in seconds, for the earliest time of this bucket.

etz and ltz are different if the buckets are months or days and you have a DST change during the middle.

ltz Timezone offset, in seconds, for the latest time of this bucket.
Status Code Description
200 Listed successfully.
204 Search was found, but events are not yet ready. Retry request.
404 Timeline for search job does not exist.

Returned Values

No values returned for this request.

Example

Get the information usually used to populate the timeline, which is basically just a breakdown of the event distribution over time. Render times using the splunk server's locale time format 

curl -k -u admin:pass https://localhost:8089/services/search/jobs/mytestsid/timeline --get \
	-d time_format="%c"



<timeline c='150397' cursor='1312308000'>
<bucket c='7741' a='7741' t='1312308000.000' d='3600' f='1' etz='-25200' ltz='-25200'>Tue Aug  2 11:00:00 2011</bucket>
<bucket c='7894' a='7894' t='1312311600.000' d='3600' f='1' etz='-25200' ltz='-25200'>Tue Aug  2 12:00:00 2011</bucket>
<bucket c='7406' a='7406' t='1312315200.000' d='3600' f='1' etz='-25200' ltz='-25200'>Tue Aug  2 13:00:00 2011</bucket>
<bucket c='6097' a='6097' t='1312318800.000' d='3600' f='1' etz='-25200' ltz='-25200'>Tue Aug  2 14:00:00 2011</bucket>
<bucket c='6072' a='6072' t='1312322400.000' d='3600' f='1' etz='-25200' ltz='-25200'>Tue Aug  2 15:00:00 2011</bucket>
<bucket c='6002' a='6002' t='1312326000.000' d='3600' f='1' etz='-25200' ltz='-25200'>Tue Aug  2 16:00:00 2011</bucket>
<bucket c='6004' a='6004' t='1312329600.000' d='3600' f='1' etz='-25200' ltz='-25200'>Tue Aug  2 17:00:00 2011</bucket>
<bucket c='5994' a='5994' t='1312333200.000' d='3600' f='1' etz='-25200' ltz='-25200'>Tue Aug  2 18:00:00 2011</bucket>
<bucket c='6037' a='6037' t='1312336800.000' d='3600' f='1' etz='-25200' ltz='-25200'>Tue Aug  2 19:00:00 2011</bucket>
<bucket c='6021' a='6021' t='1312340400.000' d='3600' f='1' etz='-25200' ltz='-25200'>Tue Aug  2 20:00:00 2011</bucket>
<bucket c='6051' a='6051' t='1312344000.000' d='3600' f='1' etz='-25200' ltz='-25200'>Tue Aug  2 21:00:00 2011</bucket>
<bucket c='6006' a='6006' t='1312347600.000' d='3600' f='1' etz='-25200' ltz='-25200'>Tue Aug  2 22:00:00 2011</bucket>
<bucket c='6041' a='6041' t='1312351200.000' d='3600' f='1' etz='-25200' ltz='-25200'>Tue Aug  2 23:00:00 2011</bucket>
<bucket c='5993' a='5993' t='1312354800.000' d='3600' f='1' etz='-25200' ltz='-25200'>Wed Aug  3 00:00:00 2011</bucket>
<bucket c='6040' a='6040' t='1312358400.000' d='3600' f='1' etz='-25200' ltz='-25200'>Wed Aug  3 01:00:00 2011</bucket>
<bucket c='5993' a='5993' t='1312362000.000' d='3600' f='1' etz='-25200' ltz='-25200'>Wed Aug  3 02:00:00 2011</bucket>
<bucket c='6061' a='6061' t='1312365600.000' d='3600' f='1' etz='-25200' ltz='-25200'>Wed Aug  3 03:00:00 2011</bucket>
<bucket c='5995' a='5995' t='1312369200.000' d='3600' f='1' etz='-25200' ltz='-25200'>Wed Aug  3 04:00:00 2011</bucket>
<bucket c='5988' a='5988' t='1312372800.000' d='3600' f='1' etz='-25200' ltz='-25200'>Wed Aug  3 05:00:00 2011</bucket>
<bucket c='6042' a='6042' t='1312376400.000' d='3600' f='1' etz='-25200' ltz='-25200'>Wed Aug  3 06:00:00 2011</bucket>
<bucket c='5998' a='5998' t='1312380000.000' d='3600' f='1' etz='-25200' ltz='-25200'>Wed Aug  3 07:00:00 2011</bucket>
<bucket c='6055' a='6055' t='1312383600.000' d='3600' f='1' etz='-25200' ltz='-25200'>Wed Aug  3 08:00:00 2011</bucket>
<bucket c='5997' a='5997' t='1312387200.000' d='3600' f='1' etz='-25200' ltz='-25200'>Wed Aug  3 09:00:00 2011</bucket>
<bucket c='5994' a='5994' t='1312390800.000' d='3600' f='1' etz='-25200' ltz='-25200'>Wed Aug  3 10:00:00 2011</bucket>
<bucket c='875' a='875' t='1312394400.000' d='3600' f='1' etz='-25200' ltz='-25200'>Wed Aug  3 11:00:00 2011</bucket>
</timeline>


search/parser

Provide search language parsing services.

GET search/parser

Parses Splunk search language and returns semantic map.

Request

Name Type Required Default Description
q String
✓
 The search string to parse.
enable_lookups Boolean false If true, reverse lookups are done to expand the search expression.
output_mode String xml Specify output formatting. Select from either: 
 xml:  XML formatting
 json: JSON formatting
parse_only Boolean false If true, disables expansion of search due evaluation of subsearches, time term expansion, lookups, tags, eventtypes, sourcetype alias.
reload_macros Boolean true If true, reload macro definitions from macros.conf.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.

Returned Values

No values returned for this request.

Example

Returns the semantic map for the specified search string in JSON format.

In the q parameter, the search operator, search, is prefixed to the search string.

For this example, --get prevents the operation from being interpreted as a POST operation. 


curl -k -u admin:pass https://localhost:8089/servicesNS/admin/search/search/parser --get \
	-d output_mode=json \
	-d q="search index=os sourcetype=cpu"



{
	"remoteSearch": "litsearch  | fields  keepcolorder=t \"host\" \"index\" \"linecount\" \"source\" \"sourcetype\" \"splunk_server\"",
	"remoteTimeOrdered": true,
	"eventsSearch": "search ",
	"eventsTimeOrdered": true,
	"eventsStreaming": true,
	"reportsSearch": "",
	"commands": [
		{
			"command": "search",
			"rawargs": "",
			"pipeline": "streaming",
			"args": {
				"search": [""],
			}
			"isGenerating": true,
			"streamType": "SP_STREAM",
		},
	]
}


search/timeparser

Provides time argument parsing.

GET search/timeparser

Returns a lookup table of time arguments to absolute timestamps.

Request

Name Type Required Default Description
time String
✓
 The time argument to parse.

Acceptable inputs are either a relative time identifier or an absolute time. Multiple time arguments can be passed by specifying multiple time parameters.

now String The time to use as current time for relative time identifiers.

Can itself either be a relative time (from the real "now" time) or an absolute time in the format specified by time_format.

output_time_format String  %FT%T.%Q%:z Used to format a UTC time. Defaults to the value of time_format.
time_format String  %FT%T.%Q%:z The format (strftime) of the absolute time format passed in time.

This field is not used if a relative time identifier is provided. For absolute times, the default value is the ISO-8601 format.

Response Codes

Status Code Description
200 Listed successfully.
204 No timeparser arguments given.
400 Request error. See response body for details.

Returned Values

No values returned for this request.

Example

Returns a lookup table of absolute timestamps for the supplied time parameters. 


curl -k -u admin:pass https://localhost:8089/servicesNS/admin/search/search/timeparser --get \
	-d time=-12h \
	-d time=-24h





<response>
	<dict>
		<key name="-12h">2011-07-06T21:54:23.000-07:00</key>
		<key name="-24h">2011-07-06T09:54:23.000-07:00</key>
	</dict>
</response>


search/typeahead

Provides search string auto-complete suggestions.

GET search/typeahead

Returns a list of words or descriptions for possible auto-complete terms.

count is a required parameter to specify how many descriptions to list. prefix is a required parameter to specify a string for terms in your index.

Request

Name Type Required Default Description
count Number
✓
 The number of counts to return for this term.
prefix String
✓
 The term for which to return typeahead results.
output_mode String xml Valid values: (xml | json)

Format for the output.

Response Codes

Status Code Description
200 Listed successfully.
204 No Content. The server successfully processed the request, but is not returning any content.
400 Request error. See response body for details.
403 Insufficient permissions to view typeahead results.
405 Invalid method (only GET is supported).

Returned Values

No values returned for this request.

Example

Returns 3 typeahead terms for the string "source," displaying the results in JSON format. 


curl -k -u admin:pass https://localhost:8089/servicesNS/admin/search/search/typeahead --get \
	-d count=3 \
	-d prefix=source \
	-d output_mode=json



[
	{
		"content": "source=\"cpu\"",
		"count": "181",
		"operator": "false"
	},
	{
		"content": "source=\"df\"",
		"count": "19",
		"operator": "false"
	},
	{
		"content": "source=\"hardware\"",
		"count": "1",
		"operator": "false"
	}
]
Retrieved from "http://docs.splunk.com/Documentation/Splunk/4.3.2/RESTAPI/RESTsearch"

This documentation applies to the following versions of Splunk: 4.2.2 , 4.2.3 , 4.2.4 , 4.2.5 , 4.3 , 4.3.1 , 4.3.2 , 4.3.3 , 4.3.4 , 4.3.5 , 4.3.6 View the Article History for its revisions.


Comments

Searches passed to the parser endpoint need to be URL encoded in order to get the correct results. When you use the proper quoting sequences for spaces etc., you get

{
"canSummarize": false,
"commands": [
{
"args": {
"search": [
"index=os sourcetype=cpu"
]
},
"command": "search",
"isGenerating": true,
"pipeline": "streaming",
"rawargs": "index=os sourcetype=cpu",
"streamType": "SP_STREAM"
}
],
"eventsSearch": "search index=os sourcetype=cpu",
"eventsStreaming": true,
"eventsTimeOrdered": true,
"remoteSearch": "litsearch index=os sourcetype=cpu | fields keepcolorder=t \"host\" \"index\" \"linecount\" \"source\" \"sourcetype\" \"splunk_server\"",
"remoteTimeOrdered": true,
"reportsSearch": ""
}

Note the args are different. This might be true in general, not just for the parser endpoint.

Salspaugh splunk, Splunker
July 27, 2012

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!