# 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](/resources/api-overview.md).

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.


---

# 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://developer.mediarithmics.io/alerting.md?ask=<question>
```

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.