# incident.io
{% hint style="info" %}
Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.
{% endhint %}
[incident.io](https://incident.io/) is an incident management and alerting platform.
Integrating incident.io with Cortex allows you to:
* [Trigger an incident](#trigger-an-incident) directly from Cortex
* View incident data on entity pages in Cortex
* Create [Scorecards](#scorecards-and-cql) that track progress and drive alignment on projects involving incidents
## How to configure incident.io with Cortex
### Prerequisites
Before getting started:
* Create an [incident.io API key](https://app.incident.io/settings/api-keys) with the following scopes:
* **Create incidents**
* **View all incident data**, including private incidents
* **View data** like public incidents and organization settings
* **View catalog** types and entries
### Configure the integration in Cortex
1. In Cortex, navigate to the [incident.io settings page](https://app.getcortexapp.com/admin/integrations/incidentio):
* Click **Integrations** from the main nav. Search for and select **incident.io**.
2. Click **Add configuration**.
3. Configure the incident.io integration form:
* **Account alias**: Enter the alias for your configuration.
* **API key**: Enter your incident.io API key.
4. Click **Save**.
To modify the integration configuration, see [Modifying an existing integration configuration](/ingesting-data-into-cortex/integrations.md#modifying-an-existing-integration-configuration).
**Configure the integration for multiple incident.io accounts**[****](https://docs.cortex.io/docs/reference/integrations/incidentio#configure-the-integration-for-multiple-propsintegration-accounts)
The incident.io integration has multi-account support. You can add a configuration for each additional instance by repeating the process above.
Each configuration requires an alias, which Cortex uses to correlate the designated instance with registrations for various entities. Registrations can also use a default configuration without a listed alias. You can edit aliases and default configurations from the incident.io page in your Cortex settings. Select the edit icon next to a given configuration and toggle **Set as default** on. If you only have one configuration, it will automatically be set as the default.
## How to connect Cortex entities to incident.io
### Discovery
By default, Cortex will try to "best-guess" the corresponding custom field value in incident.io for all catalog-based custom fields.
Cortex first looks up a custom field values using the name (e.g. `My Entity`), then the entity identifier (e.g. `my-entity`). For example, if your entity name is "My Entity," then the corresponding custom tag field in incident.io should either be "My Entity" or "my-entity."
### Editing the entity descriptor
```yaml
x-cortex-incident-io:
customFields:
- name: Entity
value: My Entity
alias: my-default-alias
```
| Field | Description | Required |
| ------- | ------------------------------------------------------------------------------------------------ | :------: |
| `name` | Name for the entity (from `customFieldName`) | **✓** |
| `value` | Display name for the entity in Cortex | **✓** |
| `alias` | Alias for the configuration in Cortex (only needed if you have opted into multi-account support) | |
```yaml
x-cortex-incident-io:
customFields:
- id: Entity_ID
value: my-second-entity
alias: my-other-alias
```
| Field | Description | Required |
| ------- | ------------------------------------------------------------------------------------------------ | :------: |
| `id` | ID for the entity (from `customFieldID`) | **✓** |
| `value` | Tag for the entity in Cortex | **✓** |
| `alias` | Alias for the configuration in Cortex (only needed if you have opted into multi-account support) | |
## Using the incident.io integration
### View incident.io information on entity pages
Once the integration is set up, incident data will appear on [entity details pages](/ingesting-data-into-cortex/entities-overview/entities/details.md).
Active incidents detected in incident.io will appear on an entity's details page in the **Operations** block under the **Overview** tab. More detailed information is also available under the **Operations** tab.
Incident data will also be pulled into the incident.io page under the **On-call & incidents** page in the entity's sidebar.
### Trigger an incident
While viewing an entity in Cortex, you can trigger an incident in incident.io:
1. In Cortex, navigate to an entity. On the left side of an entity details page, click **On-call & incidents.**
2. In the upper right side of the entity's "On-call" page, click **Trigger incident**.
3. Configure the incident modal:
* **Summary**: Enter a title for the incident.
* **Description**: Enter a description of the incident.
* **Severity**: Select a severity level.
4. At the bottom of the modal, click **Trigger incident**.
* A confirmation screen will appear. In the confirmation, click the link to view the incident in incident.io.
### Scorecards and CQL
With the incident.io integration, you can create Scorecard rules and write CQL queries based on incident.io incidents.
See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.
Check if incident.io service is set
Check if entity has a registered incident.io custom field value in its entity descriptor.
If no registration exists, Cortex will try to automatically detect which corresponding incident.io custom field value is associated with the entity.
**Definition:** `incidentio (==/!=) null`
**Example**
For a Scorecard focused on operational maturity, you can use this expression to make sure each entity has an incident.io project set:
```
incidentio != null
```
Incidents
List incidents, filterable by severity and status.
* Created at
* Mode
* Name
* Severity
* Status
* Summary
* Type
* URL
**Definition:** `incidentio.incidents()`
**Examples**
To assess entities' health in a Scorecard, you can write a rule to make sure a given entity has fewer than three incidents with a severity of SEV1:
```
incidentio.incidents(severity = ["SEV1"]).length < 3
```
You can also use this expression to query for entities that have two or fewer critical incidents in the last three months:
```
incidentio.incidents(severity = ["Critical"]).filter((incident) => incident.createdAt.fromNow() > duration("-P90D")).length <= 2
```
### View integration logs
{% hint style="info" %}
This feature is available in Cortex cloud.
{% endhint %}
While viewing an integration's settings page, click the **Logs** tab to view error logs from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).
Click into a row to get more information, including time stamp, status code, full error, and request path.
## Still need help?[](https://docs.cortex.io/docs/reference/integrations/aws#still-need-help)
The following options are available to get assistance from the Cortex Customer Engineering team:
* **Email**: , or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.cortex.io/ingesting-data-into-cortex/integrations/incidentio.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.