Health, Metrics & Debugging

Monitor browser server health, surface performance metrics, and access buffered console and network logs. These endpoints let you verify the hoody-browser service is reachable, inspect the last 500 console messages or network requests, and query or purge persistent browsing history.

All endpoints in this section are scoped to a single browser container. The base URL is https://{projectId}-{containerId}-browser-1.{server}.containers.hoody.icu, where {projectId}, {containerId}, and {server} are substituted with your project, container, and server identifiers.

Health

GET /api/v1/browser/health

Returns standardized health metadata for the hoody-browser service using the shared 9-field contract.

This endpoint takes no parameters.

cURL

curl -X GET "https://abc123-xyz789-browser-1.eu-west-1.containers.hoody.icu/api/v1/browser/health"

SDK

await client.browser.health.check();

Response 200

Server is healthy.

{
  "status": "ok",
  "service": "hoody-browser",
  "built": "2026-01-12T08:00:00.000Z",
  "started": "2026-01-15T11:42:13.512Z",
  "memory": {
    "rss": 134217728,
    "heap": 67108864
  },
  "fds": 42,
  "pid": 17,
  "ip": "10.0.4.21",
  "userAgent": "hoody-sdk/1.4.2"
}

Field	Type	Description
status	string	Literal "ok" when the service is healthy.
service	string	Service identifier. Always "hoody-browser".
built	string	ISO-8601 mtime of the server module at startup. Nullable.
started	string	ISO-8601 timestamp when the process started.
memory	object	Process memory usage in bytes.
memory.rss	integer	Resident set size in bytes.
memory.heap	integer	V8 heapUsed in bytes. Nullable.
fds	integer	Number of open file descriptors. Nullable on non-Linux.
pid	integer	Process id.
ip	string	Caller’s socket remote address (no X-Forwarded-For).
userAgent	string	Caller’s User-Agent header, if present. Nullable.

Debugging

The debugging endpoints expose the browser’s in-memory console and network buffers. Each buffer retains the last 500 entries and can be drained with the clear flag.

GET /console

Returns buffered browser console messages (console.log, console.error, page errors).

Parameters

Name	In	Type	Required	Description
browser_id	query	string	Yes	Unique identifier for the browser instance (0-based index).
tabId	query	integer	No	The ID of the tab to filter by.
start	query	boolean	No	Controls instance creation behavior. Default mode: instances are created automatically. Set to false to prevent creation. When auto-start is disabled globally: set to true to create an instance. Default: true.
type	query	string	No	Filter by message type (log, error, warning, info, etc.).
since	query	string	No	Only return logs after this ISO timestamp.
clear	query	boolean	No	Clear the buffer after reading. Default: false.

cURL

curl -X GET "https://abc123-xyz789-browser-1.eu-west-1.containers.hoody.icu/console?browser_id=0&type=error&since=2026-01-15T10:00:00.000Z"

SDK

await client.browser.debugging.getConsoleLogs({
  browser_id: "0",
  type: "error",
  since: "2026-01-15T10:00:00.000Z"
});

Response 200

Console logs retrieved.

{
  "logs": [
    {
      "timestamp": "2026-01-15T11:55:01.123Z",
      "type": "error",
      "text": "Uncaught ReferenceError: foo is not defined",
      "tabId": 1
    },
    {
      "timestamp": "2026-01-15T11:55:04.881Z",
      "type": "warning",
      "text": "Deprecated API used: document.origin",
      "tabId": 2
    }
  ],
  "count": 2
}

Field	Type	Description
logs	array	Buffered console messages.
logs[].timestamp	string	ISO-8601 timestamp the message was captured.
logs[].type	string	Message type (for example log, error, warning, info).
logs[].text	string	Console message text.
logs[].tabId	integer	Tab that produced the message.
count	integer	Total entries returned.

GET /network

Returns buffered network request and response entries.

Parameters

Name	In	Type	Required	Description
browser_id	query	string	Yes	Unique identifier for the browser instance (0-based index).
tabId	query	integer	No	The ID of the tab to filter by.
start	query	boolean	No	Controls instance creation behavior. Default mode: instances are created automatically. Set to false to prevent creation. When auto-start is disabled globally: set to true to create an instance. Default: true.
since	query	string	No	Only return logs after this ISO timestamp.
clear	query	boolean	No	Clear the buffer after reading. Default: false.

cURL

curl -X GET "https://abc123-xyz789-browser-1.eu-west-1.containers.hoody.icu/network?browser_id=0&clear=true"

SDK

await client.browser.debugging.getNetworkLogs({
  browser_id: "0",
  clear: true
});

Response 200

Network logs retrieved.

