Коли користувачі в одній країні повідомляють про проблеми, а команда бачить, що сервіс працює у звичайному режимі, найкраще перевірити спостереження саме для їхнього регіону. API UptimeScout дає змогу запросити історію вибраного сервісу за кодом регіону й отримати інтервали разом із кількістю вимірювань. У результаті ви отримаєте таблицю, яку можна перевірити під час розгляду звернення: час інтервалу, роздільна здатність, розподіл сигналів і кількість вибірок.

Практичний сценарій тут — діагностика ймовірного регіонального збою. Вхідні дані: ідентифікатор сервісу з каталогу UptimeScout, код регіону, наприклад US або GB, і часовий інтервал історії. Результат допоможе зіставити час повідомлення користувача зі спостереженнями щодо сервісу. API описує ці дані як сигнали спостережуваної доступності; перевірка сервісу допомагає локалізувати проблему, але не замінює власні перевірки застосунку.
Спершу перевірте сервіс і регіон
Почніть із каталогу: знайдіть потрібний сервіс за назвою або пошуковим запитом і зафіксуйте його точний ID. Специфікація UptimeScout OpenAPI описує пошук через GET /v1/services і параметри q, service, region, limit та offset. Для діагностичного звіту краще зберігати ID, а не лише назву для відображення: так повторний запит звертатиметься до того самого елемента каталогу.
Для регіону використовують окремий дволітерний код. Важливо зберегти його разом із результатом: відповідь для US і відповідь без регіонального фільтра дають відповіді на різні запитання. Якщо опис потрібно показувати українською, параметр lang=uk керує локалізацією опису, а параметр region визначає спостереження. У документації чітко розмежовано ці два призначення.
Запросіть історію, а не лише один статус
Для розгляду інциденту скористайтеся /v1/history із обов’язковим параметром service і вибраним region. Параметр hours задає часовий інтервал історії; специфікація дозволяє значення від 1 до 2160 годин. У запиті також передбачено lang. Згідно з OpenAPI, авторизація передається ліцензійним ключем за схемою Bearer. Під час практичного запуску зберігайте ключ у змінній середовища й не записуйте його в журнал запитів.
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 і невідомих проміжків. Для перевірки доступності це і є практичний результат: не просто поточна позначка статусу, а запис, обмежений регіоном і часом, який колега може перевірити повторно.