# Incidents API

This documentation describes the API endpoints for retrieving and managing incident data.

## List Incidents

This endpoint retrieves a list of incidents, which are aggregations of multiple alerts related to an asset.

| Method | Path                                                       |
| ------ | ---------------------------------------------------------- |
| `GET`  | `https://{telmai_endpoint}/api/backend/{tenant}/incidents` |

**Query Parameters (Filters)**

The request supports the following query parameters for filtering the incident list:

| Parameter          | Type                               | Description                                                              | Example                    |
| ------------------ | ---------------------------------- | ------------------------------------------------------------------------ | -------------------------- |
| `project_ids`      | List of Integers (comma-separated) | Filters by a list of Project IDs.                                        | `0,24`                     |
| `connection_types` | List of Strings (comma-separated)  | Filters by asset connection types (e.g., GCS, BIGQUERY).                 | `GCS,BIGQUERY`             |
| `alert_policy_ids` | List of Strings (comma-separated)  | Filters by Alert Policy IDs. (IDs can be strings for prebuilt policies). | `4,5`                      |
| `severities`       | List of Strings (comma-separated)  | Filters by severity (LOW, MEDIUM, HIGH).                                 | `HIGH,MEDIUM`              |
| `impacts`          | List of Strings (comma-separated)  | Filters by impact (LOW, MEDIUM, HIGH).                                   | `HIGH`                     |
| `connection_ids`   | List of Strings (comma-separated)  | Filters by Connection IDs.                                               | `conn-123,conn-456`        |
| `from_time`        | String (ISO 8601 Timestamp)        | Range start timestamp for filtering.                                     | `2025-07-15T12:14:54.123Z` |
| `to_time`          | String (ISO 8601 Timestamp)        | Range end timestamp for filtering.                                       | `2025-07-15T12:14:54.123Z` |
| `text_to_search`   | String                             | A search string applied to policy names and source names.                | `test_policy`              |

Example Request:

```
GET: https://{host:port}/api/backend/{tenant}/incidents?project_ids=0,24
```

**Response Body (JSON Array)**

Returns an array of incident objects.

JSON

```
[
  {
    "id": 1311,
    "project_id": 0,
    "asset_id": "5x0e34yk1re4",
    "last_upload_timestamp": "2025-06-30T14:12:51.871Z",
    "created_time": "2025-06-30T14:12:51.871Z",
    "severity": "HIGH",
    "impact": "HIGH",
    "status": "OPEN",           // Can be one of OPEN / CLOSED
    "ticket_id": 2411,
    "alert_policy_id": "4",
    "alert_policy_name": "test_policy",
    "description": "...",
    "tags": ["T1", "PROD"]
  },
  ...
]
```

***

### Get Incident Details

Retrieves the detailed information for a specific incident.

| Method | Path                                                                    |
| ------ | ----------------------------------------------------------------------- |
| `GET`  | `https://{telmai_endpoint}/api/backend/{tenant}/incidents/{incidentId}` |

**Path Parameter**

| Parameter    | Type    | Description                    |
| ------------ | ------- | ------------------------------ |
| `incidentId` | Integer | The unique ID of the incident. |

Example Request:

```
GET: https://{telmai_endpoint}/api/backend/{tenant}/incidents/1311
```

**Response Body (JSON Object)**

In addition to the fields in the list response, this endpoint returns detailed metrics and a history of state changes.

JSON

```
{
  "id": 1311,
  "project_id": 0,
  "asset_id": "5x0e34yk1re4",
  "last_upload_timestamp": "2025-06-30T14:12:51.871Z",
  "severity": "HIGH",
  "impact": "HIGH",
  "status": "OPEN",           // Can be one of OPEN / CLOSED
  "ticket_id": 2411,
  "alert_policy_id": "4",
  "alert_policy_name": "test_policy",
  "description": "...",
  "metrics": [
    {
      "metric_name": "contains_pii",
      "metric_aggregation": "ratio",
      "display_metric_name": "PII %",
      "segment": null,
      "rule": null, // If populated, it indicates a virtual attribute for a correctness policy
      "attribute": null
    },
    ...
  ],
  "tags": ["T1", "PROD"],
  "history": [
    {
      "timestamp": "2025-06-30T14:12:51.871Z",
      "state": "NEW",         // Can be one of NEW / ONGOING / RESOLVED / REOPENED
      "alert_refs": [
        {"metric_time":"2025-06-30T14:12:51.871Z", "violation_name":"FEATURE.s132j7ja1"},
        ...
      ]
    }
  ]
}
```

***

### Incidents Distribution

This endpoint retrieves a day-by-day distribution of incident counts, categorized by severity and impact.

