> For the complete documentation index, see [llms.txt](https://docs.butlr.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.butlr.io/integrations-api-third-party-sensors/reporting-api/cleaning-alerts.md).

# Cleaning Alerts

Cleaning-alert history per room: one data point per alert status change, plus one each time a cleaning is recorded.

| Measurement             | Data keyed by |
| ----------------------- | ------------- |
| `cleaning_alert_events` | `room_id`     |

**Intervals:** none. This is an event measurement, so you can leave out `interval`, and any value sent is ignored. **Max range:** 730 days; see [Query Limits](/integrations-api-third-party-sensors/reporting-api/query-limits.md).

## Fields

| Field                | Description                                                                                                                                   |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `alert_id`           | ID of the alert. Every status change of one alert shares this ID. Empty for `cleaning_done`, which is not part of an alert.                   |
| `alert_type`         | `clean_now` or `end_of_day`. Empty for `cleaning_done`.                                                                                       |
| `status`             | For an alert: `triggered`, `cleaning_in_progress`, or `resolved`. `cleaning_done` records a completed cleaning on its own, outside any alert. |
| `resolved_reason`    | For `resolved` only: `cleaned`, `auto_cleared`, `manual_dismiss`, or `day_reset`                                                              |
| `resolved_by_name`   | For `manual_dismiss` only: display name of the person who dismissed the alert                                                                 |
| `source_sensor_type` | Which data drove the alert: `traffic` or `door_window`                                                                                        |
| `cumulative_value`   | Accumulated value when the status changed                                                                                                     |
| `threshold`          | Configured threshold that `cumulative_value` is compared with                                                                                 |

Each point has `stop` equal to `start`, and carries room-level [location metadata](/integrations-api-third-party-sensors/reporting-api/items-and-fields.md#location-metadata).

To follow one alert, group points by `alert_id` and order them by `start`.

`fill_gaps` is not supported; the request fails with code `-5015`.

## Example: alerts on a floor over two weeks

```bash
curl -X POST https://api-integrations.butlr.io/api/v1/reporting \
  -H "Authorization: Bearer [insert access_token here]" \
  -H "Content-Type: application/json" \
  -d '{
    "measurements": ["cleaning_alert_events"],
    "items": ["space_XXXX"],
    "start": "2026-09-01",
    "stop": "2026-09-15"
  }'
```

```json
{
  "data": {
    "room_XXXX": [
      {
        "start": "2026-09-03T14:02:11Z",
        "stop": "2026-09-03T14:02:11Z",
        "alert_id": "…",
        "alert_type": "clean_now",
        "status": "triggered",
        "source_sensor_type": "door_window",
        "cumulative_value": 40,
        "threshold": 40,
        …
      }
    ]
  }
}
```