{
  "logs": [
    {
      "timestamp": "2026-01-15T11:56:02.444Z",
      "method": "GET",
      "url": "https://api.example.com/v1/users",
      "status": 200,
      "resourceType": "xhr",
      "tabId": 1
    },
    {
      "timestamp": "2026-01-15T11:56:03.991Z",
      "method": "POST",
      "url": "https://api.example.com/v1/events",
      "status": 500,
      "resourceType": "fetch",
      "tabId": 1
    }
  ],
  "count": 2
}

Field	Type	Description
logs	array	Buffered network entries.
logs[].timestamp	string	ISO-8601 timestamp the request fired.
logs[].method	string	HTTP method.
logs[].url	string	Request URL.
logs[].status	integer	HTTP response status code. Nullable if the response did not complete.
logs[].resourceType	string	Resource type (for example xhr, fetch, document, script).
logs[].tabId	integer	Tab that issued the request.
count	integer	Total entries returned.

Browsing History

History is recorded for all navigations, whether triggered by the API or by the user, and is read from persistent storage. Use these endpoints to inspect and prune that record.

GET /history

Returns paginated browsing history entries with optional filters.

Parameters

Name	In	Type	Required	Description
since	query	string	No	Return entries after this ISO 8601 timestamp.
domain	query	string	No	Filter by domain (exact match).
browser_id	query	string	No	Filter by browser ID.
limit	query	integer	No	Maximum entries to return (1-500). Default: 50.
offset	query	integer	No	Number of entries to skip for pagination. Default: 0.

cURL

curl -X GET "https://abc123-xyz789-browser-1.eu-west-1.containers.hoody.icu/history?domain=example.com&limit=20&offset=0"

SDK

await client.browser.history.list({
  domain: "example.com",
  limit: 20,
  offset: 0
});

Response 200

History entries retrieved successfully.

{
  "entries": [
    {
      "id": "1709913600000-a3f2",
      "url": "https://example.com",
      "requestedUrl": "https://example.com",
      "title": "Example Domain",
      "domain": "example.com",
      "tabId": 1,
      "browserId": "0",
      "browserPort": 9223,
      "sessionId": "s-7c9a",
      "httpStatus": 200,
      "error": null,
      "source": "api",
      "timestamp": "2026-01-15T11:30:00.000Z",
      "created": true,
      "reused": false
    }
  ],
  "total": 1,
  "has_more": false,
  "limit": 20,
  "offset": 0
}

Response 400

Invalid parameters.

{
  "error": "limit must be between 1 and 500",
  "code": "INVALID_PARAMETER",
  "details": {
    "parameter": "limit",
    "value": 1000
  }
}

Response 404

History is disabled.

{
  "error": "Browsing history storage is disabled",
  "code": "HISTORY_DISABLED",
  "details": {}
}

Field	Type	Description
entries	array	Navigation records matching the query.
total	integer	Total matching entries (bounded for global queries).
has_more	boolean	Whether more entries exist beyond the current page.
limit	integer	Echo of the applied limit.
offset	integer	Echo of the applied offset.

Each entry follows the NavigationRecord shape:

Field	Type	Description
id	string	Unique navigation entry ID (timestamp-random).
url	string	Final URL after navigation.
requestedUrl	string	Original URL passed to /browse.
title	string	Page title after navigation.
domain	string	Extracted hostname.
tabId	integer	Browser tab ID.
browserId	string	Derived browser ID.
browserPort	integer	Browser instance port.
sessionId	string	Session identifier.
httpStatus	integer	HTTP status code. Nullable for manual navigations.
error	string	Error message if navigation failed. Nullable.
source	string	Navigation source. api for /browse calls, page for framenavigated events.
timestamp	string	ISO 8601 timestamp.
created	boolean	Whether a new tab was created.
reused	boolean	Whether an existing tab was reused.

DELETE /history

Deletes browsing history entries matching the given filters. Without filters, all history is deleted.

Parameters

Name	In	Type	Required	Description
before	query	string	No	Delete entries before this ISO 8601 timestamp.
browser_id	query	string	No	Delete entries for a specific browser ID only.

cURL

curl -X DELETE "https://abc123-xyz789-browser-1.eu-west-1.containers.hoody.icu/history?before=2026-01-10T00:00:00.000Z"

SDK

await client.browser.history.clear({
  before: "2026-01-10T00:00:00.000Z"
});

Response 200

History deleted successfully.

{
  "deleted": 142
}

Response 400

Invalid parameters.

{
  "error": "Invalid ISO 8601 timestamp for 'before'",
  "code": "INVALID_PARAMETER",
  "details": {
    "parameter": "before",
    "value": "yesterday"
  }
}

Response 404

History is disabled.

{
  "error": "Browsing history storage is disabled",
  "code": "HISTORY_DISABLED",
  "details": {}
}

Field	Type	Description
deleted	integer	Number of entries deleted.

Caution

Deleting history without any filter removes every persisted entry. Always scope the call with before or browser_id when you only want a partial purge.