Send Agent Runner Heartbeat
POST/api/automation/runner/heartbeat
Report that the runner is alive and which job templates it can handle. Call it on start-up and periodically (any authenticated call also marks the runner as seen; a runner counts as online for 90 seconds).
Called by your own agent or script with the token SKU issued for this runner or callback, sent as Authorization: Bearer <token> — not with a Personal Access Token or a session.
Authenticate with the runner token as Authorization: Bearer <runner token> (not a Personal Access Token).
Body (all optional)
version(string, max 32) - runner software version.hostname(string, max 255).templates(array, max 100) - template keys this runner handles; letters, digits,.,_,-,:, starting with a letter or digit, max 120 chars. Replaces the previously advertised list; only jobs with these templates are offered to the runner.
Returns the runner as the server sees it plus server_time. Returns 401 for a missing, invalid or revoked token, 413 for a body over 256 KB, 421 when the request reached the wrong regional host (retry at redirect_to), 422 for validation errors, 429 above 240 requests a minute per token.
Request
Responses
- 200
- 401
- 403
- 421
- 422
- 429
OK
Response Headers
Unauthorized
Response Headers
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Misdirected Request
Response Headers
Unprocessable Entity
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.