# Alerting

Alerts are displayed in the UI, but can also be accessed by API if you want to automate actions or grab them in your own reports.

## Alert types

Here are the various alert types that exist:

<table><thead><tr><th width="301">Type</th><th>Trigger</th></tr></thead><tbody><tr><td><code>SEGMENT_DEFINITION_ERROR</code></td><td>Error in the segment definition.<br><a href="https://userguides.mediarithmics.io/audience/segments/segments-page#segments-that-have-definition-error">More information here</a></td></tr><tr><td><code>SEGMENT_VOLUME_DROP</code></td><td><p>Segment volume drops by more than a configured threshold (in percentage).<br></p><p><em>In the segment computation process, after it has been computed, we check</em> </p><ul><li><em>If volumes have dropped by more than XX%</em></li><li><em>If none of the segment labels are in the blocklist when in blocklist mode</em></li><li><em>If any of the segment labels are in the allowlist when in allowlist mode</em></li></ul><p><a href="https://userguides.mediarithmics.io/audience/segments/segments-page#segments-that-had-volume-drop">More information here</a></p></td></tr><tr><td><code>INITIAL_LOADING_ERROR</code></td><td>Error during initial loading of a feed attached to a segment<br><a href="https://userguides.mediarithmics.io/audience/segments/segments-page#segment-that-havent-been-correctly-activated-initial-loading-errors">More information here</a></td></tr><tr><td><code>SEGMENT_COMPUTATION_ERROR</code></td><td>Error during the calculation of a segment<br><a href="https://userguides.mediarithmics.io/audience/segments/segments-page#segment-that-couldnt-be-computed">More information here</a></td></tr></tbody></table>

## Alert properties

Alerts have several properties associated:&#x20;

* `type`: The type of the alert (e.g., SEGMENT\_COMPUTATION\_ERROR, SEGMENT\_VOLUME\_DROP...)
* `id`: The unique identifier of the alert
* `datamart_id`: The identifier of the datamart associated with the alert
* `organisation_id`: The identifier of the organisation associated with the alert
* `community_id`: The identifier of the community associated with the alert
* `created_ts`: The timestamp indicating when the alert was created
* `archived`: A flag indicating whether the alert is closed/archived (`true`) or open (`false`)
* `archived_ts`: The timestamp indicating when the alert was closed/archived
* `archived_by`: The identifier of the user that closed/archived the alert
* `expiration`: The expiration timestamp for the alert
* `count`: The number of times the alert has been triggered
* `last_count_ts`: The timestamp of the most recent trigger of the alert

### Polymorphism

The alerting system supports polymorphism to accommodate specific fields for various alert types.&#x20;

#### For Segment alert

<table><thead><tr><th width="177">Alert type</th><th width="178">Property name</th><th>Value</th></tr></thead><tbody><tr><td>-</td><td><code>segment</code></td><td><p>{ </p><p>'segment_id': 'xxx',</p><p>'segment_name': 'The segment name',</p><p>'segment_type': 'USER_QUERY',</p><p>'user_points_count': 71989,</p><p>'feeds_count': 0</p><p>}</p></td></tr><tr><td>SEGMENT_INITIAL_LOADING</td><td><code>alert_sub_type</code></td><td><p>sub-type of the error:</p><ul><li>INITIAL_LOADING_EXECUTION_ON_ERROR</li><li>INITIAL_LOADING_RECORDS_ERROR</li><li>INITIAL_LOADING_NOT_STARTING</li><li>INITIAL_LOADING_RUNNING_TOO_LONG</li></ul></td></tr><tr><td>SEGMENT_INITIAL_LOADING</td><td><code>feed_id</code></td><td>ID of the feed concerned by the error</td></tr><tr><td>SEGMENT_VOLUME_DROP</td><td><code>drop_rate</code></td><td>Total drop (in percentage) of the segment volume since the alert was first triggered</td></tr></tbody></table>

### Open/Close

To provide a familiar terminology to users, alerts can be opened or closed. However, in the system, the open/closed state is represented by the `archived` field. Opening an alert sets the `archived` field to `false`, while closing an alert sets it to `true`. The closed state implies that the alert is no longer active or visible to users.

### Preventing duplicates

To avoid having multiple instances of the same alert, the system employs a prevention mechanism. Each alert has `count` and `count_last_ts` properties. When triggering a new alert, we check if there is already an active alert for the same target. If such an alert exists, the system increments the `count` property and updates the `count_last_ts` to reflect the latest trigger. This prevents the proliferation of identical alerts and ensures that only one alert remains active with an incremented counter.

For example, if a segment has a query error and the issue persists without resolution, the system will increment the `count` property of the existing alert rather than creating multiple duplicate alerts.

The `count_last_ts` property stores the timestamp of the most recent trigger, while the `created_ts` property stores the timestamp of the initial trigger.

### Expiration

To manage the storage of alerts and ensure their relevance, the system implements an expiration mechanism. Alerts have an expiration duration associated with them. It is set to the `created_ts` + 1 month. You can't modify this behavior.

A cleaning job runs regularly to identify and delete all expired alerts from the database. This prevents the accumulation of unnecessary historical data.

## API

The API allows users and integrators to interact with alerts through the following functionalities:API

## Retrieve a list of alerts based on specific criteria

<mark style="color:blue;">`GET`</mark> `https://api.mediarithmics.com/v1/alerts`

[Paginated API](https://developer.mediarithmics.io/resources/api-overview).

You have to fill in either the `organisation_id`, `datamart_id` or `community_id` parameters.

Archived alerts are not returned by default. You need to ask them through the `archived` parameter.

#### Query Parameters

| Name             | Type      | Description                                                           |
| ---------------- | --------- | --------------------------------------------------------------------- |
| organisation\_id | Int       | ID of the organisation in which to find alerts                        |
| datamart\_id     | Int       | ID of the datamart in which to find alerts                            |
| community\_id    | Int       | ID of the community in which to find alerts                           |
| type             | AlertType | Such as `SEGMENT_COMPUTATION_ERROR`. See [Alert types](#alert-types). |
| archived         | Boolean   | `true` to return archived alerts.                                     |

{% tabs %}
{% tab title="401: Unauthorized You don't have access to the organisation, datamart or community" %}

{% endtab %}

{% tab title="200: OK List of alerts" %}

{% endtab %}
{% endtabs %}

## Change the status of an alert from open to closed or vice versa

<mark style="color:orange;">`PUT`</mark> `https://api.mediarithmics.com/v1/alerts/:alertId`

#### Path Parameters

| Name    | Type | Description             |
| ------- | ---- | ----------------------- |
| alertId | Int  | ID of the alert to edit |

#### Query Parameters

| Name    | Type    | Description                                   |
| ------- | ------- | --------------------------------------------- |
| archive | boolean | `true` to close an alert, `false` to open it. |

{% tabs %}
{% tab title="401: Unauthorized You can't open/close this alert" %}

{% endtab %}

{% tab title="200: OK OK. Returns the new alert object." %}

{% endtab %}

{% tab title="400: Bad Request Missing parameter: archive" %}

{% endtab %}
{% endtabs %}

<mark style="color:red;">`DELETE`</mark> `https://api.mediarithmics.com/v1/alerts/:alertId`

#### Path Parameters

| Name    | Type | Description               |
| ------- | ---- | ------------------------- |
| alertId | Int  | ID of the alert to delete |

{% tabs %}
{% tab title="401: Unauthorized " %}

{% endtab %}

{% tab title="200: OK " %}

{% endtab %}
{% endtabs %}

No other operations or modifications are permitted through the API.

Users and integrators are restricted from editing any field other than the `archived` flag for an alert.