Get logs by filter

GetLogsByFilter¶

GetLogsByFilter

Description: Returns server audit log records in a table-oriented format. The method uses cursor-based streaming pagination and does not calculate the total row count by default. This avoids loading large log ranges into server memory.

This method does not use from and to. Time filtering is done through timestamp in where or whereBetween. If no timestamp filter is provided, the server scans the last 30 days of log files.

Access Control¶

🛡️ Access Level Required: SESSION_ADMIN, SESSION_MANAGER, or SESSION_DEALER

Manager permissions are resolved from the cached staff manager record. Non-admin managers require BackOffice access; token payload is used only for manager id and session type.

Request Parameters¶

Name	Type	Required	Description
limit	int	Yes	Maximum number of rows to return
offset	int	No	Legacy first-page skip. Prefer `cursor` for scrolling
cursor	object / null	No	Cursor returned by the previous response. Use `null` for the first page
where	array	No	Array of conditions in format `[field, operator, value]`
whereNot	array	No	Array of negative conditions in format `[field, value]`
whereIn	array	No	Array of inclusion conditions
whereNotIn	array	No	Array of exclusion conditions
whereBetween	array	No	Array of range conditions in format `[field, [from, to]]`
whereNotBetween	array	No	Array of negative range conditions
orderBy	array	No	Sorting rule. Cursor scan supports only `["timestamp", "ASC"]` or `["timestamp", "DESC"]`
grep	object	No	Streaming text search by one log field

Cursor¶

The first request should pass cursor: null or omit cursor. If the response contains has_more: true, send the returned cursor object unchanged in the next request.

Cursor Field	Type	Description
direction	string	Scan direction: `ASC` or `DESC`
query_hash	string	Hash of filters, grep, direction, and scan boundary
file	string	Internal log file name where the scan stopped
byte_offset	int64	Internal byte position where the next scan should continue
scan_until	int64	Fixed upper timestamp boundary for a stable scrolling session

The frontend should treat cursor fields as opaque technical state. Do not modify cursor values.

Grep Search¶

grep applies a streaming search after structured filters. It does not require loading the full result set into memory.

Name	Type	Required	Description
field	string	Yes	Field to search. `message` is accepted as an alias of `detail`
value	string	Yes	Search value
mode	string	No	`contains`, `equals`, `starts_with`, or `ends_with`. Default: `contains`
case_sensitive	bool	No	Case-sensitive search. Default: `false`

Example:

{
  "field": "message",
  "value": "backup",
  "mode": "contains",
  "case_sensitive": false
}

Supported Fields¶

The following log fields can be used in filters and grep:

timestamp
actor_type
actor_id
action
status
source
detail

message can be used as a grep/filter alias for detail.

Sorting is intentionally limited to timestamp ASC/DESC for cursor pagination. Sorting by text fields requires a full materialized result set or a dedicated index and is not supported by this method.

Response Structure¶

Field	Type	Description
timestamp	int64	Unix timestamp in seconds
actor_type	string	Actor category
actor_id	string	Actor identifier or `-`
action	string	Operation name
status	string	Operation status
source	string	Request origin, IP, plugin name, or module name
detail	string	Free-form payload or message

Request Example¶

First page:

{
  "limit": 50,
  "cursor": null,
  "where": [
    ["actor_type", "=", "MANAGER"],
    ["status", "=", "SUCCESS"]
  ],
  "whereBetween": [
    ["timestamp", [1713744000, 1713830399]]
  ],
  "whereNot": [
    ["source", "127.0.0.2"]
  ],
  "grep": {
    "field": "message",
    "value": "backup",
    "mode": "contains",
    "case_sensitive": false
  },
  "orderBy": ["timestamp", "DESC"]
}

{
  "limit": 50,
  "cursor": {
    "direction": "DESC",
    "query_hash": "8f9b1a28e674c901",
    "file": "2026-07-02.log",
    "byte_offset": 18374622,
    "scan_until": 1783001234
  },
  "where": [
    ["actor_type", "=", "MANAGER"],
    ["status", "=", "SUCCESS"]
  ],
  "whereBetween": [
    ["timestamp", [1713744000, 1713830399]]
  ],
  "grep": {
    "field": "message",
    "value": "backup",
    "mode": "contains",
    "case_sensitive": false
  },
  "orderBy": ["timestamp", "DESC"]
}

Response Example¶

{
  "structure": [
    "timestamp",
    "actor_type",
    "actor_id",
    "action",
    "status",
    "source",
    "detail"
  ],
  "rows": [
    [
      1713787200,
      "MANAGER",
      "1223",
      "AuthManager",
      "SUCCESS",
      "127.0.0.1",
      "{\"id\":1223}"
    ]
  ],
  "has_more": true,
  "cursor": {
    "direction": "DESC",
    "query_hash": "8f9b1a28e674c901",
    "file": "2026-07-02.log",
    "byte_offset": 18374622,
    "scan_until": 1783001234
  }
}

Last page:

{
  "structure": [
    "timestamp",
    "actor_type",
    "actor_id",
    "action",
    "status",
    "source",
    "detail"
  ],
  "rows": [],
  "has_more": false,
  "cursor": null
}

Frontend Usage Recommendations¶

Use infinite scroll with cursor, not page numbers.
For the first request, send cursor: null.
Keep the same filters, grep, and orderBy while scrolling. If any filter changes, discard the old cursor and start again with cursor: null.
Stop requesting more data when has_more is false.
Do not rely on count or total; this method does not return them in the normal scrolling flow.
Prefer an explicit whereBetween by timestamp for large installations. Without it, the server scans the last 30 days.
Use orderBy: ["timestamp", "DESC"] for the default newest-first journal view.
Debounce text search before sending grep requests from the UI.
Treat the cursor object as opaque state. Store and resend it unchanged.
If the server returns INVALID_DATA for cursor mismatch, reset cursor to null and reload the list.

Notes¶

limit is applied during streaming scan.
offset is kept only as a legacy first-page skip. Cursor pagination is recommended.
count and total are intentionally not returned by this method to avoid expensive full-range scans.
If no timestamp filter is provided, the server scans the last 30 days of log files.
Only timestamp sorting is supported: ["timestamp", "ASC"] or ["timestamp", "DESC"].
GetLogs remains available for simple field-based filtering; GetLogsByFilter is intended for table-style admin views.