Introduction
Query incidents for a given period of time based on properties of the incident or properties of the events correlated to the incidents. By default, incidents created in the last 7 days will be retrieved and filtered. A start time and end time can be provided to define the time range, but the range is limited to a 30 day period. The query also has a limit of 500 incidents being returned for any query.
Methods
Query incidents by incident properties and properties of the correlated events
Query incidents for a given period of time based on properties of the incident or properties of the events correlated to the incidents. By default, incidents created in the last 7 days will be retrieved and filtered. A start time and end time can be provided to define the time range, but the range is limited to a 30 day period. The query also has a limit of 500 incidents being returned for any query. Incidents can be requested by incident properties, like incident priority and incident state. You can also set 1 or more event filters that set conditions on events that must be correlated to an incident for it to be included in the query results. You can filter only on incident properties, only on properties of the correlated events, or a combination of the two. Restrictions on incident/event filter expressions:
-
Attribute names are case sensitive
-
Expressions must include an attribute name, operator, and value (no value is allowed for operators "is empty" "is not empty")
-
There must be at least one space between the attribute name and operator and the operator and value.
-
Operators and logical operators are case insensitive 'or' == 'OR' == 'Or'
-
Only "or's" or "and's" are allowed in an expression, not a mixture of both
-
No parentheses are allowed for grouping expressions
Use the URLs provided to see the specifications for the incident attributes and event attributes, including valid operators and and constraints on the value.
Example expressions for incident filter:
- lastChanged > "2017-08-01"
- priority == 5 OR priority == 4
- priority == 1 and state != 'closed' and assignedBy == 'POLICY'
Example expressions for event filter (up to 5 filters supported):
- severity >= "minor"
- summary starts with "Failure" and resource.application == "payroll"
- type.eventType == 'a1' or type.eventType == 'a2' or type.eventType == 'a3'
For best performance, filter the incidents as much as possible using the incident properties. This will reduce the number of incidents that must be further processed against their events if event filter properties are specified.
GET /incidentquery/v1
Request
Query Parameters
Beginning UTC timestamp (YYYY-MM-DDTHH:mm:SS.sssZ) for range of incidents to query - will default to system configured value of 7 days ago. This time is compared to the "created" time of an incident to determine if the incident should be included. Example values: 2017-09-12T08:00:00.000Z, 2017-09-12T08:00, 2017-09-12
Ending UTC timestamp (YYYY-MM-DDTHH:mm:SS.sssZ) for range of incidents to query - - will default to current time. This time is compared to the "created" time of an incident to determine if the incident should be included. Example values: 2017-09-14T17:00:00.000Z, 2017-09-14T17:00, 2017-09-14
A condition filter that specifies expression matches for incident properties
Set to "and" or "or" to indicate how the event filters should be combined when filtering by event content. The default is to combine the event filters using the "and" operator, meaning all event filters must be satisfied by any returned incident. Use "or" if only one of the event filters must be satisfied.
Allowable values: [
and,or]Default:
andA condition filter that specifies expression matches for the properties of a single event on the incident
A condition filter that specifies expression matches for the properties of a single event on the incident
A condition filter that specifies expression matches for the properties of a single event on the incident
A condition filter that specifies expression matches for the properties of a single event on the incident
A condition filter that specifies expression matches for the properties of a single event on the incident
Response
A single incident defined in the Cloud Event Management data store
UUID allocated when the incident was created
ID suitable for displaying, likely but not guaranteed to be unique.
Human readable digest of the events that make up the incident.
Priority of an event or incident, 1 is highest priority
Possible values: 1 ≤ value ≤ 5
Possible values: [
unassigned,assignedToTeam,assignedToIndividual,inProgress,onHold,resolved,closed]Time at which a change was made to the incident. Changes to the fields in the incident and additional event instances (but not occurrences) are included.
Sources of all events correlated to the incident.
Team with responsibility for the incident. A single hyphen (-) indicates no team. If the incident has no team it will appear in the default queue.
Individual with responsibility for the incident. A single hyphen (-) indicates no user. If the incident has no owner it will appear in the team queue.
Time at which the incident was created.
URL to fetch the properties for the incident.
URL to fetch the events for the incident.
URL to fetch the timeline for the incident.
Status Code
Array of incidents retrieved
Bad request
Internal server error
No Sample Response
Query the specifications for incident attributes allowed in incident filter conditions.
Query information that describes the attributes of an incident that can be used for creating filters for querying incidents. This will list valid attribute names, descriptions, valid operators, and any restrictions on the value.
GET /incidentquery/v1/incidentattributes
Response
The name of an incident or event attribute
List of the allowable operators for the attribute
The description of the attribute.
The type of value required, for example, string, integer, or boolean.
A list of valid values for this attribute.
Status Code
Array of attribute specs that constrain filter conditions for incident queries
Bad request
Internal server error
No Sample Response
Query the specifications for event attributes allowed in event filter conditions.
Query information that describes the attributes of events in an incident that can be used for creating filters for querying incidents. This will list valid attribute names, descriptions, valid operators, and any restrictions on the value.
GET /incidentquery/v1/eventattributes
Response
The name of an incident or event attribute
List of the allowable operators for the attribute
The description of the attribute.
The type of value required, for example, string, integer, or boolean.
A list of valid values for this attribute.
Status Code
Array of attribute specs that constrain filter conditions for incident queries
Bad request
Internal server error
No Sample Response
Query the properties of a specific incident.
Query the properties for a specific incident. The incident UUID must be specified in the requesting URL. This URL is returned in the response for each incident found when using the main incident query endpoint /incidentquery/v1.
GET /incidentquery/v1/{id}Request
Path Parameters
UUID of incident to retrieve
Possible values: Value must match regular expression
^[0-9a-f]{8}-[0-9a-f]{4}-1[0-9a-f]{3}-[0-9a-f]{4}-[0-9a-f]{12}$
Response
A single incident defined in the Cloud Event Management data store
UUID allocated when the incident was created
ID suitable for displaying, likely but not guaranteed to be unique.
Human readable digest of the events that make up the incident.
Priority of an event or incident, 1 is highest priority
Possible values: 1 ≤ value ≤ 5
Possible values: [
unassigned,assignedToTeam,assignedToIndividual,inProgress,onHold,resolved,closed]Time at which a change was made to the incident. Changes to the fields in the incident and additional event instances (but not occurrences) are included.
Sources of all events correlated to the incident.
Team with responsibility for the incident. A single hyphen (-) indicates no team. If the incident has no team it will appear in the default queue.
Individual with responsibility for the incident. A single hyphen (-) indicates no user. If the incident has no owner it will appear in the team queue.
Time at which the incident was created.
URL to fetch the properties for the incident.
URL to fetch the events for the incident.
URL to fetch the timeline for the incident.
Status Code
Single incident
Bad request
Requested object was not found
Internal server error
No Sample Response
Query the events for a specific incident.
Query the events for a specific incident. The incident UUID must be specified in the requesting URL. This URL is returned in the response for each incident found when using the main incident query endpoint /incidentquery/v1.
GET /incidentquery/v1/{id}/eventsRequest
Path Parameters
UUID of incident to retrieve
Possible values: Value must match regular expression
^[0-9a-f]{8}-[0-9a-f]{4}-1[0-9a-f]{3}-[0-9a-f]{4}-[0-9a-f]{12}$
Response
UUID allocated when the event instance was created
Used to find existing event instance for this event occurrence
Possible values: length ≤ 32767
The subject of the event
Brief description of the event
Severity of the event
Possible values: 10 ≤ value ≤ 100
Categorization of the event.
The system sending the event
Possible values: [
open,clear,closed]Runbooks associated with this event
RFC3339 format time of the earliest event occurrence for this instance
RFC3339 format time of the earliest event occurrence for this instance
True if a flapping policy applies and the event instance is currently identified as flapping.
UUID of the associated incident
Status Code
Array of incident events retrieved
Bad request
Internal server error
No Sample Response
Query the timeline for a specific incident.
Query the timeline entries for a specific incident. The incident UUID must be specified in the requesting URL. This URL is returned in the response for each incident found when using the main incident query endpoint /incidentquery/v1.
GET /incidentquery/v1/{id}/timelineRequest
Path Parameters
UUID of incident to retrieve
Possible values: Value must match regular expression
^[0-9a-f]{8}-[0-9a-f]{4}-1[0-9a-f]{3}-[0-9a-f]{4}-[0-9a-f]{12}$
Response
Description of a change to an incident
Time at which the change occurred
Possible values: [
created,instance,comment,ownerchange,statechange]UUID of the timeline entry. Unique identifier for the entry, no matter the type.
UUID of event instance that was added to the incident, only if type is instance.
Text of the comment, only if type is comment.
Who made the comment, only if type is comment.
Name of the new team, optional if type is ownerchange.
Name of the new owner, optional if type is ownerchange.
Tag of the new state, only if type is statechange.
Status Code
Array of incident timeline entries retrieved
Bad request
Internal server error