Agent Presence
No heartbeat data yet
Agents will appear here when they start reporting
| Agent Name | Status | Last Run | Runs (24h) | Actions |
|---|
No agents found
| ID | Agent | Status | Source | Started | Duration | Error |
|---|
No runs yet
Trigger Wake
0 = fire once. Minimum 1 minute.
Leave blank for unlimited.
Queued Wakeups
| ID | Agent | Source | Reason | Schedule | Status | Requested At | Actions |
|---|
No wakeup requests
Agent API
REST + MCP endpoints for programmatic heartbeat and wakeup management.
https://ss-heartbeat.ocuss.app
workspace parameter is mandatory.
/api/heartbeat/runs
List heartbeat runs in a workspace, newest first. Optionally filter by agent, status, limit, offset.
workspace (required) Slug or UUIDagent_id (optional) Filter by agentstatus (optional) queued|running|completed|failed|cancelledlimit (optional) Max results (default 50, max 200)offset (optional) Pagination offset/api/heartbeat/runs/{run_id}
Get a single heartbeat run by ID.
workspace (required) Slug or UUID/api/heartbeat/runs
Create a new heartbeat run. Also updates agent_presence.
agent_id * Agent UUIDinvocation_source (optional) routine|wakeup|mention|assignment|manual|peertrigger_detail (optional) Free text/api/heartbeat/runs/{run_id}
Update a heartbeat run's status, error, or next_action. Also updates agent_presence on status change.
status, error, next_action, finished_at, started_atcurl -X PATCH "https://ss-heartbeat.ocuss.app/api/heartbeat/runs/$RUN_ID?workspace=$MULTICA_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{"status":"running"}'
/api/heartbeat/events
List events for a heartbeat run, ordered by sequence.
workspace (required) Slug or UUIDrun_id * Run UUID/api/heartbeat/events
Append an event to a run. Auto-increments seq.
run_id * Run UUIDevent_type * tool_call|chat|status_change|error|output|claim|completemessage * Event message textlevel (optional) info|warn|error|debugstream (optional) stdout|stderr|tool|statepayload (optional) JSON object/api/heartbeat/wakeups
List wakeup requests in a workspace.
workspace (required) Slug or UUIDagent_id (optional) Filter by agentstatus (optional) queued|claimed|completed|cancelled|expired/api/heartbeat/wakeups
Create a wakeup request. Returns 409 Conflict if a duplicate queued wakeup exists within 30 seconds. If interval_seconds is provided for an agent that already has a scheduled wakeup, the existing schedule is silently cancelled and the new one replaces it. The response includes replaced_schedule_id when this happens.
agent_id * Agent UUIDsource * user|peer|mention|assignment|routine|autopilot|apireason * Wakeup reason textrequested_by_type (optional) member|agent|systemrequested_by_id (optional) Requester UUIDpayload (optional) JSON objectinterval_seconds (optional) >= 60 for recurringmax_fires (optional) Max repeat countcurl -X POST "https://ss-heartbeat.ocuss.app/api/heartbeat/wakeups?workspace=$MULTICA_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{"agent_id":"AGENT_UUID","source":"user","reason":"Manual wakeup"}'
/api/heartbeat/wakeups/{wakeup_id}
Cancel a queued or scheduled wakeup request.
workspace (required) Slug or UUID/api/heartbeat/wakeups/{wakeup_id}
Update an existing wakeup. Only queued or scheduled wakeups can be edited. For scheduled rows, changing interval_seconds resets next_fire_at to NOW + new interval. Changing agent_id on a scheduled row silently cancels any existing schedule for the new agent.
agent_id (optional) New agent UUIDreason (optional) Updated reasoninterval_seconds (optional) >= 60, resets next_firemax_fires (optional) Updated max repeat count/api/heartbeat/presence
List all agents with computed current_status (active/stale/offline) and staleness_seconds.
workspace (required) Slug or UUIDcurl "https://ss-heartbeat.ocuss.app/api/heartbeat/presence?workspace=$MULTICA_WORKSPACE_ID"
MCP Tools
heartbeat_request_wakeup(workspace_id, agent_id, source, reason, payload?, interval_seconds?, max_fires?)
heartbeat_list_runs(workspace_id, agent_id?, status?, limit?)
heartbeat_get_run(workspace_id, run_id)
heartbeat_record_event(workspace_id, run_id, event_type, message, level?, payload?)
heartbeat_get_presence(workspace_id)
heartbeat_complete_run(workspace_id, run_id, status, error?)
heartbeat_update_wakeup(workspace_id, wakeup_id, agent_id?, reason?, interval_seconds?, max_fires?)
Quick Reference
curl "https://ss-heartbeat.ocuss.app/api/heartbeat/presence?workspace=$MULTICA_WORKSPACE_ID"
curl -X POST "https://ss-heartbeat.ocuss.app/api/heartbeat/wakeups?workspace=$MULTICA_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{"agent_id":"AGENT_UUID","source":"user","reason":"Please investigate"}'
curl "https://ss-heartbeat.ocuss.app/api/heartbeat/runs?workspace=$MULTICA_WORKSPACE_ID&status=running"
curl -X PATCH "https://ss-heartbeat.ocuss.app/api/heartbeat/runs/$RUN_ID?workspace=$MULTICA_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{"status":"completed"}'
curl -X DELETE "https://ss-heartbeat.ocuss.app/api/heartbeat/wakeups/$WAKEUP_ID?workspace=$MULTICA_WORKSPACE_ID"
curl -X POST "https://ss-heartbeat.ocuss.app/api/heartbeat/wakeups?workspace=$MULTICA_WORKSPACE_ID" -H "Content-Type: application/json" -d '{"agent_id":"AGENT_UUID","source":"api","reason":"Periodic check","interval_seconds":120,"max_fires":5}'
curl -X PATCH "https://ss-heartbeat.ocuss.app/api/heartbeat/wakeups/$WAKEUP_ID?workspace=$MULTICA_WORKSPACE_ID" -H "Content-Type: application/json" -d '{"reason":"updated reason","interval_seconds":1800}'