Logs API

Search continuously-collected log history, or live-tail a container or pod on demand.

KubeWatch collects container and pod logs two ways, covered by two separate API surfaces. See Agent architecture for how each one works under the hood.

Base URL: https://YOUR_KUBEWATCH_URL (your KubeWatch instance, shown in your dashboard)

All requests require Authorization: Bearer <token> or X-API-Key: <key>.

Search log history

GET /api/v1/logs/search

Searches logs continuously collected in the background, across every container and pod, whether or not anyone had the Logs page open when a line was written. Available on every plan.

Query parameters (all optional):

Parameter	Description
`q`	Free-text search against the log message.
`source`	`docker` or `kubernetes`.
`agentId`	Restrict to one agent.
`containerId` / `containerName`	Docker container filters.
`namespace` / `pod` / `container`	Kubernetes filters.
`stream`	`stdout` or `stderr`.
`start` / `end`	RFC3339 timestamps. Defaults to the last hour.
`limit`	Max results, up to 1000. Defaults to 200.

Response 200:

[
  {
    "time": "2026-07-21T10:15:32.123456789Z",
    "source": "kubernetes",
    "agentId": "agent_abc123xyz",
    "namespace": "prod",
    "pod": "checkout-api-7d8f9c6b5-x8k2p",
    "container": "checkout-api",
    "stream": "stderr",
    "message": "context deadline exceeded calling payments-service"
  }
]

Results are returned most-recent-first.

This is separate from the **live-tail** endpoints below. Those show you what's happening right now, while you're watching. This one searches everything already collected, going back as far as your organization's log retention allows.

Live-tail a Docker container

GET /api/v1/logs/containers/{id}

Server-Sent Events (SSE). Requests the agent tail a specific container's logs on demand, and streams lines back as they arrive. Requires the Pro plan or higher; on a plan without log streaming this returns 403 with {"error":"Log streaming is available on the Pro plan"} instead of opening the stream.

Query parameters:

Parameter	Description
`tail`	Number of historical lines to include before following. Defaults to `100`.
`sinceSeconds`	Only lines newer than this many seconds ago.
`follow`	`1` to keep the connection open and stream new lines as they're written. Omit for a one-shot tail.

Events: connected, waiting, log ({ "line", "source", "ts" }), end, error.

Live-tail a Kubernetes pod

GET /api/v1/logs/pods/{namespace}/{name}

Same shape as the container endpoint above, including the Pro-plan requirement, with an additional optional container query parameter when the pod has more than one container.