Incidents V2

The Incidents API allows you to manage BigPanda incidents externally, and can be configured with external ticketing and monitoring tools. It provides the Incidents object, which represents a BigPanda incident containing correlated alerts from your integrated monitoring systems.

The Incident Search function uses BigPanda Query Language (BPQL) to filter the incidents in your BigPanda instance and return those that meet specific conditions. Set sort order, pagination rules, and query incidents by tag, time frame, source system, or more. The Incident Search function can be used to return all incidents in a specific environment.

Expanding alert data

To include the full alert object for each retrieved incident, include expand=alerts in the query.

When making a call with alerts expanded, page_size cannot be larger than 10. An expanded call with a page size greater than 10 will return a 400 error.

Incident Actions allows you to seamlessly manage incidents through the API. Incidents can be merged, split, assigned, snoozed, and commented on through the API.

A list of the actions that have been taken on an incident can be retrieved using the Get Activities function.

Environment ID

The environment ID can extracted from the URL of the BigPanda console in browser, or it can be retrieved through the Environments API

Different objects

The Incidents V2 API and Notifications Webhook return different fields and formatting. This object page lists the fields for calls made to the Incidents V2 API.

To configure a sharing integration or notifications webhook, see the Webhook Incident Object.

Incidents v2

Authentication

All BigPanda APIs require Bearer Token Authorization in the call headers.

This API uses the User API Key type of Authorization token.

BigPanda recommends adding Authentication headers only in the secure tool you use to make API calls.

Incident V2 Parameters

The Incident object schema includes the following attributes:

Parameter	Description	Type
id	System-generated unique identifier for the incident.	String
status	Current incident status, which is determined by the most severe status of the correlated alerts. Possible statuses: [critical, warning, unknown, ok].	String
active	Whether the incident contains at least one active alert and has not been manually resolved. An incident is automatically resolved when all the alerts are resolved.	Boolean
severity	The highest status the incident reached	String
flapping	Whether at least one correlated alert has changed states frequently enough to be treated as flapping	Boolean
shared	Whether the incident has been shared	Boolean
snooze	Snooze options for the incident Attributes: snoozed - Whether the incident is currently snoozed. end_time - Time when the current snooze period expires. Unix epoch time when X (in seconds). cancel_on_incident_updates - Whether the current snooze should be automatically cancelled if a new alert is added, the severity of an existing alert increases, or the incident is resolved and then reopens.	Object
maintenance	Whether an incident is in maintenance null - not in maintenance partial - one of the alerts is in maintenance active - all alerts in maintenance	String
correlation_matchers_log	Log of the correlation patterns matched to the incident over time. As more alerts are added to the incident, the matched correlation patterns may change. When this happens, another array is added that contains the matching correlation patterns at that time. Correlation Pattern Attributes: correlation pattern id - system generated unique identifier for the correlation pattern. time window - The time frame in which this pattern will correlate incoming alerts. alert tags - Alert tags that match the correlation pattern rules. The last item in the array is the most recent one. If multiple correlation patterns match the incident, the pattern with the longest time window is the one that appears in the UI. See the Algorithmic Correlation documentation for more information. When an incident is split, only the source incident maintains the correlation_matchers_log.	Array of Objects
start	Unix epoch time when the earliest correlated alert was received (in seconds).	Timestamp (in seconds)
changed_at	Unix epoch time when the last incident change triggered applicable sharing updates (in seconds).	Timestamp (in seconds)
updated_at	Unix epoch time when the last change to the incident occurred (in seconds).	Timestamp (in seconds)
end	Unix epoch time when the incident was resolved, either manually or automatically when all alerts were resolved (in seconds).	Timestamp (in seconds)
alerts	Array of the alerts that the incident contains. Attributes: alert_id - System-generated unique identifier for the alert. When the request comes with expand=alerts, it sends an array of alert object data.	Array
assignee	The user assigned responsibility to see an incident through resolution name - in system name of user user_id - unique identifier of user email - email associated with user	Object
assigner	The user who assigned responsibility for an incident name - in system name of user user_id - unique identifier of user email - email associated with user	Object
environments	Environment IDs for all environments the incident appears in	Array
folders	Folder name of all folders the incident appears in	Array
incident_tags	Incident tags associated with the incident id - unique identifier for the tag name - in system tag name type - whether the tag is a Text, Priority or MultiValue tag value - value of the incident tag according to its type	Array

Sample Object

