---
title: "System Logs API"
canonical_url: "https://ainode.run/docs/logs"
type: "doc"
locale: "en"
description: "Endpoints for managing and retrieving application event logs."
---

# System Logs API
> Endpoints for managing and retrieving application event logs.

This section describes the API endpoints for managing and retrieving system event logs. These endpoints require administrator authentication.

## Admin Endpoints (Requires Authentication)

### List Logs

Retrieve a paginated list of system logs.

**Endpoint:** `GET /api/admin/logs`

**Query Parameters:**

- `page` (optional): The page number to retrieve. Defaults to `1`.
- `pageSize` (optional): The number of logs per page. Defaults to `50`.
- `search` (optional): Search the message and details for a request ID, error message or pathname (up to 200 characters). Pagination applies to the filtered results. `page` is at least `1`; `pageSize` is clamped to `1–100`.

**Response:**

```json
{
  "logs": [
    {
      "id": 1,
      "level": "error",
      "message": "Payment gateway timeout",
      "details": "{\"error\": \"Connection refused\", \"gateway\": \"stripe\"}",
      "source": "payment",
      "createdAt": "2024-01-01T12:00:00.000Z"
    }
  ],
  "total": 150,
  "page": 1,
  "pageSize": 50
}
```

## Diagnosing HTTP 5xx and runtime errors

Every request receives a generated `x-request-id` response header. Error JSON also contains `requestId`; object-valued `data` includes the same ID while preserving business error fields. A 5xx message includes `[requestId]`, so existing API error notifications can display it. Fatal/unhandled messages remain sanitized in production. HTML 500/503 pages show a copyable request ID, path and build version; development additionally shows the error stack.

Open **Admin → Logs → System** and search for this ID, or use `GET /api/admin/logs?search=`. HTTP 5xx records use source `http-error`; failures without an HTTP event use `runtime-error`. Details include UTC time, build ID, method, pathname, status, duration, user ID (when available), stack and a bounded cause chain. The detail dialog renders stacks and causes on separate lines. These records reuse the existing logs table and administrator permissions; no schema migration is needed.

Evidence is also written to the server console (`[api-error]`) and, on Node deployments, `${APAY_DATA_DIR:-.data}/logs/api-errors.jsonl`, with a 5 MiB rotation threshold. File writes are asynchronous so a busy disk does not stall other requests. Page 404s (non-`/api` paths, mostly crawler probes) are not recorded; API 404s still are. Console/file logging runs before database logging, so database outages remain diagnosable. Edge deployments use platform console logs rather than local files. Request bodies, cookies, headers and query strings are not recorded; URL credentials and query strings, SQL parameter lines and common credential assignments in error messages are redacted. Treat remaining diagnostics as administrator-only data.

Server source maps are bundled with the server; retain server `.map` files when packaging. Start Node with `node --enable-source-maps .output/server/index.mjs` (or add `--enable-source-maps` to `NODE_OPTIONS`) to map even modules loaded before the error plugin initializes. The plugin enables mapping for subsequently loaded modules as a fallback. [Node source-map behavior](https://nodejs.org/docs/latest-v24.x/api/process.html#processsetsourcemapsenabledval). Client source maps remain disabled. Logging failures never change the original HTTP outcome. Rollback is a code rollback; there are no data migrations or business retries. Import/startup failures before plugins initialize and errors swallowed inside business code still require process/platform logs. Browser-only failures are visible in the development console, but are not uploaded to the server.

### Delete a Log

Delete a specific log entry by its ID.

**Endpoint:** `DELETE /api/admin/logs/:id`

**Response:**

```json
{
  "success": true
}
```

### Clear All Logs

Permanently delete all system logs.

**Endpoint:** `DELETE /api/admin/logs/clear`

**Response:**

```json
{
  "success": true,
  "message": "All logs cleared successfully"
}
```
