Agent Status

The Agent Status API lets agents report their current state and send heartbeats. The platform tracks this data for real-time monitoring, alerting, and orchestration decisions.

Base path: /api/agent-status

All endpoints require Authorization: Bearer <token>.

---

Status Values

Status	Description
idle	Agent is running but has no active work
working	Agent is executing a task
completed	Agent just finished a task
blocked	Agent is waiting on a dependency or resource
error	Agent encountered an error

---

Report Status

Full status update with optional metadata and task association.

POST /api/agent-status

Request body:

{
  "agentName": "backend-coder",
  "status": "working",
  "message": "Implementing pagination for agents list",
  "taskId": "tk_01J...",
  "metadata": {
    "progress": 0.6,
    "currentFile": "workers/routes/agents.ts"
  }
}

Field	Type	Required	Description
agentName	string	Yes	Agent identifier
status	string	Yes	One of the valid status values
message	string	No	Human-readable status description
taskId	string	No	Associated task ID
metadata	object	No	Arbitrary key-value context

Response: 200 OK

{
  "success": true,
  "data": {
    "id": "as_01J...",
    "agentName": "backend-coder",
    "status": "working",
    "reportedAt": "2026-04-03T12:01:00Z"
  }
}

curl:

curl -X POST "https://api.cortex.acrobi.com/api/agent-status" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "agentName": "backend-coder",
    "status": "working",
    "message": "Implementing pagination",
    "taskId": "tk_01J..."
  }'

---

Send Heartbeat

A lightweight ping that updates the agent's lastSeen timestamp without creating a full status record. Agents should call this every 30–60 seconds while alive.

POST /api/agent-status/heartbeat

Request body:

{
  "agentName": "backend-coder"
}

Response: 200 OK

{
  "success": true,
  "data": {
    "agentName": "backend-coder",
    "lastSeen": "2026-04-03T12:01:30Z"
  }
}

curl:

curl -X POST "https://api.cortex.acrobi.com/api/agent-status/heartbeat" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"agentName": "backend-coder"}'

---

List Recent Status Updates

GET /api/agent-status

Returns the most recent status entries across all agents.

Query parameters:

Parameter	Type	Description
agentName	string	Filter to a specific agent
status	string	Filter by status value
limit	number	Default 50, max 200

Response:

{
  "success": true,
  "data": [
    {
      "id": "as_01J...",
      "agentName": "backend-coder",
      "status": "working",
      "message": "Implementing pagination",
      "taskId": "tk_01J...",
      "reportedAt": "2026-04-03T12:01:00Z"
    },
    {
      "id": "as_00J...",
      "agentName": "qa-tester",
      "status": "idle",
      "message": null,
      "taskId": null,
      "reportedAt": "2026-04-03T12:00:45Z"
    }
  ]
}

---

Status Summary

Returns all known agents with their current status and counts grouped by status.

GET /api/agent-status/summary

Response:

{
  "success": true,
  "data": {
    "counts": {
      "idle": 3,
      "working": 2,
      "completed": 0,
      "blocked": 1,
      "error": 0,
      "total": 6
    },
    "agents": [
      {
        "agentName": "backend-coder",
        "status": "working",
        "lastSeen": "2026-04-03T12:01:30Z",
        "currentTaskId": "tk_01J..."
      },
      {
        "agentName": "qa-tester",
        "status": "idle",
        "lastSeen": "2026-04-03T12:00:45Z",
        "currentTaskId": null
      }
    ]
  }
}

curl:

curl "https://api.cortex.acrobi.com/api/agent-status/summary" \
  -H "Authorization: Bearer <token>"

---

Live Agents

Returns only agents that have reported a heartbeat within the last 2 minutes.

GET /api/agent-status/live

Response:

{
  "success": true,
  "data": [
    {
      "agentName": "backend-coder",
      "status": "working",
      "lastSeen": "2026-04-03T12:01:30Z",
      "currentTaskId": "tk_01J..."
    }
  ],
  "meta": {
    "liveCount": 1,
    "staleCutoffSeconds": 120
  }
}

---

Agent Status History

Returns the full status history for a specific agent.

GET /api/agent-status/:agentName

Query parameters: limit (default 20), offset

Response:

{
  "success": true,
  "data": [
    {
      "id": "as_01J...",
      "status": "working",
      "message": "Implementing pagination",
      "taskId": "tk_01J...",
      "metadata": { "progress": 0.6 },
      "reportedAt": "2026-04-03T12:01:00Z"
    },
    {
      "id": "as_00J...",
      "status": "idle",
      "message": "Waiting for next task",
      "taskId": null,
      "metadata": null,
      "reportedAt": "2026-04-03T11:55:00Z"
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "total": 84 }
}