> For the complete documentation index, see [llms.txt](https://docs.mediarithmics.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mediarithmics.io/setup-and-monitor/operate-and-monitor/set-up-alerts.md).
# Set up alerts
Read platform alerts, tune their thresholds, and pull them into your own reports.
## Your goal
Be told when something in the platform needs attention - a broken segment definition, a volume drop, a failed initial loading - rather than discovering it later.
## Expected outcome
Alerts tuned to your segments, and, if you want it, a job that pulls open alerts into your own monitoring.
## What alerts are
**Platform modules can trigger alerts** to grab the attention of users and integrators on specific points to improve or fix. Alerts are displayed in the interface, and can also be accessed by API - which is how you automate actions or bring them into your own reports.
## The alert types
| Type | Trigger |
| --------------------------- | ---------------------------------------------------------------------------- |
| `SEGMENT_DEFINITION_ERROR` | An error in the segment definition. |
| `SEGMENT_VOLUME_DROP` | A segment's volume drops by more than a configured threshold, in percentage. |
| `SEGMENT_COMPUTATION_ERROR` | An error during the calculation of a segment. |
| `INITIAL_LOADING_ERROR` | An error during the initial loading of a feed attached to a segment. |
The volume-drop check runs **after** the segment has been computed, and evaluates whether volumes dropped by more than the threshold, then whether the segment's labels pass the allowlist or blocklist configuration.
## Alert properties
| Property | What it holds |
| ------------------------------------------------ | ------------------------------------------------- |
| `type` | The alert type. |
| `id` | The unique identifier. |
| `datamart_id`, `organisation_id`, `community_id` | The scope the alert belongs to. |
| `created_ts` | When the alert was created. |
| `archived` | `true` when closed, `false` when open. |
| `archived_ts`, `archived_by` | When it was closed, and by whom. |
| `expiration` | The expiration timestamp. |
| `count` | The number of times the alert has been triggered. |
| `last_count_ts` | The most recent trigger. |
Segment alerts carry a `segment` object with the segment's ID, name, type, UserPoint count, and feed count. Initial-loading alerts additionally carry an `alert_sub_type` - `INITIAL_LOADING_EXECUTION_ON_ERROR`, `INITIAL_LOADING_RECORDS_ERROR`, `INITIAL_LOADING_NOT_STARTING`, or `INITIAL_LOADING_RUNNING_TOO_LONG` - and the `feed_id` concerned. Volume-drop alerts carry a `drop_rate`: the total drop in percentage since the alert was first triggered.
## Three behaviours worth knowing
{% tabs %}
{% tab title="Open and closed" %}
Alerts are described as **open** or **closed**, but in the system that state is the `archived` field: opening sets `archived` to `false`, closing sets it to `true`. A closed alert is no longer active or visible to users.
{% endtab %}
{% tab title="No duplicates" %}
When a new alert is triggered, the system checks whether an active alert already exists **for the same target**. If it does, it **increments `count`** and updates the last-count timestamp instead of creating a second alert.
So a segment with a persistent query error produces **one** alert with a rising count - not a new alert every run. `created_ts` is the first trigger, `last_count_ts` the most recent.
{% endtab %}
{% tab title="Expiration" %}
Alerts expire at **`created_ts` + 1 month**, and this cannot be modified. A cleaning job runs regularly and deletes expired alerts.
{% hint style="warning" %}
This is a one-month history. If you need alerts kept longer - for a quality report or an audit trail - pull them through the API and store them yourself.
{% endhint %}
{% endtab %}
{% endtabs %}
## Tune the thresholds
**Alert configurations** define the behaviour, thresholds, and rules of each alert type. They can be personalised **per organisation**; where a configuration is not set, a default value set by mediarithmics applies.
A configuration is identified by three values together: `config_key`, `organisation_id`, and `alert_type`.
| Configuration | Alert type | Value | Editable in the interface |
| -------------------------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| `volume_drops_threshold` | `SEGMENT_VOLUME_DROP` | An integer percentage such as `15`. **Defaults to `10`.** | No |
| `volume_drops_segment_labels_mode` | `SEGMENT_VOLUME_DROP` | `blacklist` or `whitelist`. Volume drops apply to **all** segments if not defined. | Yes |
| `volume_drops_segment_labels_ids` | `SEGMENT_VOLUME_DROP` | A list of segment labels, such as `1,2,3`, that will or will not receive alerts depending on the mode. Applies to all segments if not defined. | Yes |
| `initial_loading_not_starting_hours_threshold` | `SEGMENT_INITIAL_LOADING` | Hours after which an alert triggers if the initial loading has not started. **Defaults to `24`.** | No |
| `initial_loading_running_too_long_hours_threshold` | `SEGMENT_INITIAL_LOADING` | Hours after which an alert triggers if the initial loading is taking longer than expected. **Defaults to `24`.** | No |
| `initial_loading_records_error_threshold` | `SEGMENT_INITIAL_LOADING` | An integer percentage of errors above which an alert triggers. **Defaults to `10`.** | No |
{% hint style="success" %}
The label mode is the setting that makes volume-drop alerts usable. Without it, every segment is monitored at the same threshold, and a handful of naturally volatile segments will generate enough noise that people stop reading the alerts. Put those segments behind a label and blocklist it.
{% endhint %}
The two label configurations are edited from the alerts area on the segment list; the others are API-only.
## Manage alerts and configurations by API
{% tabs %}
{% tab title="Alerts" %}
```
GET https://api.mediarithmics.com/v1/alerts
```
A paginated API. Fill in **one of** `organisation_id`, `datamart_id`, or `community_id`. Filter with `type`, and pass `archived=true` to include closed alerts - **archived alerts are not returned by default**.
```
PUT https://api.mediarithmics.com/v1/alerts/:alertId?archive=true
DELETE https://api.mediarithmics.com/v1/alerts/:alertId
```
`PUT` with `archive=true` closes an alert, `false` reopens it.
{% hint style="info" %}
**No other operations are permitted.** The only field you may edit on an alert is the `archived` flag.
{% endhint %}
{% endtab %}
{% tab title="Configurations" %}
```
GET https://api.mediarithmics.com/v1/alert_type_configs?organisation_id=:organisationId
POST https://api.mediarithmics.com/v1/alert_type_configs/config_key=:configKey/organisation_id=:organisationId/alert_type=:alertType
PUT https://api.mediarithmics.com/v1/alert_type_configs/config_key=:configKey/organisation_id=:organisationId/alert_type=:alertType
DELETE https://api.mediarithmics.com/v1/alert_type_configs/config_key=:configKey/organisation_id=:organisationId/alert_type=:alertType
```
`POST` and `PUT` take `config_value` in the body; `PUT` also accepts `archived`.
{% hint style="info" %}
A configuration from the allowed list that is **not set up** is not returned by `GET` - it falls back to the platform default. An empty response therefore means "all defaults", not "nothing configured".
Use the interface where a configuration is editable there; it is easier.
{% endhint %}
**Archiving a configuration** stops the platform using it - falling back to the default - while keeping it easy to reactivate later. Use `PUT` with `archived: true`.
Only keys from the allowed list have an effect. Other keys are accepted and do nothing.
{% endtab %}
{% endtabs %}
## Set it up
{% stepper %}
{% step %}
### Read what you already get
Open the alerts in the interface. The four types above are active with default thresholds whether or not you have configured anything.
{% endstep %}
{% step %}
### Label your volatile segments
Then set `volume_drops_segment_labels_mode` and `volume_drops_segment_labels_ids` so those segments do not generate noise.
{% endstep %}
{% step %}
### Adjust the thresholds
`volume_drops_threshold` at the default `10` percent may be too sensitive or too lax for your segments.
{% endstep %}
{% step %}
### Pull them into your monitoring, if you have any
`GET /v1/alerts` filtered by organisation, on a schedule. Store them, because they expire after a month.
{% endstep %}
{% step %}
### Agree who closes them
Closing is the only edit the API allows, and an alert nobody closes keeps incrementing its count silently.
{% endstep %}
{% endstepper %}
## What alerts do not cover
Alerts are about segments and feeds. They do **not** tell you that ingestion stopped, that a collection is not indexed, or that consumption grew - for those, read the monitoring reports:
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.mediarithmics.io/setup-and-monitor/operate-and-monitor/set-up-alerts.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
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.