Ping API
Jobs report to a heartbeat monitor by calling its ping URL. To create and manage monitors, use the REST API.
Conventions
Section titled “Conventions”| Convention | Value |
|---|---|
| Host | https://ping.chronos.sh |
| Authentication | None. The token in the path is the credential. |
| Methods | GET, HEAD, POST |
| Response type | text/plain, with Cache-Control: no-store |
A ping URL is the monitor’s ping_url, such as https://ping.chronos.sh/k3Jx9Qm2TnV7bRw4YcZ8dHfL. The token is 24 letters and digits. Anyone with the URL can ping the monitor. Treat the URL as a secret, and rotate it if it leaks.
| Path | Ping kind | Effect |
|---|---|---|
/<token> |
success | Marks the run succeeded. The monitor goes up, and a down monitor sends an up alert. |
/<token>/fail |
fail | Marks the run failed. The monitor goes down. It sends a down alert unless it was already down. |
/<token>/<exit-code> |
success or fail | An integer from 0 to 255. 0 is a success ping, and any other code is a fail ping. The ping history and the down alert show the code. |
/<token>/start |
start | Marks the run started. Changes no status or deadline. The next success or fail ping records the time since the start ping as the run’s duration. |
A success or fail ping sets the monitor’s next deadline. See Cadence and grace period.
Request body
Section titled “Request body”A POST body is optional. Chronos stores the first 10 KB as text with the ping, whatever its content type. The down alert shows the first 500 characters of a fail ping’s body, so send the error message or the end of the job’s output. GET and HEAD pings have no body.
Chronos stops reading a body at 1 MB. It records the ping with the first 10 KB and closes the connection after the response.
Responses
Section titled “Responses”| Status | Body | When |
|---|---|---|
200 |
OK |
The ping was recorded. |
400 |
Exit code must be an integer from 0 to 255 |
The second path segment isn’t start, fail, or an integer from 0 to 255. |
404 |
Not found |
The token is unknown, malformed, or rotated, or the path has more than two segments. |
405 |
Method not allowed |
The method isn’t GET, HEAD, or POST. The Allow header lists those three. |
429 |
Too many pings, ping not recorded |
A rate limit was hit. The Retry-After header gives the seconds to wait. |
500 |
Internal error |
Chronos couldn’t record the ping. Retry it. |
HEAD responses carry the same status with no body.
Rate limits
Section titled “Rate limits”| Limit | Window |
|---|---|
| 10 pings per token | 1 minute |
| 300 pings per client IP | 10 seconds |
The limits are counted per Chronos API instance. A rate-limited ping isn’t recorded, so a job that pings more than 10 times a minute loses pings. The per-IP limit is high enough for many monitors on one CI runner or server.
Paused monitors
Section titled “Paused monitors”A ping to a paused monitor returns 200 and updates the monitor’s last_ping. It isn’t kept in the ping history, sends no alert, and changes no status or deadline.
Ping history
Section titled “Ping history”Each recorded ping keeps its kind, exit code, duration, body, method, User-Agent header, and the time Chronos received it. Chronos keeps the latest 1,000 pings per monitor. Read them with GET /v1/monitors/:id/pings.