Logs

Agents scale to zero when idle, and that changes how logs work. Live logs exist only while an instance — one running copy of your agent — is up. History is saved separately, so it outlives the instance. This page covers both, plus how to tail logs as they arrive and how long history is kept.

Live logs vs history

	Live logs	History
Source	The newest running instance	The platform's persisted log store
Survives scale-to-zero?	No — no instance, no live logs	Yes
Survives new revisions?	No — a rollout replaces the instance	Yes
Retention	Life of the instance	14 days by default
Follow/tail mode	Yes, from the CLI and the API	No

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

Live logs

GET /v1/agents/{name}/logs streams the log as text/plain — plain text, not JSON — from the agent's newest running instance.

platformctl

platformctl logs research-buddy

That prints what the instance has buffered and returns. To hold the connection open and print new lines as they are written:

platformctl logs research-buddy -f

A followed stream runs without a client timeout, so it tails until you stop it with Ctrl-C.

curl

curl -s "$CAI_API/v1/agents/research-buddy/logs" \
  -H "Authorization: Bearer $CAI_TOKEN"

Add ?follow=true to hold the connection open and receive new lines as they are written, instead of getting a snapshot and stopping:

curl -sN "$CAI_API/v1/agents/research-buddy/logs?follow=true" \
  -H "Authorization: Bearer $CAI_TOKEN"

-N turns off curl's output buffering, so lines appear as they arrive rather than in blocks.

Console

Open the agent's Logs tab and click Live instance.

You should see: the newest instance's buffered output. The console does not follow the stream — it re-reads on demand. Use Refresh, or tick auto-refresh every 5s to have it re-read for you. No wrap toggles line wrapping, which is what makes long structured log lines readable.

If the agent is idle there is no instance to read, and the tab offers Show history instead.

The scale-to-zero message

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

agent research-buddy has no running instances: it is scaled to zero, 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.

An agent that really is missing returns 404 instead. Read the two codes like this. A 200 carrying that message means your agent is fine, just asleep. A 404 with unknown agent: <name> means it does not exist — or it exists and is not yours, since the API answers both cases the same way. 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

platformctl

platformctl logs research-buddy --history

You should see (oldest lines first):

2026-08-10T09:12:02Z  stdout  harness started, agent loaded
2026-08-10T09:12:44Z  stdout  invoke session=3f2c8a1e-… tool=run_python

The CLI sends no limit or since, so it takes the server's default of 500 lines. Add -o json for the full objects, revision and instance included. An agent with nothing collected prints no persisted logs.

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

--follow and --history are mutually exclusive: --history reads persisted logs, --follow tails a running instance

curl

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",
      "instance": "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"
}

An agent with no persisted lines answers 200 with "count": 0 and an empty lines array, not a 404.

Console

Open the agent's Logs tab. History is the view it opens on, because it is the one that has something in it most of the time.

You should see: the last 500 persisted lines, oldest first, each prefixed with its timestamp and stream. Refresh, auto-refresh every 5s, and the wrap toggle work the same as in the live view.

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

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 last part of the build output lands in the agent's message field instead — up to 4,000 characters, ending in ...(truncated) if it had to be cut. Read it with platformctl status <agent> or GET /v1/agents/{name}, or see it laid out on the console's Overview tab.

The runtime logs this page describes are a different thing. They begin only after a build succeeds and an instance actually runs. See troubleshooting for reading build failures.

Summary

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

Next steps

• Troubleshooting — read a failed build's output and diagnose a stuck deploy.
• Traffic and revisions — why --history spans a rollout.
• Invoke an agent — the tool_calls and stream lines these logs echo.
• Quotas and audit — the audit log, for state changes rather than runtime output.