Trace API Payload Model

The SigNoz Trace 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)
endEpoch timestamp marking the end of the query range (in milliseconds)
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, trace, value)
offsetOffset used in pagination
limitLimit number of 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., traces
aggregateOperatorType of aggregation - noop, count, count_distinct, sum, avg, min, max, p05, p10, p20, p25, p50, p75, p90, p95, p99, rate, rate_sum, rate_avg, rate_min, rate_max
aggregateAttributeThe attribute against which the aggregateOperator is applied
filtersArray of filter used for filtering data
selectColumnsArray of attribute which is used in list panelType to fetch columns/attributes of list
groupByArray of attribute used for groupBy
orderByArray of orderBy used for ordering data
havingArray of having used for filtering data after aggregation
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
valueValue for the filter, can be empty for some op like exists and nexists
📝 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's column, i.e., it would be faster to query using this attribute

Order By

An orderBy consists of:

columnNameName of the attribute/key
orderOrder of the column (e.g., asc, desc)


A having consists of:

columnNameName of the attribute/key along with aggregate operator (e.g., COUNT(httpMethod))
opOperators - =, !=, >, >=, <, <=
valueValue for the filter

Sample Payload

This sample payload contains the different fields that we looked at above. It queries the SigNoz Trace API and illustrates how to count distinct hasError values and group them by serviceName where hasError is true.

    "start": 1702007766000,
    "end": 1702009566000,
    "step": 60,
    "variables": {},
    "compositeQuery": {
        "queryType": "builder",
        "panelType": "table",
        "builderQueries": {
            "A": {
                "dataSource": "traces",
                "queryName": "A",
                "aggregateOperator": "count",
                "aggregateAttribute": {
                    "key": "hasError",
                    "dataType": "bool",
                    "type": "tag",
                    "isColumn": true
                "filters": {
                    "items": [
                            "key": {
                                "key": "hasError",
                                "dataType": "bool",
                                "type": "tag",
                                "isColumn": true
                            "op": "=",
                            "value": "true"
                    "op": "AND"
                "expression": "A",
                "disabled": false,
                "having": [],
                "stepInterval": 60,
                "limit": null,
                "orderBy": [
                        "columnName": "timestamp",
                        "order": "desc"
                "groupBy": [
                        "key": "serviceName",
                        "dataType": "string",
                        "type": "tag",
                        "isColumn": true
                "legend": "",
                "reduceTo": "sum"
    "dataSource": "traces"