Skip to main content

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.

Required scope: support:write

Grant 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 422
  • accepting (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 once
  • disk_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​

OK

Response Headers
    Content-Type