Logs API Payload Model

The SigNoz Logs API uses a JSON payload for queries, which includes various fields and nested fields. This document provides a detailed explanation of each field to help users construct effective queries.


The top-level of the payload model has the following fields:

startEpoch timestamp marking the start of the query range (in milliseconds or nanoseconds)
endEpoch timestamp marking the end of the query range (in milliseconds or nanoseconds)
stepAggregation interval for the query, specified in seconds
compositeQueryThis contains the compositeQuery which is explained below

Composite Query

The compositeQuery field consists of:

queryTypeType of query (e.g., builder, clickhouse, prometheus).Scope of this documentation is limited to builder type
panelTypeType of panel (e.g., list, graph, table)
offsetOffset used in pagination
pageSizeNumber of items to fetch, used in list view
limitFor list view: - Maximum number of items to be paginate, i.e., offset + pageSize cannot exceed limit, For aggregation:- limit on the results
builderQueriesMap of builderQuery

Builder Query

A builderQuery consists of:

stepIntervalAggregation interval for query in seconds
queryNameName of the query, should match the key to this map value
dataSourceSource of data, e.g., logs
aggregateOperatorType of aggregation - noop, count, count_distinct, sum, avg, min, max, p05, p10, p20, p25, p50, p75, p90, p95, p99, rate, sum_rate, avg_rate, min_rate, max_rate, rate_sum, rate_avg, rate_min, rate_max
aggregateAttributeThe attribute against which the aggregateOperator is applied
filtersArray of filter used for filtering data
groupByArray of attribute used for groupBy
expressionWill be same as query name but different in case of formulas
disabledSpecifies if the query is disabled


A filter consists of:

itemsArray of filterItem
opOperator defining how filter items are joined (e.g., AND).

Filter Item

The filterItem includes:

keyCorresponding attribute
opOperators - =, !=, >, >=, <, <=, in, nin, contains, ncontains, regex, nregex, like, nlike, exists, nexists, has, nhas
valueValue for the filter, can be empty for some op
📝 Note

The value parameter will be empty for exists and nexists.


An attribute consists of:

keyName of the key
typeType of the key, i.e., tag/resource. It is empty for top level fields. (e.g., tag = method, resource = k8s_deployment_name, (empty) = trace_id)
dataTypeData type of the key (e.g., string, int64, float64, bool)
isColumnIndicates if it has a materialized column, i.e., selected field
isJsonSpecifies if the key is a JSON key

Sample Payload

This sample payload contains the different fields that we looked at above. It queries the SigNoz Logs API and illustrates how to count distinct component values and group them by container_id.

    "start": 1700734490000,
    "end": 1700738090000,
    "step": 60,
    "variables": {},
    "compositeQuery": {
        "queryType": "builder",
        "panelType": "table",
        "builderQueries": {
            "A": {
                "dataSource": "logs",
                "queryName": "A",
                "aggregateOperator": "count_distinct",
                "aggregateAttribute": {
                    "key": "component",
                    "dataType": "string",
                    "type": "tag",
                    "isColumn": false
                "filters": {
                    "items": [],
                    "op": "AND"
                "expression": "A",
                "disabled": false,
                "stepInterval": 60,
                "orderBy": [
                        "columnName": "timestamp",
                        "order": "desc"
                "groupBy": [
                        "key": "container_id",
                        "dataType": "string",
                        "type": "tag",
                        "isColumn": true,
                        "isJSON": false
                "offset": 0