---
title: "Query log"
method: POST
path: "/v1/logs/{log-name}/query"
tags: ["Logs"]
---

# Query log

`POST /v1/logs/{log-name}/query`

Execute a log query and return the requested page of records. Each request is
self-contained - there is no server-side query state to open or close.

All column filters are combined with AND; use a filter of type `set` to combine
conditions on the same column with OR. Filter and ordering column names are
validated against the log definition.

Numeric filter values for timestamp columns are UNIX timestamps (milliseconds
for columns of millisecond resolution). A string value is parsed as a timestamp
and accepts ISO 8601, a UNIX timestamp, a relative offset such as `-30m`, or `now`.

Records are returned as objects keyed by column name, with values typed according
to the column type: coded and integer columns as numbers, timestamps as ISO 8601
strings, everything else as strings. Detail columns are not included.

Paging is implemented by re-executing the query and skipping records, so a large
`offset` is expensive; `offset` + `limit` may not exceed 100000.

## Request body

- LogQueryRequest
  - `filters` LogColumnFilter[] — Column filters combined with AND
    - `column` string — Column to filter on. Required for top level filters, ignored for filters nested in a `set`.
    - `type` 'equals' | 'range' | 'set' | 'like' | 'less' | 'greater' | 'childOf' | 'relative' | 'currentPeriod', required — Filter type. `equals`, `less`, `greater`, and `range` require numeric values; `like` performs an SQL LIKE match (use `%` and `_` as wildcards, empty string matches empty and NULL values); `childOf` matches objects below the given object; `relative` matches a timestamp column within the last N units; `currentPeriod` matches a timestamp column within a calendar period in the client's time zone; `set` combines nested filters on the same column.
    - `negated` boolean — Invert the condition
    - `value` union — Value for `equals`, `less`, `greater`, `childOf` (object ID), `like` (pattern), and `relative` (number of units). String values on numeric columns are parsed as timestamps.
      - integer
      - string
    - `from` union — Lower bound (inclusive) for `range`
      - integer
      - string
    - `to` union — Upper bound (inclusive) for `range`
      - integer
      - string
    - `unit` 'minute' | 'hour' | 'day' | 'week' — Time unit for `relative`
    - `period` 'today' | 'yesterday' | 'thisWeek' | 'thisMonth' — Calendar period for `currentPeriod`
    - `timeZoneOffset` integer — Client UTC offset in seconds (east of UTC) used to resolve `currentPeriod` boundaries
    - `operation` 'and' | 'or' — Operation used to combine nested filters of a `set`
    - `filters` LogColumnFilter[] — Nested filters for `set`
  - `orderBy` object[] — Ordering columns, most significant first
    - `column` string, required — Column to sort by
    - `descending` boolean — Sort in descending order
  - `offset` integer — Number of records to skip
  - `limit` integer — Maximum number of records to return (1 to 10000; `offset` + `limit` may not exceed 100000)

## Response `200`

Query executed successfully

- LogQueryResult
  - `columns` LogColumn[] — Log column definitions (includes detail columns, which are not present in records)
    - `name` string — Column name as used in filters, ordering, and record objects
    - `description` string, nullable — Human readable column name
    - `type` 'text' | 'severity' | 'objectId' | 'userId' | 'eventCode' | 'timestamp' | 'integer' | 'alarmState' | 'alarmHelpdeskState' | 'zoneUIN' | 'eventOrigin' | 'textDetails' | 'jsonDetails' | 'completionStatus' | 'actionCode' | 'atmTransactionCode' | 'assetOperation' | 'deploymentStatus' | 'aiTaskStatus' | 'macAddress' | 'connectionEvent' | 'aiOperatorExecutionStatus' | 'observationState' | 'unknown' — Column data type. Values `timestamp` are returned as ISO 8601 strings, `text`, `textDetails`, and `macAddress` as strings, `jsonDetails` as a JSON document, and all other types as integers. Coded types (`severity`, `objectId`, `userId`, `eventCode`, `alarmState`, `alarmHelpdeskState`, `zoneUIN`, `eventOrigin`, `completionStatus`, `actionCode`, `atmTransactionCode`, `assetOperation`, `deploymentStatus`, `aiTaskStatus`, `connectionEvent`, `aiOperatorExecutionStatus`, `observationState`) carry NetXMS internal codes.
    - `recordId` boolean — Set to true if this column is a sequential record ID
    - `detail` boolean — Set to true if this column is only returned when reading a single record
  - `offset` integer — Number of records skipped
  - `count` integer — Number of records returned
  - `records` object[] — Log records as objects keyed by column name

## Other responses

- `400` — Missing request body, invalid filter definition, or invalid offset/limit
- `403` — Access denied (log has an access right requirement not held by the user)
- `404` — Unknown log name
- `500` — Database failure

---

[API](https://skmtc.net/netxms/apis/netxms-api.md) · [All operations](https://skmtc.net/netxms/apis/netxms-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/netxms/netxms-api/versions/14d93e5115dd/schema)