# Log Management

**Page:** api/exec/logs

[Download Raw Markdown](./api/exec/logs.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



# 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



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


```json
{
  "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 |


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



### SDK Usage

```ts
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



```json
{
  "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 |


```json
{
  "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 |


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



### SDK Usage

```ts
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 |

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

### Response



```json
{
  "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"
}
```


```json
{
  "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 |


```json
{
  "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 |


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



### SDK Usage

```ts
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 |

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

### Response



```json
{
  "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"
    }
  ]
}
```


```json
{
  "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 |


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



### SDK Usage

```ts
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



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


```json
{
  "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 |


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



### SDK Usage

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


The clear operation permanently removes log files. The `confirm` parameter should be set to `"true"` to acknowledge destructive intent and prevent accidental data loss.