Health, Metrics & Debugging

The browser service exposes endpoints for monitoring server health, retrieving buffered console and network logs for debugging, and querying or deleting persistent browsing history. Use these endpoints to instrument your integration, troubleshoot page behavior, and audit navigation activity across browser instances.

Health Check

Check service health

GET /api/v1/browser/health

Returns standardized health metadata for the hoody-browser service, including process identifiers, memory usage, file descriptor counts, and the caller’s remote address. The response conforms to the 9-field health contract shared across all hoody-kit services.

This endpoint takes no parameters.

curl https://api.hoody.com/v1/browser/health \
  -H "Authorization: Bearer YOUR_API_KEY"

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

console.log(health.status);    // "ok"
console.log(health.service);   // "hoody-browser"
console.log(health.pid);       // process id
console.log(health.memory);    // { rss, heap }

{
  "status": "ok",
  "service": "hoody-browser",
  "built": "2024-01-15T10:30:00.000Z",
  "started": "2024-03-10T08:15:00.000Z",
  "memory": {
    "rss": 134217728,
    "heap": 50331648
  },
  "fds": 42,
  "pid": 12345,
  "ip": "192.168.1.100",
  "userAgent": "HoodySDK/1.0"
}

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.
`started`	string	ISO-8601 timestamp when the process started.
`memory`	object	Process memory usage in bytes. Contains `rss` (resident set size) and `heap` (V8 heapUsed).
`fds`	integer	Number of open file descriptors (`null` 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.

Debugging

Get console logs

GET /console

Returns buffered browser console messages (log, error, warning, info, and page errors). The buffer retains the last 500 entries per browser instance.

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 "https://api.hoody.com/v1/browser/console?browser_id=0&tabId=0&type=error" \
  -H "Authorization: Bearer YOUR_API_KEY"

const { logs, count } = await client.browser.debugging.getConsoleLogs({
  browser_id: "0",
  tabId: 0,
  type: "error"
});

console.log(`Retrieved ${count} console messages`);
for (const entry of logs) {
  console.log(`[${entry.type}] ${entry.text}`);
}

{
  "logs": [
    {
      "timestamp": "2024-03-10T08:15:30.123Z",
      "type": "log",
      "text": "Page loaded successfully",
      "tabId": 0
    },
    {
      "timestamp": "2024-03-10T08:15:31.456Z",
      "type": "error",
      "text": "Failed to fetch user profile: 500",
      "tabId": 0
    }
  ],
  "count": 2
}

Get network logs

GET /network

Returns buffered network request and response entries. The buffer retains the last 500 entries per browser instance.

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 "https://api.hoody.com/v1/browser/network?browser_id=0&tabId=0&clear=false" \
  -H "Authorization: Bearer YOUR_API_KEY"

const { logs, count } = await client.browser.debugging.getNetworkLogs({
  browser_id: "0",
  tabId: 0
});

console.log(`Recorded ${count} network requests`);
for (const entry of logs) {
  console.log(`${entry.method} ${entry.url} -> ${entry.status}`);
}

{
  "logs": [
    {
      "timestamp": "2024-03-10T08:15:30.123Z",
      "method": "GET",
      "url": "https://api.example.com/users/me",
      "status": 200,
      "resourceType": "fetch",
      "tabId": 0
    },
    {
      "timestamp": "2024-03-10T08:15:31.789Z",
      "method": "POST",
      "url": "https://api.example.com/events",
      "status": 204,
      "resourceType": "fetch",
      "tabId": 0
    }
  ],
  "count": 2
}

Browsing History

Query browsing history

GET /history

Returns paginated browsing history entries with optional filters. History is recorded for all navigations including API-triggered calls to /browse and manual page navigation. Reads from persistent storage (symlink directories).

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 (between 1 and 500). Default: `50`.
`offset`	query	integer	No	Number of entries to skip for pagination. Default: `0`.

curl "https://api.hoody.com/v1/browser/history?domain=example.com&limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

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

console.log(`Returned ${page.entries.length} of ${page.total}`);
if (page.has_more) {
  console.log("Fetch the next page by incrementing offset.");
}

{
  "entries": [
    {
      "id": "1709913600000-a3f2",
      "url": "https://example.com",
      "requestedUrl": "https://example.com",
      "title": "Example Domain",
      "domain": "example.com",
      "tabId": 0,
      "browserId": "0",
      "browserPort": 9223,
      "sessionId": "abc123def456",
      "httpStatus": 200,
      "error": null,
      "source": "api",
      "timestamp": "2024-03-10T08:15:30.000Z",
      "created": true,
      "reused": false
    }
  ],
  "total": 1,
  "has_more": false,
  "limit": 50,
  "offset": 0
}

Field	Type	Description
`entries`	array	Array of navigation records.
`total`	integer	Total matching entries (bounded for global queries).
`has_more`	boolean	Whether more entries exist beyond the current page.
`limit`	integer	The limit applied to this page.
`offset`	integer	The offset applied to this page.

{
  "error": "Invalid limit value",
  "code": "INVALID_PARAMETERS",
  "details": {
    "field": "limit"
  }
}

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

Delete browsing 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/v1/browser/history?before=2024-01-01T00:00:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY"

const result = await client.browser.history.clear({
  before: "2024-01-01T00:00:00Z"
});

console.log(`Deleted ${result.deleted} history entries`);

{
  "deleted": 5
}

{
  "error": "Invalid timestamp format",
  "code": "INVALID_PARAMETERS",
  "details": {
    "field": "before"
  }
}

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