{
  "id": "60a4ee83bb7d9d046b8d7a93",
  "status": "Ok",
  "active": false,
  "severity": "Critical",
  "flapping": false,
  "shared": false,
  "maintenance": null,
  "start": 1621421699,
  "changed_at": 1629410549,
  "updated_at": 1629410549,
  "end": 1629410549,
  "alerts": [
    {
      "alert_id": "60a4ee83bb7d9d046b8d7a93"
    }
  ],
  "environments": [],
  "folders": [],
  "incident_tags": [],
  "correlation_matchers_log": [
    [
      {
        "time_window": 7200,
        "tags": [
          {
            "name": "case",
            "value": "sensitive1"
          }
        ],
        "correlation_id": "a02fde2f-0ec3-4cc2-9cbd-74895cb13050",
        "source_system": "api.backend_monitoring"
      }
    ]
  ]
}

Parameters

The Alert object schema includes the following attributes:

Parameter	Description	Type
id	System-generated unique identifier for the alert	String
status	The most severe status the alert triggered.<br><br> Possible returns are: `critical`, `warning`, `unknown`, `ok`.	String
start	Unix epoch time when the alert was received (in seconds).	Timestamp (in seconds)
end	Unix epoch time when the alert was resolved (in seconds).	Timestamp (in seconds)
changed_at	Unix epoch time when the alert status last changed (in seconds).	Timestamp (in seconds)
updated_at	Unix epoch time when the last change to the alert occurred (in seconds).	Timestamp (in seconds)
last_event_at	Unix epoch time when the last alert event occurred (in seconds).	Timestamp (in seconds)
active	Whether the alert is active and has not been manually resolved.	Boolean
primary_property	Main object that triggered the alert.	String
secondary_property	Secondary object or sub-item that triggered the alert.	String
source_system	Integrated monitoring system that sent the alert to BigPanda.	String
incident_key	A unique id BigPanda uses to recognize if two events are related to each other.	String
maintenance_plans	If alert is in maintenance, returns the plan ids.	Array
description	Brief summary (max. 2048 characters) of the alert included by certain monitoring tools.	String
tags	Array of name-value pairs that represent alert properties.<br><br> Attributes:<br><br> name - Tag name in BigPanda.<br><br> value - Tag value in BigPanda.<br><br> Note: By default, tag values are limited to a maximum of 30 items. Each value supports up to 512 characters before truncation. If you want to increase the value limit, reach out to your BigPanda account team.	String

Sample Object

{
  "alert_id": "60a4ee83bb7d9d046b8d7a93",
  "status" : "critical",
  "start": 1466416853,
  "end": null,
  "changed_at": 1466417169,
  "updated_at": 1466417169,
  "last_event_at": 1466417169,
  "active": true,
  “primary_property”: “host”,
  “secondary_property”: “check”,
  "source_system": "api.backend_monitoring",
  "incident_key" : “prod-mwv2-demo-1__Host is down”,
  “maintenance_plans”: “60450a8012d7dd0464f1b87dl”,
  "description": "CRITICAL - Host Unreachable",
  "tags":[ {"name":"host","value":"production-database-1"}, {"name":"check","value":"CPU load"} ]
}

General Activities Parameters

The Activity object includes the following attributes. Many activity types include additional parameters included in the schema.

Parameter	Description	Type
id	System-generated unique identifier for the activity	String
type	The type of activity	String
timestamp	Unix epoch time when the activity occurred in the system (in seconds)	Timestamp (in seconds)
created_by	User ID of the user who manually took action	String
params	Additional parameters according to the type	Object

Type-Specific Parameters

Each activity type has type-specific parameters included in the schema. These parameters will only be included for the relevant activity types.

