Health, Metrics & Debugging

Download Page (.md)

The Hoody browser service provides a set of endpoints for monitoring server health, retrieving debugging logs, and querying browsing history. Use these endpoints to integrate liveness checks, capture console and network activity, and manage the persistent navigation history of browser instances.

Health check

`GET /api/v1/browser/health`

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

This endpoint takes no parameters.

curl -X GET https://api.hoody.com/api/v1/browser/health

const health = await client.browser.health.check();

{
  "status": "ok",
  "service": "hoody-browser",
  "built": "2025-01-15T10:30:00.000Z",
  "started": "2025-01-20T14:22:18.452Z",
  "memory": {
    "rss": 134217728,
    "heap": 73400320
  },
  "fds": 42,
  "pid": 18432,
  "ip": "10.0.0.42",
  "userAgent": "HoodySDK/1.0"
}

Console logs

`GET /console`

Returns buffered browser console messages (console.log, console.error, page errors). The buffer keeps the last 500 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 interact with
`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 -X GET "https://api.hoody.com/console?browser_id=0&tabId=1&type=error&clear=false"

const result = await client.browser.debugging.getConsoleLogs({
  browser_id: "0",
  tabId: 1,
  type: "error",
  clear: false
});

{
  "logs": [
    {
      "timestamp": "2025-01-20T14:25:03.118Z",
      "type": "error",
      "text": "Uncaught ReferenceError: foo is not defined",
      "tabId": 1
    },
    {
      "timestamp": "2025-01-20T14:25:14.502Z",
      "type": "warning",
      "text": "Deprecation: Third-party cookie will be blocked in a future release.",
      "tabId": 1
    }
  ],
  "count": 2
}

Network logs

`GET /network`

Returns buffered network request/response entries captured from browser traffic. The buffer keeps the last 500 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 interact with
`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 -X GET "https://api.hoody.com/network?browser_id=0&tabId=1&since=2025-01-20T14:00:00.000Z"

const result = await client.browser.debugging.getNetworkLogs({
  browser_id: "0",
  tabId: 1,
  since: "2025-01-20T14:00:00.000Z"
});

{
  "logs": [
    {
      "timestamp": "2025-01-20T14:25:03.045Z",
      "method": "GET",
      "url": "https://example.com/api/users",
      "status": 200,
      "resourceType": "fetch",
      "tabId": 1
    },
    {
      "timestamp": "2025-01-20T14:25:03.502Z",
      "method": "POST",
      "url": "https://example.com/api/events",
      "status": 201,
      "resourceType": "fetch",
      "tabId": 1
    }
  ],
  "count": 2
}

Browsing history

Browsing history is recorded for all navigations, including those triggered through the API and manual page navigations. History entries are read from persistent storage via symlinked directories.

`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 -X GET "https://api.hoody.com/history?domain=example.com&limit=25&offset=0"

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

{
  "entries": [
    {
      "id": "1737385503045-a3f2",
      "url": "https://example.com/dashboard",
      "requestedUrl": "https://example.com/dashboard",
      "title": "Dashboard - Example",
      "domain": "example.com",
      "tabId": 1,
      "browserId": "0",
      "browserPort": 9222,
      "sessionId": "sess-7c2a18",
      "httpStatus": 200,
      "error": null,
      "source": "api",
      "timestamp": "2025-01-20T14:25:03.045Z",
      "created": false,
      "reused": true
    }
  ],
  "total": 1,
  "has_more": false,
  "limit": 25,
  "offset": 0
}

{
  "error": "Invalid value for parameter 'limit'",
  "code": "INVALID_PARAMETER",
  "details": {
    "parameter": "limit",
    "received": 0,
    "allowed": "1-500"
  }
}

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

`DELETE /history`

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

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 specific browser ID only

curl -X DELETE "https://api.hoody.com/history?before=2025-01-01T00:00:00.000Z&browser_id=0"

const result = await client.browser.history.clear({
  before: "2025-01-01T00:00:00.000Z",
  browser_id: "0"
});

{
  "deleted": 142
}

{
  "error": "Invalid value for parameter 'before'",
  "code": "INVALID_PARAMETER",
  "details": {
    "parameter": "before",
    "received": "not-a-date",
    "allowed": "ISO 8601 timestamp"
  }
}

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