Send AI Runner Heartbeat
POST/api/support/agent/ai/runner-heartbeat
The AI agent's runner reports in: its version, the host it runs on, the sessions it is running, the size of its local queue and how much room it has. Sent on every check-in; the status reads as online for 5 minutes after the last one. A support.ai.changed push goes out only when the runner comes back online or its set of running sessions changes.
support:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Request body
version(string, optional, max 64)host(string, optional, max 255)running(array, required — empty when idle, max 100): each{ticket_id (integer, required), phase (string, optional, max 40), started_at (ISO 8601, optional)}queue_size(integer, optional, min 0, default 0)owner_email(string, optional, email) — the person this runner works for; must be the person the token is bound to, otherwise 422accepting(boolean, optional, default true) — false while the runner is paused on its machine (it then takes no unassigned tickets)max_sessions(integer, optional, 0–100) — how many sessions the runner works at oncedisk_free_gb(integer, optional, min 0) — free disk on the runner's machine, in GB
When several runners take unassigned tickets, each unassigned ticket goes to the one with the most room: the most free session slots (max_sessions minus running sessions), then the most free disk. A runner that omits max_sessions never outranks one that reports it.
The response is the new status (fields as in Get AI Agent Status) plus me — this runner's own routing settings and presence (fields as in Get My AI Runner). A heartbeat from a second machine while the first is online flags host_conflict on the runner.
Authentication: Bearer token with the support:write scope belonging to the AI agent's own account — any other caller, including support admins, gets a 403. No tenant context — this endpoint is central.
Request
Responses
- 200
- 401
- 403
- 422
- 429
OK
Response Headers
Unauthorized
Response Headers
Forbidden
Response Headers
Unprocessable Content
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.