Activity Type	Description	Additional Parameters
incident_assigned	A specific user was assigned responsibility to see the incident through resolution	assignee object: id - the unique ID of the user the incident was assigned to username - the username of the user the incident was assigned to
incident_become_flapping	The incident entered or exited the flapping state in which at least one correlated alert is changing states too frequently	flapping (true/false)- whether or not the incident is in the flapping state
incident_commented	A comment was added to the incident	comment - the comment string added to the incident
incident_resolved_ui_manually	The incident was resolved by a user through the BigPanda UI	annotation - an optional comment added to the resolver action
incident_resolved_api	The incident was resolved by an API call or with Time-Based Alert Resolution	annotation - an optional comment added to the resolver action
incident_alerts_resolved	One or more of the alerts within the incident were manually resolved	annotation - an optional comment added to the resolver action resolution_type - the method through which the alerts were resolved. One of: manual-ui, manual-api ids_to_resolve - the unique id of the alerts that were resolved
incident_tag_removed	An incident tag was removed from the incident	tag_id - system-generated unique identifier for the incident tag
incident_tag_updated	An incident tag was added to the incident	tag_id - system-generated unique identifier for the incident tag tag_value - the content of the incident tag
incident_merged_destination	The incident was the destination of a merge action	source_incident_ids - A list of incidents that were merged into this destination incident
incident_merged_source	The incident was merged into a different incident	targetIncidentId - The destination incident this incident was merged into source_incident_ids - A list of incidents to merge into the destination incident defined in the URL path
incident_created	The incident was created in the system	None
incident_rcc_update	The relationship between the incident and a potential root cause change match was updated	change object: identifier - the change's unique identifier from its original change system ticket_url - the URL of the record in the change system change_id - the unique identifier of the change in BigPanda rcc_medata object: change_id - the unique identifier of the change updated_at - unix time of the last update to the change in BigPanda match_certainty (MATCH, SUSPECT, or NONE) - the relationship status between the change and incident match_type (manual-UI or Manual-API) - whether the relationship status between the change and incident was set by a user or the RCC algorithm comment - an optional comment added to a manual match action suggested_by_bigpanda (true/false) - whether the relationship status between the change and incident was suggested by BigPanda's RCC algorithm
incident_shared	The incident was shared to an external channel	share_target - the channel or address the incident was sent to share_auto (true/false) - whether the share was triggered by an AutoShare rule escalation_id - an internal system id for the rule-match that triggers the share annotation - an optional comment added to the share action firstTime - whether or not this was the first time this incident was shared to the destination
incident_snoozed	The incident was snoozed	annotation - an optional comment added to the snooze action
incident_splitted_destination	The incident was created from a subset of alerts as part of a split action	alert_ids - a list of the ID of each alert that was moved into this new incident source_incident_id - the ID of the incident the alerts originally belonged to
incident_splitted_source	One or more alerts within the incident were split into a new incident	alert_ids - a list of the ID of each alert that was moved into the new incident new_incident_id - the ID of the new incident created with the selected alerts
incident_unassigned	The user assigned responsibility to see the incident through resolution was removed	unassigned_on_reopen (true/false) - whether the incident was unassigned through the incident reopen process
incident_unsnoozed	The incident had the snooze status removed	None
incident_reopened	The incident reopened within BigPanda	None
incident_resolved_by_alerts	The incident was resolved automatically by BigPanda when all associated alerts received an 'ok' status	None

Sample Object

{
    "items": [
        {
            "id": "161b4dc6c33740283e5416b0e6d6c70b",
            "timestamp": 1643700751,
            "type": "incident_shared",
            "created_by": "61950bc8c481fd1100abc3a3",
            "params": {
                "share_target": "webhook.whtest",
                "share_auto": false,
                "escalation_id": "61f8e20e89325b001201b9a3",
                "firstTime": true
            }
        },
        {
            "id": "5411150b64b2ad17da754b206e32f938",
            "timestamp": 1643700483,
            "type": "incident_shared",
            "created_by": "61950bc8c481fd1100abc3a3",
            "params": {
                "share_target": "webhook.amitwebook",
                "share_auto": false,
                "escalation_id": "61f8e102013bc30012204bff",
                "annotation": "this is another test",
                "firstTime": true
            }
        },
        {
            "id": "724df23d5ccc24d590ac4cddc306c892",
            "timestamp": 1641467377,
            "type": "incident_unsnoozed",
            "created_by": "57459f747dc1d7700e883ab2"
            }
        },
        {
            "id": "f9a27884d9193b3bba369b96b29434bd",
            "timestamp": 1641365710,
            "type": "incident_unassigned"
            }
        },
        {
            "id": "53bb1dbef847bcffbb838ba21c0972f9",
            "timestamp": 1641365708,
            "type": "incident_assigned",
            "created_by": "57459f747dc1d7700e883ab2",
            "params": {
                "assignee": {
                    "id": "5ea5be5bd97cad2836891e88",
                    "username": "[email protected]"
            }
        },
        {
            "id": "8df43e05a120198bdee009226f8bd86a",
            "timestamp": 1641365697,
            "type": "incident_snoozed",
            "created_by": "57459f747dc1d7700e883ab2",
            "params": {
                "time": 1633342764
            }
        },
        {
            "id": "f01fa98d40fd0beb4ef014a00d7aaf41",
            "timestamp": 1641365691,
            "type": "incident_shared",
            "created_by": "5519581afe04d9ba16bf9d07",
            "params": {
                "share_target": "slack.amitslack",
                "share_auto": true,
                "escalation_id": "61d540baf80bb900193e940c",
                "annotation": "This is a test",
                "firstTime": true
            }
        },
        {
            "id": "280f3b9ec3c5399e7ed053f0886f51ed",
            "timestamp": 1641365682,
            "type": "incident_created"
        }
    ],
    "page": 1,
    "total": 8
}

In this section:

Incidents V2

Incidents v2

Incident V2 Parameters

Sample Object

Parameters

Sample Object

General Activities Parameters

Type-Specific Parameters

Sample Object

Search results