Можно ли по ответу UptimeScout incidents сразу объявить, что у сервиса авария? Нет: этот эндпоинт перечисляет сервисы с недавними повышенными сигналами нарушений, а спецификация прямо отмечает, что это не подтверждённые инциденты провайдера. Практический результат — короткий список сигналов для проверки, а не готовое заключение о причине сбоя.

Это полезное различие для дежурного инженера и аналитика: автоматическое оповещение может сообщить «проверьте сервис X в регионе Y», сохраняя подтверждение факта и объяснение причины за официальным статусом провайдера или собственной диагностикой. Спецификация UptimeScout документирует отдельные маршруты для сигналов, текущего статуса и истории наблюдений.
Что именно возвращает список сигналов
/v1/incidents — GET-эндпоинт каталога сервисов с повышенными сигналами нарушений. В его параметрах есть фильтры по сервису, региону, категории, поисковому запросу и окну времени. Ответ требует лицензии; API описывает авторизацию Bearer-токеном. Поле региона принимает двухбуквенный код, а hours задаёт окно от 1 до 2160 часов.
Слово «incident» в пути легко прочитать как «подтверждённая авария», но документация задаёт более узкое значение: свежий сигнал наблюдений. Поэтому уведомление стоит формулировать по данным ответа — например, «получен сигнал о нарушении доступности» — и не приписывать поставщику услуги признание инцидента.
Минимальная проверка перед уведомлением
Сначала сохраните исходный ответ вместе со временем получения и параметрами запроса. Затем проверьте, какой сервис и регион вернулись, и оцените свежесть по полям сервиса observed_at и stale. Если наблюдение помечено как устаревшее, его следует отделить от текущего сигнала, а не показывать как состояние «прямо сейчас».
curl -sS 'https://api.uptimescout.com/v1/incidents?region=US&hours=24' \
-H "Authorization: Bearer $UPTIMESCOUT_LICENSE_KEY"
Это пример запроса по США за 24-часовое окно; ключ читается из переменной окружения и не выводится в командной строке. После ответа проверьте HTTP-ошибки и структуру JSON, затем обработайте каждый возвращённый сервис отдельно. Значения статуса в схеме включают operational, degraded, outage и unknown; при отсутствии поля или значения не подставляйте собственную интерпретацию.
Для сигнала, который требует действия, запросите текущий статус соответствующего сервиса через /v1/status и историю через /v1/history. В истории полезно сохранить рядом с рядами resolution_seconds, samples, counts и effective_start: так аналитик видит, с какой временной детализацией собраны данные и за какой фактический интервал они доступны. Спецификация предупреждает, что пропущенные интервалы неизвестны; пустой промежуток нельзя автоматически считать ни доступностью, ни сбоем.
Как превратить ответ в проверяемый отчёт
Для каждой записи заведите поля: идентификатор и имя сервиса, регион запроса, статус, время наблюдения, признак устаревания, время получения ответа и ссылка на источник официального статуса, если команда её проверила. Последнее поле заполняет ваша интеграция или оператор: спецификация UptimeScout не обещает, что сигнал содержит подтверждённую причину или заявление провайдера.

Разделите рабочий процесс на три состояния. «Сигнал получен» означает, что запись попала в результат /v1/incidents. «Статус сверяется» означает, что вы запросили текущее состояние и историю. «Подтверждено» оставляйте для вывода, который подкреплён внешним официальным сообщением или внутренней проверкой. Это простое разделение не даёт дашборду выдавать агрегированный сигнал за установленный факт.
Если команда строит отчёт по нескольким регионам, выполняйте отдельные запросы с нужными кодами регионов и сохраняйте параметр вместе с результатом. Поле lang относится к языку описаний сервисов; оно не меняет регион наблюдений. Такое разделение важно при сравнении, например, локализованного каталога и регионального состояния.
Где заканчивается вывод
Проверяемый результат этого сценария — журнал сигналов с явными отметками времени, региона и свежести, дополненный отдельной сверкой статуса и истории. Он помогает обнаружить, что именно требует внимания и что удалось подтвердить по выбранным источникам. Сам ответ /v1/incidents сообщает о повышенном сигнале наблюдений; для объявления подтверждённой аварии нужны подтверждающие данные.