Ping API

Send a heartbeat with one HTTP request.

Your automation pings a URL, and Checkilo watches for it. The Ping API is that call: a plain HTTP request you can send from Make, Zapier, cron, curl, or any code, in any language.

Start free Jump to the reference

Works everywhere

One request, from any tool that speaks HTTP.

The ping URL takes a plain HTTP request, so anything that can make one can report to Checkilo.

No-code platforms

Any no-code automation tool that can send an HTTP request calls the ping URL directly. Same monitoring, one request.

Scripts and cron jobs

A shell script, a scheduled cron task, or a serverless function adds one curl line to report that it ran. No SDK, no dependency.

Your own code

A backend in any language sends a GET or POST when a job starts and finishes. If it can make an HTTP request, it can ping Checkilo.

Reference

The Ping API.

Each automation has its own unique ping URL, shown in your dashboard. The examples below use a sample.

Base host

Production

https://ping.checkilo.app

A full ping URL looks like https://ping.checkilo.app/8f3ac1e2. 8f3ac1e2 is a sample; use your automation's own ping URL from the dashboard.

Request

Use GET or POST. POST is recommended so you can send a JSON body. The path after the ping URL is the segment:

https://ping.checkilo.app/8f3ac1e2/<segment>

Segment	Meaning
`/start`	Workflow run started.
`/checkpoint`	An intermediate step. Pair with ?label= to name it.
`/success`	Run finished OK. Alias: /ok.
`/fail`	Run failed. Alias: /failure.
`(no segment)`	Treated as a one-shot success event.

Event ping (one-shot): POST to <ping-url>/success or <ping-url>/fail.

Workflow ping (correlated): send /start, then any /checkpoint?label=..., then /success or /fail. Give every step the same ?run= value and they group into one run.

Query parameters

Both are optional.

Parameter	What it does
`run`	Correlation id. Use the same value across the steps of one run to group them into a single run. Omit it and the ping is treated standalone.
`label`	Checkpoint name. Only meaningful on the checkpoint segment; ignored on the others.

Authentication

Send your API key as a Bearer token:

Authorization: Bearer <API_KEY>

Auth is optional by default. It is required only when an automation has Require API key turned on, a per-automation setting. When it is required and the Bearer token is missing or wrong, the ping returns 401.

Request body

Optional. Send Content-Type: application/json with an arbitrary JSON object of metadata. The hard limit is 4 KB (4096 bytes); a larger body is rejected with 400.

Success response

A successful ping returns 200 with this JSON:

{
  "received_at": "2025-06-21T12:34:56.789Z",
  "ping_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "success"
}

status is "failure" for the fail segment. An error string is added when a domain rule was violated, for example a checkpoint received before a start.

Error responses

Errors use the same JSON envelope; ping_id may be null.

{
  "received_at": "2025-06-21T12:34:56.789Z",
  "ping_id": null,
  "status": "failure",
  "error": "rate limit exceeded"
}

Status	When	error
`400`	Invalid JSON, an unknown segment, or a body over 4 KB.	`"..."`
`401`	Missing or invalid Bearer on a protected automation.	`"unauthorized"`
`404`	Unknown ping URL. Also returned to hide protected URLs.	`"automation not found"`
`429`	Rate limit exceeded.	`"rate limit exceeded"`
`500`	Server error.	`"internal error"`

Rate limits

Pings per second, per automation. Over quota returns 429.

Free

1 / s

Pro

10 / s

Examples

A one-shot success event

curl -X POST "https://ping.checkilo.app/8f3ac1e2/success"

A correlated workflow run (start, checkpoint, success)

curl -X POST "https://ping.checkilo.app/8f3ac1e2/start?run=order-1042"
curl -X POST "https://ping.checkilo.app/8f3ac1e2/checkpoint?run=order-1042&label=charged"
curl -X POST "https://ping.checkilo.app/8f3ac1e2/success?run=order-1042"

With Bearer auth and a JSON metadata body

curl -X POST "https://ping.checkilo.app/8f3ac1e2/success?run=order-1042" \
  -H "Authorization: Bearer $CHECKILO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customer":"acme","amount":129.0}'

8f3ac1e2 is a sample; replace it with your own ping URL from the dashboard.

Two things, two places

Where to get your ping URL and API key.

Your ping URL

Each automation has its own unique ping URL, shown on its page in the Checkilo dashboard. Copy it, then add the segment your call needs.

Open the dashboard

Your API key

Create an API key on the API keys page. You only need it for automations with Require API key turned on. It is a separate thing from the ping URL.

Manage API keys

One HTTP request away from a monitored automation.

Free for 5 automations, no card. Create one, copy its ping URL, and your first run appears on the timeline.

Start free: 5 automations, no card Read the reference