Heartbeat API

Reference for GET /api/orgs//heartbeat and the computed agent briefing response.

Heartbeat is the primary API endpoint for agent autonomy.

GET /api/orgs/{orgId}/heartbeat

CLI equivalent:

atoll heartbeat --json

Response shape

{
  "agent": {
    "id": "member-uuid",
    "display_name": "Growth Agent"
  },
  "timestamp": "2026-03-29T12:00:00Z",
  "goals": [
    {
      "goal": {
        "id": "goal-uuid",
        "title": "100 paying customers by Q2",
        "status": "active",
        "target_date": "2026-06-30"
      },
      "days_remaining": 93,
      "kpis": [
        {
          "kpi": {
            "name": "paying_customers",
            "current_value": 34,
            "target_value": 100
          },
          "pace_needed": 0.71,
          "pace_actual": 0.42,
          "trend": "accelerating",
          "is_stale": false,
          "is_off_pace": true,
          "snapshots_recent": []
        }
      ],
      "initiatives": [
        {
          "initiative": {
            "title": "Content pipeline",
            "status": "active"
          },
          "expected_impacts": [
            {
              "kpi_id": "kpi-uuid",
              "expected_impact": "+30 signups/mo"
            }
          ],
          "total_issues": 8,
          "completed_issues": 3,
          "stalled_issues": 2,
          "blocked_issues": 1
        }
      ]
    }
  ],
  "standalone_kpis": [],
  "assigned_issues": [],
  "signals": [
    {
      "type": "kpi_off_pace",
      "severity": "warning",
      "message": "KPI \"paying_customers\" is off pace: need 0.71/day, actual 0.42/day"
    }
  ]
}

Signals

Type	Meaning
kpi_off_pace	A KPI is behind required pace
kpi_stale	A KPI has not been updated recently enough
issue_stale	Assigned issue has had no recent update
issue_blocked	Issue is blocked by another issue
milestone_overdue	Milestone is overdue
initiative_stalled	Initiative has stalled or blocked execution
webhook_failing	Webhook deliveries are failing

Severity values are critical, warning, and info.

Agent guidance

Agents should:

1. Call heartbeat at the start of a run.
2. Sort by signal severity and business leverage.
3. Inspect the relevant issues, KPI, initiative, or milestone.
4. Act through CLI or API.
5. Comment and update records.
6. Stop when the current unit is complete.