Log Management

The Log Management API provides endpoints to list, read, stream, search, and clear execution logs produced by Hoody agents. Use these endpoints to inspect agent output, tail logs in real time, query historical log files, and reclaim storage by removing old entries.

List Logs

GET /api/v1/exec/logs/list

Returns the available log files or entries. Supports optional filtering by log type and result count.

Parameters

Name	In	Type	Required	Description
`type`	query	string	No	Type query parameter
`limit`	query	string	No	Limit query parameter

Request Example

This endpoint accepts no request body.

Response

{
  "logs": [
    "exec-2025-01-15-001.log",
    "exec-2025-01-15-002.log",
    "exec-2025-01-15-003.log"
  ],
  "count": 3
}

{
  "error": "VALIDATION_ERROR",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-15T14:32:11.482Z"
}

Error Code	Title	Description	Resolution
`VALIDATION_ERROR`	Invalid input	Request parameters failed validation	Check parameter format and requirements

{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T14:32:11.482Z"
}

SDK Usage

const result = await client.exec.logs.list({
  type: "execution",
  limit: "50"
});

Stream Logs

GET /api/v1/exec/logs/stream

Streams the contents of a log file, optionally following new lines as they are written (similar to tail -f).

Parameters

Name	In	Type	Required	Description
`file`	query	string	Yes	File query parameter
`follow`	query	string	No	Follow query parameter

Request Example

This endpoint accepts no request body.

Response

{
  "error": "VALIDATION_ERROR",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-15T14:32:11.482Z"
}

Error Code	Title	Description	Resolution
`VALIDATION_ERROR`	Invalid input	Request parameters failed validation	Check parameter format and requirements

{
  "error": "Resource not found",
  "code": "NOT_FOUND",
  "timestamp": "2025-01-15T14:32:11.482Z"
}

Error Code	Title	Description	Resolution
`NOT_FOUND`	Resource not found	The requested resource does not exist	Verify the resource identifier

{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T14:32:11.482Z"
}

SDK Usage

const stream = await client.exec.logs.stream({
  file: "exec-2025-01-15-001.log",
  follow: "true"
});

Read Log

POST /api/v1/exec/logs/read

Reads lines from a log file with support for tailing, line limits, and text search.

Request Body

Name	Type	Required	Default	Description
`file`	string	No	—	File
`executionId`	string	No	—	Execution Id
`lines`	integer	No	`100`	Lines
`tail`	boolean	No	`true`	Tail
`search`	string	No	—	Search

{
  "file": "exec-2025-01-15-001.log",
  "executionId": "exec_8f3a2b1c9d4e5f6a",
  "lines": 200,
  "tail": true,
  "search": "ERROR"
}

Response

{
  "file": "exec-2025-01-15-001.log",
  "totalLines": 1024,
  "filteredLines": 12,
  "returnedLines": 12,
  "lines": [
    "2025-01-15T14:00:01.000Z [ERROR] Connection refused to upstream service",
    "2025-01-15T14:00:02.140Z [ERROR] Retry attempt 1 failed",
    "2025-01-15T14:00:03.512Z [ERROR] Retry attempt 2 failed"
  ],
  "size": 1048576,
  "modified": "2025-01-15T14:30:00.000Z"
}

{
  "error": "VALIDATION_ERROR",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-15T14:32:11.482Z"
}

Error Code	Title	Description	Resolution
`VALIDATION_ERROR`	Invalid input	Request parameters failed validation	Check parameter format and requirements

{
  "error": "Resource not found",
  "code": "NOT_FOUND",
  "timestamp": "2025-01-15T14:32:11.482Z"
}

Error Code	Title	Description	Resolution
`NOT_FOUND`	Resource not found	The requested resource does not exist	Verify the resource identifier

{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T14:32:11.482Z"
}

SDK Usage

const log = await client.exec.logs.read({
  file: "exec-2025-01-15-001.log",
  lines: 200,
  tail: true,
  search: "ERROR"
});

Search Logs

POST /api/v1/exec/logs/search

Searches across one or more log files using either a plain-text query or a regular expression.

Request Body

Name	Type	Required	Default	Description
`query`	string	No	—	Query
`regex`	string	No	—	Regex
`files`	array	No	—	Files
`limit`	integer	No	`1000`	Limit
`caseSensitive`	boolean	No	`false`	Case Sensitive

{
  "query": "timeout",
  "files": ["exec-2025-01-15-001.log", "exec-2025-01-15-002.log"],
  "limit": 500,
  "caseSensitive": false
}

Response

{
  "query": "timeout",
  "searchType": "text",
  "filesSearched": 2,
  "matchesFound": 7,
  "results": [
    {
      "file": "exec-2025-01-15-001.log",
      "line": 142,
      "content": "2025-01-15T13:42:18.221Z [WARN] Request timeout after 30s",
      "timestamp": "2025-01-15T13:42:18.221Z"
    }
  ]
}

{
  "error": "VALIDATION_ERROR",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-15T14:32:11.482Z"
}

Error Code	Title	Description	Resolution
`VALIDATION_ERROR`	Invalid input	Request parameters failed validation	Check parameter format and requirements

{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T14:32:11.482Z"
}

SDK Usage

const matches = await client.exec.logs.search({
  query: "timeout",
  files: ["exec-2025-01-15-001.log", "exec-2025-01-15-002.log"],
  limit: 500,
  caseSensitive: false
});

Clear Logs

DELETE /api/v1/exec/logs/clear

Deletes log files. Supports targeting a single file, filtering by type, removing entries older than a specified number of days, and requires an explicit confirmation flag.

Parameters

Name	In	Type	Required	Description
`file`	query	string	No	File query parameter
`type`	query	string	No	Type query parameter
`olderThanDays`	query	string	No	OlderThanDays query parameter
`confirm`	query	string	No	Confirm query parameter

Request Example

This endpoint accepts no request body.

Response

{
  "deleted": 14,
  "totalSize": 15728640,
  "message": "Successfully deleted 14 log files (15.73 MB)"
}

{
  "error": "VALIDATION_ERROR",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-15T14:32:11.482Z"
}

Error Code	Title	Description	Resolution
`VALIDATION_ERROR`	Invalid input	Request parameters failed validation	Check parameter format and requirements

{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T14:32:11.482Z"
}

SDK Usage

const result = await client.exec.logs.clear({
  olderThanDays: "30",
  confirm: "true"
});