Events - EventSearchStatus List and Create Methods

URI

https://164.99.19.131:8443/SentinelRESTServices/objects/event-search-status

Supported Methods

GET
POST
GET

Authentication

Authentication Types
Sentinel Permissions Needed

Supported Formats

Response

URL Parameters

Required

None.

Optional

ParameterTypeDefault ValueDescription
query string [no filter] The TinyQ language filter that specifies a subset of all available records.
field string not present The name or names of fields whose values are to be returned. The field item may appear zero or more times in the URI query parameters. A single value of "[none]" indicates return only metadata. The absence of any field parameter indicates return all field values,
page integer 1 The 1-based offset into the total records based on page size. Actual offset is (page - 1) * pagesize.
pagesize integer [unlimited] The maximum number of object records to return as a result of the request.

Success Codes

Fault Codes

Response Data

Object type: page
A container for one or more objects in the result listing. There may be multiple pages in a listing if a page size is specified that is less than the total number of objects in the listing.
FieldDescription
nextA URL addressing the subsequent page of objects in the total set of available objects.
objectsThe list of objects returned in the page of results.
prevA URL addressing the previous page of objects in the total set of available objects.
Object type: event-search-status
An EventSearchStatus object is used to obtain the status of an existing search job without affecting the job's last-accessed time.
FieldDescription
aggregate-objAn "aggregating object" is a Sentinel object that has events associated with it. Current objects are Incidents and Correlated Events. Specifying an aggregating object restricts the results of the event search to only those events associated with the aggregating object.
availThe available count number indicates the total number of events that are currently available in the results that can be obtained from the search job.
endThe end of the search date range specifies the latest date and time for which events will be returned. The end of the range is exclusive.
event-searchThe URL referencing the EventSearch object for which the EventSearchStatus object is providing the status.
fieldsFields is the set of event field names whose values are to be returned in the search results. Limiting the result fields can descrease the amount of data that must be transported. The special value "none" indicates that no field values are to be returned. An empty set indicates that all field values are to be returned.
filterThe filter is the search query string that specifies the set of events that the event search job will return.
foundThe found count number indicates the total number of events found that match the search job parameters.
InitiatingHostNameThe hostname of the system that initiated the search job, if available.
init-userThe name of the user that initiated the search job. This may be different than the Owner username if the search job is for a distributed search.
ipThe IP address of the system from which the search job was initiated.
job-endThe job end time is the time the search job finished.
job-startThe job start time is the time the search job started running.
last-accessedThe last accessed time is the last time the search job was accessed for the purposes of getting search results.
max-resultsThe maximum results number specifies the maximum event objects that the search job will return. This may be less that the maximum event objects that match the search parameters.
metaThe metadata for an object, including the object type name and the URL reference to the object. Definition
ownerThe owner link is a URL that is used to obtain the user object of the user which started the search job. The link will be empty for SYSTEM search jobs.
pgsizeThe page size specifies the number of event objects that will be returned in a single request for the results of the search job.
resultsThe results link is a URL that is used to obtain the first page of the results of the search job.
startThe start of the search date range specifies the earliest date and time for which events will be returned. The start of the range is inclusive.
statusThe status of a search job reflects the search job's current state. Values are: 0 (Pending), 1 (Running), 2 (Completed), 3 (Completed with Errors), 4 (Unavailable), 5 (Canceled), 6 (Access Denied).
typeThe type of a search job indicates the use for which the search job is started. Values are: "SYSTEM", an internal Sentinel job. "USER", started by a Sentinel user. "REPORT", used to obtain the results for use in a report. "DATASYNC", started to obtain results that will be synchronized from the event store to a relational database. "DIST", indicating a search started on behalf of a remote search console.
Object type: meta
The metadata for an object, including the object type name and the URL reference to the object.
FieldDescription
@hrefThe URL reference to the object.
typeThe name of the object type

Sample Request

GET https://164.99.19.131:8443/SentinelRESTServices/objects/event-search-status?page=2&pagesize=1
Sample Response for application/json
Status: 200
{
   "objects":[
      {
         "meta":{
            "type":"event-search-status",
            "@href":"https://164.99.19.131:8443/SentinelRESTServices/objects/event-search-status/Wildebeest"
         },
         "status":2,
         "InitiatingHostName":"jdoe_desktop.company.com",
         "event-search":{
            "@href":"https://164.99.19.131:8443/SentinelRESTServices/objects/event-search/Wildebeest"
         },
         "pgsize":125,
         "last-accessed":"2012-04-25T13:33:44.563Z",
         "job-start":"2012-04-25T13:33:44.563Z",
         "avail":200000,
         "type":"USER",
         "ip":"10.0.0.23",
         "aggregate-obj":{
            "@href":"Wildebeest"
         },
         "results":{
            "@href":"https://164.99.19.131:8443/SentinelRESTServices/objects/event?query=_jobid_.eWildebeest&page=1&pagesize=125&field=dt&field=evt"
         },
         "max-results":42,
         "start":"2012-04-25T13:33:44.563Z",
         "job-end":"2012-04-25T13:33:44.563Z",
         "init-user":"jdoe",
         "end":"2012-04-25T13:33:44.563Z",
         "filter":"sev:4",
         "fields":[
            "dt",
            "evt"
         ],
         "found":1567345
      }
   ],
   "prev":{
      "@href":"https://164.99.19.131:8443/SentinelRESTServices/objects/event-search-status?pagesize=1&page=1"
   },
   "next":{
      "@href":"https://164.99.19.131:8443/SentinelRESTServices/objects/event-search-status?pagesize=1&page=3"
   }
}
POST

