Read logs

GET /v1/instances/{id}/logs returns a snapshot of the container’s own output, everything the entrypoint and the agent printed to stdout and stderr, plus a compact health readout. It is how you debug an instance that crashed after booting, or your own custom image that will not come up. Unlike exec, which needs a running container, logs works in any state: running, sleeping, stopped, or failed. That is the point. When a container will not stay up, exec has nothing to attach to, but its logs are still there. The one gap is an instance that slept so long it was parked off its host: its logs read empty until a wake brings it back.

A container that never got created at all (a bad image reference, or an exec format error from a wrong-architecture image) has no logs to show: logs is empty and health is null. The reason for that kind of failure lands in status_reason on the instance object, so fetch GET /v1/instances/{id} and read it. Logs cover the case where a container did start and then misbehaved.

Request

tail

integer

default:"500"

How many of the most recent log lines to return. Defaults to 500, capped at 2000 (a larger value is clamped down). A value that is not a positive integer returns 400 invalid_request.

Response

logs

string

The container’s combined stdout and stderr, most recent tail lines. Capped at 512 KB; see truncated. Empty when there is no container.

truncated

boolean

true when the output spilled past the 512 KB cap and the oldest lines were dropped.

health

object | null

A compact runtime readout, or null when there is no container. It answers “did it crash, and why.”

Show health

running

boolean

Whether the container is currently up.

restart_count

integer

How many times the container has booted beyond its first start. Wakes from auto-sleep count too, so a rising number on a sleeper is normal; a count that climbs while the instance never sleeps is a crash loop.

exit_code

integer | null

The last exit code when the runtime still has one, null otherwise. Expect null in most cases: crash evidence lives in logs, restart_count, and resource_verdict.

oom_suspected

boolean

Best-effort inference that the container was killed for exceeding its memory limit. resource_verdict.memory at "critical" is the reliable version of the same signal. If either fires, resize to a larger shape.

resource_verdict

object | null

Per-dimension pressure (memory, cpu, disk, and overall, each healthy, pressure, or critical), or null when the container is not running. memory reads "critical" after the instance has been killed for exceeding its memory limit.

fetched_at

integer

When the snapshot was taken, in epoch seconds.

Unknown, deleted, or other-workspace ids return 404 not_found. If the platform cannot reach the instance’s host, you get 502 provisioning_failed.

Example

curl "https://api.agent37.com/v1/instances/ab12cd34ef/logs?tail=200" \
  -H "Authorization: Bearer sk_live_..."

import requests

resp = requests.get(
    "https://api.agent37.com/v1/instances/ab12cd34ef/logs",
    headers={"Authorization": "Bearer sk_live_..."},
    params={"tail": 200},
)
result = resp.json()
print(result["health"], result["logs"])

const resp = await fetch(
  "https://api.agent37.com/v1/instances/ab12cd34ef/logs?tail=200",
  { headers: { Authorization: "Bearer sk_live_..." } }
);
const result = await resp.json();
console.log(result.health, result.logs);

{
  "logs": "[agent37-hermes] Booting (gateway_port=3737 ...)\n[agent37-hermes] Starting hermes gateway daemon...\n",
  "truncated": false,
  "health": {
    "running": true,
    "restart_count": 0,
    "exit_code": null,
    "oom_suspected": false,
    "resource_verdict": { "memory": "healthy", "cpu": "healthy", "disk": "healthy", "overall": "healthy" }
  },
  "fetched_at": 1781222420
}

Debugging a failed instance

When an instance is failed or stuck, logs and health together tell you which layer broke:

The image will not start (a climbing restart_count, with the same error at the top of logs on every boot): read the entrypoint’s own error. This is the usual signal for a custom image mistake, such as a missing binary, an entrypoint that exits, or a service that never listens on default_port.
It ran out of memory (resource_verdict.memory is "critical"): the agent needs a bigger box. Resize to a larger shape.
It booted but the agent is wedged: the logs show the last thing it did before it stopped responding. Restart to recover it.

Once you have a running container, drop into it with exec to inspect further.

Get started

Build with Agent37

Hosting API

Agent API

Reference

Request

Response

Example

Debugging a failed instance

​Request

​Response

​Example

​Debugging a failed instance

Request

Response

Example

Debugging a failed instance