---
title: "List open monitoring alerts"
method: GET
path: "/alerts"
tags: ["Alerts and checks"]
---

# List open monitoring alerts

`GET /alerts`

## Request

- Base URL: `https://trackberry.com/api/v1`
- URL: `https://trackberry.com/api/v1/alerts`
- Auth: HTTP bearer

Use this to find shipments that Trackberry's monitoring says have a problem right now: tracking gone quiet, ETA overdue or slipped, cargo sitting at the terminal, and similar. Only open alerts of the kinds customers can see are listed, across all shipments (archived ones included), newest first, keyset paged. Pass `shipment` to look at one shipment.

## Query parameters

- `shipment` string
- `limit` integer
- `starting_after` string

## Headers

- `Trackberry-Version` string

## Response `200`

A page of open alerts, newest first.

- object: The envelope every list endpoint returns.
  - `object` 'list', required: Always `list`.
  - `data` object[], required: The items of this page, in the order the endpoint documents. Each item is an object of the kind the endpoint returns.
    - `object` 'monitoring_alert', required: Always `monitoring_alert`.
    - `id` string, required: The alert id.
    - `shipment_id` string, required: The shipment the alert is about.
    - `shipment_reference` string, required: That shipment's Trackberry reference.
    - `key` 'tracking_halted' | 'tracking_blind' | 'tracking_stale' | 'tracking_silent' | 'tracking_not_found' | 'overdue_eta' | 'missing_eta' | 'eta_drift' | 'rollover' | 'port_dwell' | 'stalled_draft' | 'unresolved_checks', required: Which monitor raised it. `tracking_halted`: the tracking source said it stopped producing data. `tracking_blind`: the tracking source stopped reaching the carrier. `tracking_stale`: the carrier has published nothing new for longer than usual. `tracking_silent`: registered for tracking but the carrier never said anything. `tracking_not_found`: the tracking source does not recognize the reference. `overdue_eta`: the ETA passed and arrival is not confirmed. `missing_eta`: nothing says when it will arrive. `eta_drift`: the ETA moved 5 days or more later than first quoted. `rollover`: the container is not on the ship it was booked on. `port_dwell`: discharged more than 5 days ago and not yet gated out. `stalled_draft`: approved but never validated. `unresolved_checks`: failed checks left unresolved for more than 3 days. New keys may be added.
    - `group` 'tracking' | 'schedule' | 'workflow' | 'null', nullable, required: The theme of the alert. Null if the monitor that raised it no longer exists.
    - `severity` 'warning' | 'critical', required: How urgent it is. Severity can rise from `warning` to `critical` as the problem ages.
    - `title` string, required: A short English title for the kind of problem.
    - `summary` string, nullable, required: An English sentence saying what is wrong on this shipment.
    - `since` string, date-time, nullable, required: When the problem began, as the monitor measures it (for example the moment the ETA passed). Null when unknown.
    - `first_detected_at` string, date-time, nullable, required: When a monitoring sweep first saw the problem.
    - `last_detected_at` string, date-time, nullable, required: When the latest sweep still saw it.
    - `resolved_at` string, date-time, nullable, required: When the problem went away. Always null here, because only open alerts are returned.
  - `has_more` boolean, required: True when more items exist after this page. Pass the last item's `id` as `starting_after` to fetch them. Always false for unpaged lists.

## Other responses

- `400`: A parameter or header is invalid (`invalid_parameter`, with `param` naming it), a customer link cannot be made for this shipment (`not_shareable`), an uploaded file is empty, over 50 MB or of a type Trackberry does not read (`file_empty`, `file_too_large`, `unsupported_file_type`), an upload's container number is on more than one live shipment (`ambiguous_container`), an `Idempotency-Key` was already used for a different request (`idempotency_key_reused`) or `Trackberry-Version` names an unpublished version (`invalid_version`, with `param` set to `Trackberry-Version`). A parameter that must be a single value but was sent as an array or hash (`status[]=x`, `q[a]=1`) is also a 400.
- `401`: No token was sent (`missing_token`) or the token is wrong, expired, revoked, or its user left the organization (`invalid_token`). The response has a `WWW-Authenticate` header.
- `403`: The token may not do this. `insufficient_scope`: a write endpoint was called with a read-only token. `read_only_member`: a write endpoint was called by a token whose owner is now a read-only member of the organization. `revoke_not_allowed`: the link can only be revoked by an admin or by the member who made it. `billing_blocked`: an upload needed a new shipment and the organization's billing does not allow one.
- `429`: A rate limit was hit (`rate_limited`). Wait the number of seconds in `Retry-After`. A BI feed answers the same way (`feed_in_progress`) when another feed for the organization is still being produced.

---

[API](https://skmtc.dev/trackberry/apis/trackberry-api.md) · [All operations](https://skmtc.dev/trackberry/apis/trackberry-api/llms.txt) · [OpenAPI document](https://skmtc.dev/trackberry/apis/trackberry-api/revisions/be06ee7c17f3?raw)