| Method | Path                                                                    |
| ------ | ----------------------------------------------------------------------- |
| `GET`  | `https://{telmai_endpoint}/api/backend/{tenant}/incidents/distribution` |

Filters: This endpoint supports the same filter set as the Incidents List endpoint.

**Response Body (JSON Object)**

JSON

```
{
  "incidents": [
    {
      "date": "2025-07-22",
      "counts": {
        "LOW": 1,
        "MEDIUM": 4,
        "HIGH": 6,
        "": 8 // Incidents without a specified severity/impact
      },
      "counts_by_impact": {
        "LOW": 1,
        "MEDIUM": 4,
        "HIGH": 6
      }
    },
    ...
  ]
}
```

***

### Incidents Summary

Retrieves overall summary statistics for incidents.

| Method | Path                                                         |
| ------ | ------------------------------------------------------------ |
| `GET`  | `https://{host:port}/api/backend/{tenant}/incidents/summary` |

**Response Body (JSON Object)**

| Field                           | Type    | Description                                           |
| ------------------------------- | ------- | ----------------------------------------------------- |
| `total`                         | Integer | Total number of incidents.                            |
| `open`                          | Integer | Total number of OPEN incidents.                       |
| `closed`                        | Integer | Total number of CLOSED incidents.                     |
| `mean_time_to_resolve`          | Integer | Average time to resolve incidents (in hours).         |
| `previous_mean_time_to_resolve` | Integer | Previous period's average time to resolve (in hours). |
| `open_by_tag`                   | Object  | Count of OPEN incidents grouped by tag.               |
| `closed_by_tag`                 | Object  | Count of CLOSED incidents grouped by tag.             |

JSON

```
{
  "total": 25,
  "open": 6,
  "closed": 19,
  "mean_time_to_resolve": 122,
  "previous_mean_time_to_resolve": 117,
  "open_by_tag": {
    "T1": 3,
    "prod": 12
  },
  "closed_by_tag": {
    "T1": 12,
    "prod": 67
  }
}
```

***

### Retrieving Alerts for an Incident

An Incident is an aggregation over time and refers to multiple uploads and alert objects, whereas an Alert refers to a specific upload and violation. To retrieve the individual alerts that compose an incident, you must use the `alert_refs` from the incident's history.

#### POST Retrieve Alerts by Filters

| Method | Path                                                                       |
| ------ | -------------------------------------------------------------------------- |
| `POST` | `https://{host:port}/api/backend/{tenant}/configuration/alerts/by_filters` |

**Request Body (JSON Object)**

The request body is constructed using data extracted from the incident's `asset_id` and the `alert_refs` array (found within the `history` of the detailed incident response).

Example:

If an incident has an `asset_id` of `"5x0e34yk1re4"` and the following `alert_refs`:

JSON

```
"alert_refs": [
  {"metric_time":"2025-06-30T14:12:51.871Z", "violation_name":"FEATURE.s132j7ja1"},
  {"metric_time":"2025-06-30T14:13:55.325Z", "violation_name":"DATA.a531"}
]
```

The request body should be:

JSON

```
{
  "sources": ["5x0e34yk1re4"], // The asset_id from the incident
  "upload_dates": ["2025-06-30T14:12:51.871Z", "2025-06-30T14:13:55.325Z"], // metric_time from alert_refs
  "violation_names": ["FEATURE.s132j7ja1", "DATA.a531"] // violation_name from alert_refs
}
```

**Alert Object Structure**

The endpoint returns an array of detailed Alert objects.

JSON

```
{
  "type": "SCHEMA_CHANGE",
  "source": "SNOWFLAKE.SALES_DB.PUBLIC.CUSTOMER_ORDERS",
  "attribute": "SHIPPING_ADDRESS",
  "job_id": "job-f8e2-4a1b-9c3d-5e6f7a8b9c0d",
  "create_time": "2023-10-27T10:30:00.123Z",
  "save_time": "2023-10-27T10:30:05.456Z",
  "violation_data": {},
  "violation_name": "Customer Orders Schema Drift",
  "notification_channels": ["critical-alerts-slack", "data-team-email"],
  "is_notification_enabled": true,
  "metric_time": "2023-10-27T10:25:00.000Z",
  "is_notified": false,
  "metric_value": 1.0,
  "policy_name": "Monitor Production Schemas",
  "segment": "USA",
  "priority": "HIGH",
  "description": {
    "HIGH": [
      "The data type for column 'SHIPPING_ADDRESS' was changed from VARCHAR(255) to VARCHAR(512)."
    ]
  },
  "source_name": "CUSTOMER_ORDERS",
  "source_type": "SNOWFLAKE",
  "project_name": "E-commerce Analytics",
  "tags": ["production", "schema", "customer-data"]
}
```