POST /ping

Request

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

Body fields

Field	Type	Required	Description
`event_type`	string	yes	`ping`, `stream_event`, or custom
`monitor`	string	yes	Monitor name (letters, digits, `-` and `_`, 1-64 chars)
`status`	string	yes*	Event status, see Event Types & States
`duration`	float	no	Execution time in seconds
`exit_code`	int	no	Process exit code
`host`	string	no	Hostname that ran the job
`project`	string	no	Project name (max 100 chars); the monitor is grouped under it in the panel, the project is created if needed
`message`	string	no	Free-form message / log excerpt
`timestamp`	int	no	Unix timestamp (defaults to now)

*For event_type: "ping" the field name is status. Allowed values: run, complete, fail, skip.

Example: job lifecycle

// 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
}

Example: skip (maintenance window)

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

For quick shell one-liners without a JSON body, use GET /ping. It accepts the same status values and supports ?api_key= URL authentication.

Response

200 OK

{ "status": "success" }

400 Bad Request

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

401 Unauthorized

{ "error": "unauthorized" }

403 Forbidden

Returned when the ping would create a new monitor and the account is already at its plan’s monitor limit. Events for monitors that already exist are always accepted, so hitting the limit - or downgrading a plan - never stops the monitoring you already have.

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

429 Too Many Requests

Rate limit. The monthly event quota never answers 4xx - see the quota headers below.

Quota headers

Every ping answers with the account’s standing, so a client can warn long before anything stops working:

Header	Meaning
`X-Quota-State`	`ok`, `warning` (from 80% of the limit), `exceeded`, or `suspended`
`X-Quota-Limit`	Monthly event allowance of the plan. Absent on plans without a limit
`X-Quota-Used`	Events accepted so far in the current period
`X-Quota-Reset`	When the counter starts over, RFC 3339 in UTC
`X-Quota-Reset-In`	Seconds until that moment

Running out of quota does not make a ping fail. The request still answers 200, because a ping usually comes from a curl line inside a crontab: a 4xx would make cron report a job that ran perfectly as failed, and mail its owner about it. A billing problem must not become a production incident.

Going over the limit starts a grace period, during which events are still accepted and the overage is visible in the panel. Only after it runs out is the account’s monitoring suspended; from then on pings answer:

{
  "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."
}

The event is not stored, and alerting stays silent for the whole account - a suspended monitor must not raise a failure that is not happening. Monitoring resumes on its own when the quota resets, when the account drops back under its monitor limit, or as soon as the plan is upgraded.