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
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, or the monthly event quota for the plan has been used up ("code": "quota_exceeded").