Authentication

Authentication Types
Sentinel Permissions Needed

Supported Formats

Request

Response

URL Parameters

None.

Success Codes

Fault Codes

Request Data

Object type: event-search-status
An EventSearchStatus object is used to obtain the status of an existing search job without affecting the job's last-accessed time.
FieldRequiredDescription
aggregate-objfalseAn "aggregating object" is a Sentinel object that has events associated with it. Current objects are Incidents and Correlated Events. Specifying an aggregating object restricts the results of the event search to only those events associated with the aggregating object.
endfalseThe end of the search date range specifies the latest date and time for which events will be returned. The end of the range is exclusive.
fieldsfalseFields is the set of event field names whose values are to be returned in the search results. Limiting the result fields can descrease the amount of data that must be transported. The special value "none" indicates that no field values are to be returned. An empty set indicates that all field values are to be returned.
filterfalseThe filter is the search query string that specifies the set of events that the event search job will return.
InitiatingHostNamefalseThe hostname of the system that initiated the search job, if available.
init-userfalseThe name of the user that initiated the search job. This may be different than the Owner username if the search job is for a distributed search.
ipfalseThe IP address of the system from which the search job was initiated.
job-endfalseThe job end time is the time the search job finished.
job-startfalseThe job start time is the time the search job started running.
last-accessedfalseThe last accessed time is the last time the search job was accessed for the purposes of getting search results.
max-resultsfalseThe maximum results number specifies the maximum event objects that the search job will return. This may be less that the maximum event objects that match the search parameters.
pgsizefalseThe page size specifies the number of event objects that will be returned in a single request for the results of the search job.
startfalseThe start of the search date range specifies the earliest date and time for which events will be returned. The start of the range is inclusive.
typefalseThe type of a search job indicates the use for which the search job is started. Values are: "SYSTEM", an internal Sentinel job. "USER", started by a Sentinel user. "REPORT", used to obtain the results for use in a report. "DATASYNC", started to obtain results that will be synchronized from the event store to a relational database. "DIST", indicating a search started on behalf of a remote search console.

Object type: meta
The metadata for an object, including the object type name and the URL reference to the object.
FieldRequiredDescription
@hreffalseThe URL reference to the object.
typefalseThe name of the object type

Response Data

Object type:
The metadata representation of the newly-created event-search-status object, including the URL reference to the new object.
FieldDescription
metaThe metadata for an object, including the object type name and the URL reference to the object. Definition
Object type: meta
The metadata for an object, including the object type name and the URL reference to the object.
FieldDescription
@hrefThe URL reference to the object.
typeThe name of the object type

Sample Request

POST https://164.99.19.131:8443/SentinelRESTServices/objects/event-search-status
{
   "InitiatingHostName":"jdoe_desktop.company.com",
   "event-search":{
      "@href":"https://164.99.19.131:8443/SentinelRESTServices/objects/event-search/Wildebeest"
   },
   "pgsize":125,
   "last-accessed":"2012-04-25T13:33:44.564Z",
   "job-start":"2012-04-25T13:33:44.564Z",
   "type":"USER",
   "ip":"10.0.0.23",
   "aggregate-obj":{
      "@href":"Wildebeest"
   },
   "results":{
      "@href":"https://164.99.19.131:8443/SentinelRESTServices/objects/event?query=_jobid_.eWildebeest&page=1&pagesize=125&field=dt&field=evt"
   },
   "max-results":42,
   "start":"2012-04-25T13:33:44.564Z",
   "job-end":"2012-04-25T13:33:44.564Z",
   "init-user":"jdoe",
   "end":"2012-04-25T13:33:44.564Z",
   "filter":"sev:4",
   "fields":[
      "dt",
      "evt"
   ]
}
Sample Response for application/json
Status: 201
Location:https://164.99.19.131:8443/SentinelRESTServices/objects/event-search-status/Wildebeest
{
   "meta":{
      "type":"event-search-status",
      "@href":"https://164.99.19.131:8443/SentinelRESTServices/objects/event-search-status/Wildebeest"
   }
}