Use the Environments API to define incident groups based on incident properties such as source, severity, or alert data.

Environments group related incidents together in a filtered incident list view, allowing your team to focus on the incidents relevant to their role.

Use Cases

Define custom Environments that help your users focus on the most relevant information to them. Common use cases include Environments that are based on areas of responsibility within IT and DevOps teams, processes, or escalation paths. For example, you can define an Environment for:

  • A DBA team that focuses on incidents related to production databases.
  • An engineering team that is responsible for incidents related to a particular set of applications.
  • Level-1 or NOC operators that work only on high-severity incidents.
  • The emergency contacts of a customer-facing service. Include only critical alerts from the service, and then set up an AutoShare to immediately notify the emergency contacts.


The basic environment builder in the BigPanda UI guides users through the creation of environments without the need for a BPQL filter. However, once an environment has been created or edited using the Environments API, the basic environment builder will no longer be available for that environment.

Environments are configured using BigPanda Query Language (BPQL) to define rules on which incidents will be grouped together. The rules construct a simple and/or boolean expression that is evaluated against the incident properties.

Relevant Permissions

See the Environment Permissions documentation for a full explanation of the permissions required to access the Environment Settings section and the Environments API.


API Key Authentication Protocol

A User API Key is required for authentication.


Reserved Words in BPQL

Certain words in BigPanda are reserved when using BPQL. When using these words to build environments, the system builds the environment according to the reserved meaning and is not able to treat them as a custom alert tag.

  • zero_impact = if false this means the environment has no incidents with the acknowledged or maintenance status
  • status = the current status of the incident. Possible statuses are: Critical, Warning, Unknown, Ok, or Acknowledged
  • severity = the max status reached by alerts in an incident. Possible statuses are: Critical, Warning, Unknown, Ok, or Acknowledged
  • source_system = the ID of the source system that produced the incident


Rate Limitations

To maintain quality of service, BigPanda APIs are limited to 5 requests per second.
Additional requests will return a 429 response code and the request will need to be retried.

Available Actions

Use the Environments API to perform these actions:

Create an EnvironmentPOST /environmentsCreates an environment.
Retrieve an Environment by IDGET /environments/{id}Retrieves a specific environment.
Retrieve All EnvironmentsGET /environmentsRetrieves all environments.
Update EnvironmentPATCH /environments/:idUpdates an environment.
Delete EnvironmentDELETE /environments/:idDeletes an environment.