Agent: Logs

Download Page (.md)

The agent logs API exposes the active-supervisor log stream: query historical entries, read individual redacted entries, list log sources/facets, fetch volume statistics, and tail the log stream over Server-Sent Events. All routes are active-only — they have no realm dimension, and any X-Hoody-Realm header (or ?realm= query alias) is rejected with 400 realm_scope_unsupported. Use these endpoints from client.agent.logs.*.

`GET /api/v1/agent/logs`

Query the active-supervisor log stream. Filters ride as query params (source, level, host, since, until); ?limit=N caps the result set.

Parameters

Name	In	Type	Required	Description
`source`	query	string	No	Filter to a log source/facet (see `logsSources`).
`level`	query	string	No	Filter to a minimum log level.
`host`	query	string	No	Filter to a host.
`since`	query	string	No	Lower time/cursor bound (`since_seq` cursor passes through verbatim).
`until`	query	string	No	Upper time bound.
`limit`	query	integer	No	Caps the result set (daemon default 200). A non-numeric value is rejected `400`.
`realm`	query	string	No	Per-request realm selector (§6.1) — the `in:query` alias of the `X-Hoody-Realm` header (read only when the header is absent). Rejected (`400 realm_scope_unsupported`) on active-only / no-realm routes.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local). Rejected (`400`) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector (§6.1): `"global"` or a 24-hex id. Rejected (`400 realm_scope_unsupported`) on active-only / no-realm routes.

cURL
SDK

curl -G "https://api.hoody.com/api/v1/agent/logs" \
  -H "X-Hoody-Cwd: /home/user/project" \
  --data-urlencode "source=supervisor" \
  --data-urlencode "level=warn" \
  --data-urlencode "host=worker-01" \
  --data-urlencode "since=2025-01-15T10:00:00Z" \
  --data-urlencode "limit=100"

const { data } = await client.agent.logs.queryLogs({
  source: "supervisor",
  level: "warn",
  host: "worker-01",
  since: "2025-01-15T10:00:00Z",
  limit: 100,
  "X-Hoody-Cwd": "/home/user/project"
});

Responses

{
  "entries": [
    {
      "ref": "lg_01HMK3Q8Y3P9X7C2N5B6J8F4DA",
      "seq": 12340,
      "source": "supervisor",
      "level": "warn",
      "host": "worker-01",
      "ts": "2025-01-15T10:23:17.482Z",
      "message": "container heartbeat missed"
    },
    {
      "ref": "lg_01HMK3Q8Y3P9X7C2N5B6J8F4DB",
      "seq": 12341,
      "source": "supervisor",
      "level": "error",
      "host": "worker-01",
      "ts": "2025-01-15T10:23:18.011Z",
      "message": "tool run aborted by gate"
    }
  ],
  "next_seq": 12342,
  "has_more": false
}

{
  "code": "realm_scope_unsupported",
  "message": "realm scope not supported on this route"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through `hoody-proxy`: its source IP is private/local (in-container loopback, the bridge, the host, or a sibling container).	Reach the agent through `hoody-proxy` (e.g. `hoody agent …` → platform → proxy), not by connecting to the container directly.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded; the gateway throttled the request before dispatch.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

`GET /api/v1/agent/logs/entries/{ref}`

Read a single log entry by ref. Entries are ALWAYS redacted.

Parameters

Name	In	Type	Required	Description
`ref`	path	string	Yes	Path identifier.
`realm`	query	string	No	Per-request realm selector (§6.1) — the `in:query` alias of the `X-Hoody-Realm` header (read only when the header is absent). Rejected (`400 realm_scope_unsupported`) on active-only / no-realm routes.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local). Rejected (`400`) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector (§6.1): `"global"` or a 24-hex id. Rejected (`400 realm_scope_unsupported`) on active-only / no-realm routes.

cURL
SDK

