POST /ping

Request

POST /ping
Authorization: Bearer <api_key>
Content-Type: application/json

Pola body

Pole	Typ	Wymagane	Opis
`event_type`	string	tak	`ping`, `stream_event` lub własny
`monitor`	string	tak	Nazwa monitora (litery, cyfry, `-` i `_`, 1-64 znaki)
`status`	string	tak*	Status zdarzenia, zobacz Typy zdarzeń i statusy
`duration`	float	nie	Czas wykonania w sekundach
`exit_code`	int	nie	Exit code procesu
`host`	string	nie	Hostname maszyny, na której leciał job
`project`	string	nie	Nazwa projektu (maks. 100 znaków); monitor trafia do niego w panelu, projekt powstaje w razie potrzeby
`message`	string	nie	Dowolna wiadomość lub wycinek logu
`timestamp`	int	nie	Unix timestamp (domyślnie now)

*Dla event_type: "ping" nazwa pola to status. Dozwolone wartości: run, complete, fail, skip.

Przykład: lifecycle zadania

// Job started
{
  "event_type": "ping",
  "monitor":    "db-backup",
  "status":     "run",
  "host":       "server-01"
}

// Job finished successfully
{
  "event_type": "ping",
  "monitor":    "db-backup",
  "status":     "complete",
  "duration":   47.3,
  "exit_code":  0
}

Przykład: skip (maintenance window)

{
  "event_type": "ping",
  "monitor":    "payment-service",
  "status":     "skip"
}

Dla szybkich jednolinijkowych komend shell bez body JSON, użyj GET /ping. Przyjmuje te same wartości status i wspiera autentykację ?api_key= w URL.

Response

200 OK

{ "status": "success" }

400 Bad Request

{ "error": "required field missing: status" }

401 Unauthorized

{ "error": "unauthorized" }

403 Forbidden

Zwracane, gdy ping utworzyłby nowy monitor, a konto jest już na limicie monitorów swojego planu. Zdarzenia dla monitorów, które już istnieją, są zawsze przyjmowane - osiągnięcie limitu ani zmiana planu na niższy nigdy nie zatrzymują monitoringu, który już działa.

{
  "status": "error",
  "code": "monitor_limit_reached",
  "message": "Monitor limit reached (30). Delete unused monitors or upgrade your plan."
}

429 Too Many Requests

Limit żądań. Wyczerpana kwota zdarzeń nigdy nie odpowiada kodem 4xx - patrz nagłówki kwoty niżej.

Nagłówki kwoty

Każdy ping niesie w odpowiedzi stan konta, żeby klient mógł ostrzec na długo przed tym, zanim cokolwiek przestanie działać:

Nagłówek	Znaczenie
`X-Quota-State`	`ok`, `warning` (od 80% limitu), `exceeded` albo `suspended`
`X-Quota-Limit`	Miesięczny limit zdarzeń w planie. Nieobecny w planach bez limitu
`X-Quota-Used`	Zdarzenia przyjęte w bieżącym okresie
`X-Quota-Reset`	Kiedy licznik zeruje się, RFC 3339 w UTC
`X-Quota-Reset-In`	Ile sekund do tego momentu

Wyczerpanie kwoty nie wywraca pingu. Odpowiedź to nadal 200, bo ping zwykle leci z linijki curl w crontabie: kod 4xx sprawiłby, że cron uzna poprawnie wykonane zadanie za błędne i wyśle o tym maila właścicielowi. Nasz problem rozliczeniowy nie może stać się czyjąś awarią na produkcji.

Przekroczenie limitu uruchamia karencję: zdarzenia są nadal przyjmowane, a nadwyżkę widać w panelu. Dopiero po jej upływie monitoring konta zostaje wstrzymany i od tej chwili pingi odpowiadają:

{
  "status": "ok",
  "quota": "suspended",
  "resets_at": "2026-10-01T00:00:00Z",
  "message": "Monitoring is suspended because the account is over its plan limit. The event was not stored."
}

Zdarzenie nie jest zapisywane, a alerty milczą dla całego konta - wstrzymany monitor nie może zgłaszać awarii, której nie ma. Monitoring wraca sam, gdy kwota się zeruje, gdy konto zejdzie pod limit monitorów albo od razu po przejściu na wyższy plan.