Проверки по запросу
В дополнение к регулярным проверкам, вы можете запускать Проверки по запросу (On-Demand Checks) в любое время. Это позволяет оперативно проверить доступность или производительность ваших компонентов, когда это необходимо, например, после внесения изменений или для быстрой диагностики.
Запуски проверок по запросу также расходуют Кредиты мониторинга вашего тарифа. Подробнее о тарификации читайте в разделе Тарификация и лимиты.
Запуск Проверки по запросу
Вы можете запустить проверку по запросу двумя способами через API:
1. Запуск существующей регулярной Проверки
Этот метод позволяет выполнить уже настроенную регулярную проверку вне её расписания.
POST /v1/checks/{check_id}/execute
Инициирует запуск указанной регулярной проверки по её ID. Результат выполнения этой проверки будет доступен через объект Задания проверки (Check Job).
Ответ
В случае успешной постановки в очередь, API вернёт объект Задания проверки (Check Job) с информацией о статусе запроса.
{
"job_id": "mburq68bp440",
"message": "Custom check execution queued successfully",
"status": "queued"
}
2. Запуск произвольной Проверки (без создания регулярной)
Этот метод позволяет выполнить проверку с заданными параметрами, не создавая её как регулярную.
POST /v1/checks/execute
Инициирует запуск проверки с параметрами, которые вы передаете в теле запроса. Это удобно для разовых диагностических проверок.
Тело запроса
На вход принимаются те же параметры, что и для создания новой регулярной Проверки (POST /v1/checks).
| Поле | Тип объекта | Описание |
|---|---|---|
name | string | Название проверки. |
type | string | Тип проверки (web, tcp, ssl, api, synthetic). |
host или url | string | Хост или URL для проверки, в зависимости от type. |
timeout | number | Таймаут ожидания ответа в секундах. Максимальное значение: 30. |
parameters | object | Дополнительные параметры, специфичные для типа проверки. Подробнее см. в разделе "Параметры Проверки". |
port | number or null | Порт для проверки (например, для tcp, ssl типов). |
Например:
{
"name": "My On-Demand Web Check",
"type": "web",
"url": "https://pingera.ru",
"timeout": 10,
"parameters": {}
}
Ответ
В случае успешной постановки в очередь, API вернёт объект Задания проверки (Check Job) с информацией о статусе запроса.
{
"job_id": "mburq68bp440",
"message": "Custom check execution queued successfully",
"status": "queued"
}
Получение результатов Проверок по запросу (Задания проверки)
После запуска проверки по запросу (как существующей, так и произвольной), её результат не возвращается немедленно. Вместо этого вы получаете job_id, по которому можете отслеживать статус и получать окончательный результат выполнения.
Метод для получения всех заданий проверки или одного задания по его job_id:
GET /v1/checks/jobs/{job_id}
GET /v1/checks/jobs
Поля
| Поле | Тип объекта | Описание |
|---|---|---|
id | string | Уникальный идентификатор задания проверки (Job ID). |
check_id | string or null | ID регулярной проверки, если запуск был инициирован для неё. null для произвольных проверок. |
check_parameters | object | Параметры, с которыми была запущена проверка. |
job_type | string | Тип задания, например, custom_check для проверок по запросу. |
status | string | Текущий статус выполнения задания: queued, started, completed, failed. |
created_at | string (ISO 8601) | Дата и время создания задания. |
started_at | string (ISO 8601) or null | Дата и время начала выполнения проверки. |
completed_at | string (ISO 8601) or null | Дата и время завершения выполнения проверки. |
error_message | string or null | Сообщение об ошибке, если задание завершилось с ошибкой. |
result | object or null | Объект с результатом проверки. Присутствует, если status — completed. Формат зависит от того, выполнялась ли проверка в одном или нескольких регионах. |
Формат результата для проверок в одном регионе
Для проверок, выполненных в одном регионе, поле result содержит краткую информацию о результате:
{
"check_id": null,
"check_parameters": {
"host": "pingera.ru",
"name": "simple DNS check",
"parameters": {
"dns_servers": [],
"expected_answers": [],
"record_type": "A",
"regions": [
"RU, Moscow",
"EU, West"
],
"retry_enabled": false,
"validation_mode": "contains_all"
},
"type": "dns"
},
"completed_at": "2025-10-24T08:39:59.676820",
"created_at": "2025-10-24T08:39:58.850667",
"error_message": null,
"id": "8mu2viu35m55",
"job_type": "custom_check",
"result": {
"error_message": null,
"region": "EU, West",
"response_time": 0,
"result_id": "en06n6z5ugoq",
"status": "ok"
},
"started_at": "2025-10-24T08:39:58.873933",
"status": "completed"
}
Поля объекта result для одного региона
| Поле | Тип объекта | Описание |
|---|---|---|
result_id | string | Уникальный идентификатор результата проверки. |
status | string | Статус выполнения проверки: ok, failed, timeout. |
response_time | number | Время ответа в миллисекундах. |
region | string | Регион, в котором была выполнена проверка. |
error_message | string or null | Сообщение об ошибке, если проверка завершилась неудачно. |
Формат результата для параллельных проверок (несколько регионов)
Для проверок, выполненных параллельно в нескольких регионах, поле result содержит агрегированную информацию и краткую сводку по каждому региону:
{
"check_id": "obr6hhftpae5",
"check_parameters": {
"host": "ya.ru",
"name": "simple ICMP check",
"parameters": {
"ip_version": "auto",
"multi_region_execution": {
"enabled": true,
"execution_mode": "all"
},
"probe_count": 50,
"probe_interval": 0.1,
"probe_timeout": 1,
"regions": [
"RU, Moscow",
"EU, West"
],
"retry_enabled": true
},
"port": null,
"timeout": 30,
"type": "icmp",
"url": null
},
"completed_at": "2025-10-24T08:40:52.027915",
"created_at": "2025-10-24T08:40:44.261187",
"error_message": null,
"id": "b78neufpivlq",
"job_type": "existing_check",
"result": {
"avg_response_time": 46,
"completed_regions": 2,
"execution_group_id": "og52zsz0eebn",
"failed_regions": 0,
"max_response_time": 46,
"min_response_time": 46,
"regional_summary": [
{
"error_message": null,
"region": "RU, Moscow",
"response_time": 0,
"result_id": "61u4nys552xz",
"status": "ok"
},
{
"error_message": null,
"region": "EU, West",
"response_time": 46,
"result_id": "f4i0cr8ax7bk",
"status": "ok"
}
],
"status": "completed",
"total_regions": 2
},
"started_at": "2025-10-24T08:40:44.284912",
"status": "completed"
}
Поля объекта result для нескольких регионов
| Поле | Тип объекта | Описание |
|---|---|---|
execution_group_id | string | Уникальный идентификатор группы выполнения для параллельных проверок. |
status | string | Общий статус выполнения: completed, failed, partial. |
total_regions | number | Общее количество регионов, в которых выполнялась проверка. |
completed_regions | number | Количество регионов, где проверка успешно завершена. |
failed_regions | number | Количество регионов, где проверка завершилась неудачно. |
avg_response_time | number | Среднее время ответа по всем регионам в миллисекундах. |
min_response_time | number | Минимальное время ответа среди всех регионов в миллисекундах. |
max_response_time | number | Максимальное время ответа среди всех регионов в миллисекундах. |
regional_summary | array | Массив объектов с краткой информацией о результатах по каждому региону. |
Элементы массива regional_summary
| Поле | Тип объекта | Описание |
|---|---|---|
result_id | string | Уникальный идентификатор результата проверки в этом регионе. |
region | string | Название региона. |
status | string | Статус выполнения проверки в этом регионе: ok, failed, timeout. |
response_time | number | Время ответа в миллисекундах для этого региона. |
error_message | string or null | Сообщение об ошибке, если проверка в этом регионе завершилась неудачно. |
Получение детальных результатов проверки
Для получения полной информации о результатах проверки (включая все метаданные, как описано в разделе Результаты Проверок), используйте result_id из ответа задания:
GET /v1/checks/all-results?result_id={result_id}
Этот эндпоинт возвращает детальный результат в том же формате, что и обычные результаты регулярных проверок, включая все специфичные для типа проверки метаданные (check_metadata), информацию о сервере (check_server) и другие детали.