Logs

Agents scale to zero when idle, which changes how logs work: live logs exist only while a pod is running, and history is persisted separately so it survives. This page covers both, plus follow mode and retention.

Live logs vs history

	Live logs	History
Source	The newest running pod	The platform's persisted log store
Survives scale-to-zero?	No — no pod, no live logs	Yes
Survives new revisions?	No — a rollout replaces the pod	Yes
Retention	Life of the pod	14 days by default
Follow/tail mode	Yes (?follow=true / -f)	No

These are management routes: sign in, owner or project admin only.

Live logs

GET /v1/agents/{name}/logs streams text/plain from the agent's newest live pod. Add ?follow=true to keep the connection open and tail new lines as they arrive.

platformctl logs research-buddy

Or follow:

platformctl logs research-buddy -f

The scale-to-zero message

If the agent is idle it has no pods, and that is normal — not an error. The endpoint answers 200 with exactly this message:

agent research-buddy has no live pods: it is scaled to zero (no running replicas), which is normal for an idle serverless agent - it cold-starts on the next invoke. For logs from earlier runs, use GET /v1/agents/research-buddy/logs/history.

A genuinely missing agent returns 404 instead. So: 200 with that message means "your agent is fine, just asleep"; 404 unknown agent: <name> means it doesn't exist (or isn't yours — see troubleshooting).

Log history

GET /v1/agents/{name}/logs/history returns persisted lines that survive scale-to-zero and revision rollouts.

Query parameters:

Parameter	Default	Meaning
limit	500	Maximum lines returned
since	—	RFC3339 timestamp; only lines after it

curl -s "$CAI_API/v1/agents/research-buddy/logs/history?limit=100" \
  -H "Authorization: Bearer $CAI_TOKEN"

You should see (oldest lines first):

{
  "agent": "research-buddy",
  "lines": [
    {
      "ts": "2026-08-10T09:12:02Z",
      "revision": "research-buddy-00002",
      "pod": "research-buddy-00002-deployment-6b7f9-xk2lp",
      "stream": "stdout",
      "message": "harness started, agent loaded"
    }
  ],
  "count": 1,
  "note": "persisted history - survives scale-to-zero and revision rollouts"
}

Each line records which revision and pod produced it — useful when a rollout changed behavior and you need to compare before and after.

With the CLI:

platformctl logs research-buddy --history

--follow and --history cannot be combined. Trying returns:

--follow and --history are mutually exclusive: --history reads persisted logs, --follow tails the live pod

Retention

History is kept for 14 days by default (platform-configurable via LOG_RETENTION). If you need logs for longer — audits, incident timelines — export them before they age out.

Where build output goes

There is no build-log endpoint. When a build fails, the tail of the build output (up to 4,000 characters, ending with ...(truncated) when cut) lands in the agent's message field — read it with platformctl status <agent> or GET /v1/agents/{name}, or see it rendered in full on the console's Overview tab. Runtime logs (this page) start only after a build succeeds and a pod runs. See troubleshooting for reading build failures.

Logs in the console

The agent detail page's Logs tab has both views — live (with follow) and persisted history — plus a line-wrap toggle for long JSON log lines.

Quick reference

Task	Command
Current logs	platformctl logs <agent>
Tail continuously	platformctl logs <agent> -f
After scale-to-zero or a rollout	platformctl logs <agent> --history
Build failure output	platformctl status <agent> (the message field)
Retention	14 days default