curl "https://api.hoody.com/api/v1/agent/logs/entries/lg_01HMK3Q8Y3P9X7C2N5B6J8F4DA" \
  -H "X-Hoody-Cwd: /home/user/project"

const { data } = await client.agent.logs.readLogEntry({
  ref: "lg_01HMK3Q8Y3P9X7C2N5B6J8F4DA",
  "X-Hoody-Cwd": "/home/user/project"
});

Responses

{
  "ref": "lg_01HMK3Q8Y3P9X7C2N5B6J8F4DA",
  "seq": 12340,
  "source": "supervisor",
  "level": "warn",
  "host": "worker-01",
  "ts": "2025-01-15T10:23:17.482Z",
  "message": "container heartbeat missed",
  "fields": {
    "container_id": "cnt_01HMK3Q8Y3P9X7C2N5B6J8F4DX"
  }
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through `hoody-proxy`: its source IP is private/local (in-container loopback, the bridge, the host, or a sibling container).	Reach the agent through `hoody-proxy` (e.g. `hoody agent …` → platform → proxy), not by connecting to the container directly.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded; the gateway throttled the request before dispatch.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

`GET /api/v1/agent/logs/sources`

List the available log sources/facets that can be passed to the source query filter on queryLogs and streamLogs.

Parameters

Name	In	Type	Required	Description
`realm`	query	string	No	Per-request realm selector (§6.1) — the `in:query` alias of the `X-Hoody-Realm` header (read only when the header is absent). Rejected (`400 realm_scope_unsupported`) on active-only / no-realm routes.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local). Rejected (`400`) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector (§6.1): `"global"` or a 24-hex id. Rejected (`400 realm_scope_unsupported`) on active-only / no-realm routes.

cURL
SDK

curl "https://api.hoody.com/api/v1/agent/logs/sources" \
  -H "X-Hoody-Cwd: /home/user/project"

const { data } = await client.agent.logs.logsSources({
  "X-Hoody-Cwd": "/home/user/project"
});

Responses

{
  "sources": [
    { "id": "supervisor", "label": "Supervisor", "count": 5432 },
    { "id": "workflow",   "label": "Workflow",   "count": 8110 },
    { "id": "tool",       "label": "Tool runs",  "count":  345 },
    { "id": "system",     "label": "System",     "count":   73 }
  ]
}

{
  "code": "realm_scope_unsupported",
  "message": "realm scope not supported on this route"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through `hoody-proxy`: its source IP is private/local (in-container loopback, the bridge, the host, or a sibling container).	Reach the agent through `hoody-proxy` (e.g. `hoody agent …` → platform → proxy), not by connecting to the container directly.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded; the gateway throttled the request before dispatch.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

`GET /api/v1/agent/logs/stats`

Return log volume and level statistics.

Parameters

Name	In	Type	Required	Description
`realm`	query	string	No	Per-request realm selector (§6.1) — the `in:query` alias of the `X-Hoody-Realm` header (read only when the header is absent). Rejected (`400 realm_scope_unsupported`) on active-only / no-realm routes.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local). Rejected (`400`) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector (§6.1): `"global"` or a 24-hex id. Rejected (`400 realm_scope_unsupported`) on active-only / no-realm routes.

cURL
SDK

curl "https://api.hoody.com/api/v1/agent/logs/stats" \
  -H "X-Hoody-Cwd: /home/user/project"

const { data } = await client.agent.logs.logsStats({
  "X-Hoody-Cwd": "/home/user/project"
});

Responses

