Когда пользователи в одной стране сообщают о проблемах, а команда видит обычную работу сервиса, полезнее всего проверить наблюдения именно для их региона. UptimeScout API позволяет запросить историю выбранного сервиса по региональному коду и получить интервалы вместе с числом измерений. На выходе получается проверяемая таблица для разбора обращения: время интервала, разрешение, распределение сигналов и количество samples.

Практический сценарий здесь — диагностика предполагаемого регионального сбоя. Входные данные: идентификатор сервиса из каталога UptimeScout, код региона вроде US или GB и окно истории. Результат помогает сопоставить время сообщения пользователя с наблюдениями сервиса. Сам API описывает данные как сигналы наблюдаемой доступности; сервисная проверка полезна для локализации вопроса, а не как замена собственным проверкам приложения.
Сначала подтвердите сервис и регион
Начните с каталога: найдите нужный сервис по имени или поисковой строке, затем зафиксируйте его точный ID. Спецификация UptimeScout OpenAPI описывает поиск через GET /v1/services и параметры q, service, region, limit и offset. Для диагностического отчёта лучше хранить ID, а не только отображаемое название: так повторный запрос адресует тот же элемент каталога.
Регион задаётся отдельным двухбуквенным кодом. Важно сохранить его рядом с результатом: ответ по US и ответ без регионального фильтра отвечают на разные вопросы. Если язык описания нужно показывать по-русски, параметр lang=ru управляет локализацией описания, а параметр region выбирает наблюдения. Документация прямо разделяет эти два назначения.
Запросите историю вместо одного статуса
Для разбора инцидента используйте /v1/history с обязательным параметром service и выбранным region. Параметр hours задаёт окно истории; спецификация допускает значения от 1 до 2160 часов. В запросе также предусмотрен lang. Авторизация передаётся лицензией по схеме Bearer согласно OpenAPI. В практическом запуске держите ключ в переменной окружения и не записывайте его в журнал запросов.
import os
import requests
response = requests.get(
"https://api.uptimescout.com/v1/history",
headers={"Authorization": f"Bearer {os.environ['UPTIMESCOUT_LICENSE_KEY']}"},
params={"service": "github", "region": "GB", "hours": 24, "lang": "ru"},
timeout=30,
)
response.raise_for_status()
data = response.json()
print(data)
Это минимальный пример запроса, а не опубликованный результат реального расследования. Идентификатор github и регион GB приведены как параметры примера: перед применением выберите нужный сервис и регион из своей задачи. Ответ полезно сохранить целиком в JSON, добавив время получения и описание запроса в отдельные поля вашей системы аудита. Так можно повторить разбор и увидеть, какой именно снимок данных использовался.
Разрешение и пропуски — часть результата
В массиве history важны поля observed_at, resolution_seconds, aggregated, samples и counts. Разрешение сообщает длительность временного интервала; samples показывает, сколько наблюдений вошло в агрегат, а counts содержит распределение сигналов. Сопоставляйте их вместе: одна строка с малым числом samples имеет иной вес для анализа, чем агрегат с большим количеством наблюдений.

UptimeScout описывает историю как временные слоты с разным шагом в зависимости от выбранного окна: минутные и пятиминутные интервалы для коротких периодов, часовые для суток и суточные для длинных периодов. Сохранённые старые агрегаты могут иметь более грубое разрешение. Поэтому не стройте вывод «сбой начался ровно в эту минуту», если строка представляет часовой или дневной агрегат. Используйте фактическое значение resolution_seconds и поля effective_start и history_resolution в ответе, чтобы обозначить границы доступного вывода.
Отсутствующий интервал трактуйте как неизвестный. Спецификация прямо просит проверять пропуски как неизвестные интервалы: пустое место в истории само по себе не кодирует ни нормальную работу, ни сбой. Для отчёта это простое правило предотвращает ложное заполнение пропусков «зелёным» статусом или нулями.
Сверьте историю с текущим сигналом
Если нужно проверить состояние в момент обращения, запросите /v1/status для того же service и region. В объекте сервиса смотрите status, observed_at и stale вместе; документация показывает эти поля как способ понять состояние и свежесть сигнала. Статус верхнего уровня относится к результату API-запроса, тогда как service.status описывает сигнал доступности конкретного сервиса. Это различие особенно полезно в автоматических отчётах: успешный HTTP-ответ и состояние внешнего сервиса — разные сущности.
Для нескольких зависимостей можно перейти к /v1/statuses, а затем использовать историю только для тех сервисов и регионов, где возникла аномалия. Спецификация также предоставляет /v1/summary и /v1/incidents. Для диагностики последнего маршрута учитывайте его точную роль: endpoint возвращает свежие повышенные сигналы нарушений, а не подтверждённые инциденты самого поставщика. Поэтому результат служит поводом для сверки, а не готовым заключением о причине.
Как оформить вывод без догадок
Сохраните в строке отчёта service ID, region, период запроса, observed_at, resolution_seconds, samples, counts и отметку о пропусках. Добавьте ссылку на обращение или внутренний инцидент отдельно от полей API. После этого сопоставьте временной диапазон с логами приложения, региональными трассировками и пользовательским сообщением. Если временные границы агрегата шире инцидента, формулируйте результат соответственно: наблюдения в выбранном регионе за заданное окно содержат такие-то сигналы, с таким-то разрешением и числом выборок.
Такой разбор даёт полезную развилку для дежурного: проверить региональную сторону внешнего сервиса или продолжить диагностику собственного приложения и сети пользователя. Его воспроизводимость зависит от сохранения параметров запроса и исходного JSON, а качество временного вывода — от явного учёта разрешения, samples и неизвестных промежутков. Для кейса с доступностью это и есть практический результат: не просто текущая метка статуса, а ограниченная по региону и времени запись, которую коллега может перепроверить.