Histogram API QueryLogHistogram

Updated at：2025-11-03

Description

Users can analyze data using statistical histograms by submitting query search statements. Note that only one logstore can be queried at a time.

Query statements support three formats, such as:

match search statement: return the log histogram statistics that meets search conditions
SQL statement: return the histogram statistics of all logs
match search statement | SQL statement: according to search conditions, return th log histogram statistics query that meet search conditions Query related restrictions are as follows:

Index must be enabled on the logstore; otherwise, the histogram query will return an error
The maximum query time is 60 seconds; an error is returned if no statistic result is obtained over 60 seconds.

For search syntax, please refer to Search Syntax

Request

Request syntax

Plain Text

1GET /v2/logstore/{logStoreName}/loghistogram?project={project} HTTP/1.1
2Host: <Endpoint>
3Authorization: <Authorization String>

Request headers

No additional headers are required beyond the standard request headers.

Request parameters

Parameter name	Types	Required or not	Parameter location	Description
project	String	No	Query	Project name
logStoreName	String	Yes	Path	Logstore name
logStreamName	String	No	Query	Logstream name
query	String	Yes	Query	Input Query statement
startDateTime	DateTime	Yes	Query	Start datetime, UTC format, including start time
endDateTime	DateTime	Yes	Query	End datetime, UT format, excluding end time

Note: The datetime is in UTC ISO8601 format, for example: 2020-01-10T13:23:34Z; the ranges of startDateTime and endDateTime restrict the logrecord timestamp

Response

Response headers

No additional headers are required beyond the standard response headers.

Response parameters

Parameter name	Types	Required or not	Description
searchInfo	Object	Yes	Search summary information
searchStatistic	Object	Yes	Histogram statistics

Therein, searchInfo includes the queried search summary information, structured as follows:

Parameter name	Types	Required or not	Description
queryType	string	Yes	Returned statement type, match: search statement; sql: analysis statement; match_and_sql: include search and analysis statements
took	Int	Yes	Statistics duration, unit: millisecond
hits	Int	Yes	Total number of matched logs

searchStatistic includes the histogram statistic information queried this time, structured as follows:

Parameter name	Types	Required or not	Description
interval	Int	Yes	Single interval size of histogram statistics, milliseconds in the interval
startTime	DateTime	Yes	Start time of histogram statistics, namely startDateTime in the request
endTime	DateTime	Yes	End time of histogram statistics, namely endDateTime in the request
histogram	List<Bucket>	Yes	Histogram counts the number of data in each interval, and is divided and arranged sequentially by interval size, showing the number of logs in each time interval.

Note: All datetimes are in UTC ISO8601 format, for example: 2020-01-10T13:23:34Z

Therein, bucket includes the number of data in an interval of histogram statistics, structured as follows:

Parameter name	Types	Required or not	Description
key	Int	Yes	Start timestamp of time interval: the first timestamp of histogram is determined by rounding down the startDateTime to the nearest interval, and the last timestamp is obtained by rounding down the endDateTime to the nearest interval. The histogram bins are uniformly divided, and the counting includes the start boundary but excludes the end boundary, i.e., count [start, end)
doc_count	Int	Yes	Number of files in the time interval

Error code

Apart from standard error codes, the following codes may be returned:

Error code	Error message	Description	HTTP status code
QueryParseError	[msg]	msg indicates the specific error content	400
InvalidParameter	Request param invalid: [param]	param indicates the error parameter	400
LogStoreStopped	LogStore stopped	LogStore write operations blocked due to debt	403
LogStoreNotFound	LogStore not found	LogStore not found	404
ExecutionTimeout	[msg]	msg indicates the specific error content	408
LogStoreNotReady	LogStore not ready	LogStore in initialization	409

Example

Request example

Text

1GET /v2/logstore/demo/loghistogram?project=default&logStreamName=my-stream&startDateTime=2019-09-01T22:00:00Z&endDateTime=2019-09-01T23:00:00Z&query=match * HTTP/1.1
2Host: bls-log.bj.baidubce.com
3Authorization: bce-auth-v1/18717522d39411e9b721df098b0b908c/2019-09-10T07:00:20Z/1800/content-type;host;x-bce-date;x-bce-request-id/6a7cb6c9ac7ec156c805e55e7d0bcfc443b47feee97cf099c1c0d93a0b4c8304
4Content-Type: application/json; charset=utf-8

Response example