{
  "total": 13960,
  "by_level": {
    "debug": 1024,
    "info":  9120,
    "warn":  3380,
    "error":  436
  },
  "by_source": {
    "supervisor": 5432,
    "workflow":   8110,
    "tool":        345,
    "system":       73
  },
  "window": {
    "from": "2025-01-15T00:00:00Z",
    "to":   "2025-01-15T10:30:00Z"
  }
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through `hoody-proxy`: its source IP is private/local (in-container loopback, the bridge, the host, or a sibling container).	Reach the agent through `hoody-proxy` (e.g. `hoody agent …` → platform → proxy), not by connecting to the container directly.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded; the gateway throttled the request before dispatch.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

`GET /api/v1/agent/logs/stream`

Tail the active-supervisor log stream over Server-Sent Events. The gateway forward-pages the daemon with a cursor it advances each round (since_seq = the previous reply’s next_seq) and DRAINS capped pages before idling, so no row is skipped under load.

The tail rides the same seq / replay convention the session stream uses:

An entry frame per redacted row CARRYING id: <seq> — a reconnecting client resumes via the Last-Event-ID header, which overrides ?since_seq.
A lagged {code:replay_gap} frame when the caller’s cursor fell behind the ring.
Periodic heartbeats.
end on disconnect.

Filters ride query params (source, level, host, since_seq, …); ?limit caps each poll batch. Local sources only.

Parameters

Name	In	Type	Required	Description
`source`	query	string	No	Filter the tail to a log source/facet.
`level`	query	string	No	Filter to a minimum log level.
`host`	query	string	No	Filter to a host.
`since_seq`	query	integer	No	Initial resume cursor (the `Last-Event-ID` header overrides it). A non-numeric value is rejected `400`.
`limit`	query	integer	No	Caps each poll batch. A non-numeric value is rejected `400`.
`realm`	query	string	No	Per-request realm selector (§6.1) — the `in:query` alias of the `X-Hoody-Realm` header (read only when the header is absent). Rejected (`400 realm_scope_unsupported`) on active-only / no-realm routes.
`Last-Event-ID`	header	string	No	SSE resume cursor — the gateway `int64` seq to resume from; OVERRIDES the `?since_seq` query param. Sent automatically by an SSE client on reconnect.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local). Rejected (`400`) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector (§6.1): `"global"` or a 24-hex id. Rejected (`400 realm_scope_unsupported`) on active-only / no-realm routes.

cURL
SDK

curl -N "https://api.hoody.com/api/v1/agent/logs/stream?source=supervisor&level=info&since_seq=12340&limit=200" \
  -H "X-Hoody-Cwd: /home/user/project" \
  -H "Accept: text/event-stream"

// The SDK returns an AsyncIterable of decoded SSE frames.
const stream = client.agent.logs.streamLogs({
  source: "supervisor",
  level: "info",
  since_seq: 12340,
  limit: 200,
  "X-Hoody-Cwd": "/home/user/project"
});

for await (const frame of stream) {
  if (frame.event === "entry") console.log(frame.data);
  if (frame.event === "lagged") console.warn("replay gap — reset cursor");
}

Responses

HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

id: 12340
event: entry
data: {"ref":"lg_01HMK3Q8Y3P9X7C2N5B6J8F4DA","seq":12340,"source":"supervisor","level":"info","host":"worker-01","ts":"2025-01-15T10:30:00.114Z","message":"tool run started"}

id: 12341
event: entry
data: {"ref":"lg_01HMK3Q8Y3P9X7C2N5B6J8F4DB","seq":12341,"source":"supervisor","level":"warn","host":"worker-01","ts":"2025-01-15T10:30:00.842Z","message":"rate limit approached"}

: heartbeat

id: 12342
event: entry
data: {"ref":"lg_01HMK3Q8Y3P9X7C2N5B6J8F4DC","seq":12342,"source":"supervisor","level":"info","host":"worker-01","ts":"2025-01-15T10:30:01.077Z","message":"tool run finished"}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not arrive through `hoody-proxy`: its source IP is private/local (in-container loopback, the bridge, the host, or a sibling container).	Reach the agent through `hoody-proxy` (e.g. `hoody agent …` → platform → proxy), not by connecting to the container directly.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded; the gateway throttled the request before dispatch.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit).	Honor `Retry-After` and retry.