tencent cloud

APIs

DocumentationAPIsCloud Log ServiceLog APIsSearchLog

SearchLog

Download
Focus Mode
Font Size
Last updated: 2026-06-10 15:01:41

1. API Description

Domain name for API request: cls.intl.tencentcloudapi.com.

This API is used to retrieve and analyze logs. Please note the following matters when using this API.

  1. Besides being subject to the default API request rate limit, for a single log topic, the number of concurrent queries cannot exceed 15.
  2. The API's return data packet maximum is 49MB. It is recommended to enable gzip compression (HTTP Request Header Accept-Encoding: gzip).

A maximum of 10000 requests can be initiated per second for this API.

This action accepts http content encodings: gzip

We recommend you to use API Explorer
Try it
API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.

2. Input Parameters

The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.

Parameter Name Required Type Description
Action Yes String Common Params. The value used for this API: SearchLog.
Version Yes String Common Params. The value used for this API: 2020-10-16.
Region Yes String Common Params. For more information, please see the list of regions supported by the product.
From Yes Integer

Start time for logs to be searched and analyzed, Unix timestamp (ms)
To Yes Integer

End time for logs to be searched and analyzed, Unix timestamp (ms)
QueryString No String

The retrieval analysis statement has a maximum length of 12KB.
The statement consists of [retrieval condition]
QuerySyntax No Integer

Search syntax rules. Default value is 1. Recommended for use is 1.

  • 0: Lucene syntax
  • 1: CQL syntax (CLS Query Language, dedicated retrieval syntax for log service)

For details, see retrieval condition syntax rules.

Default value: 1
TopicId No String
  • Log topic ID to be retrieved and analyzed. Only one can be specified.
  • If needed to retrieve multiple log topics at the same time, please use the Topics parameter.
  • TopicId and Topics cannot include both. Only select one in a single request.
Topics.N No Array of MultiTopicSearchInformation
  • Log topic list for retrieval and analysis supports a maximum of 50 log topics.
  • Use TopicId to retrieve a single log topic.
  • TopicId and Topics cannot be used simultaneously. Only select one in a single request.
Sort No String

Whether raw logs are returned in time sequence. Value range: asc (ascending), desc (descending). Default is desc.
Note:

  • Only valid when the search and analysis statement (Query) does not contain SQL.
  • For SQL result sorting, see SQL ORDER BY syntax.
Limit No Integer

Number of raw logs returned in a single query. Default is 100, maximum value is 1000.
Note:

  • Only valid when the search and analysis statement (Query) does not contain SQL.
  • For the method for specifying SQL result count, see SQL LIMIT syntax.

There are two methods to retrieve more logs:

  • Context: Pass the Context value returned by the last API call to retrieve more logs. The total number of raw logs that can be obtained is up to 10,000 entries.
  • Offset: The offset refers to the line number from which raw logs start to return. There is no log entry limit.
Offset No Integer

Offset of the raw log Query, indicating the line number from which the raw log starts to return, defaults to 0.
Note:

  • Valid only when the retrieval statement (Query) does not contain SQL
  • Cannot be used with Context parameter simultaneously
  • Applicable only for single log topic retrieval
Context No String

Pass the Context value returned by the last API call to obtain more logs later. The total number of raw logs that can be retrieved is up to 10,000 entries, with an expiration time of 1 hour.
Note:

  • When passing this parameter, do not modify other parameters except this one.
  • Applicable only for single log topic retrieval. To retrieve multiple log topics, use the Context in Topics.
  • Valid only when the search and analysis statement (Query) does not contain SQL. For SQL to obtain follow-up results, see SQL LIMIT syntax.
SamplingRate No Float

Whether to sample raw logs first and then perform statistical analysis when executing statistical analysis (SQL included in Query).
0: auto-sample;
0–1: sample at the specified sampling rate, such as 0.02;
1: indicates no sampling, that is, precise analysis.
The default value is 1.
UseNewAnalysis No Boolean

true means using the new retrieval result return method, and output parameters AnalysisRecords and Columns are valid.
false means using the old retrieval result return method, and output AnalysisResults and ColNames are valid.
There is a slight difference in encoding format between the two return methods. Recommend using true.
HighLight No Boolean

Whether to highlight keywords that meet retrieval criteria, generally used for highlighting. Only key-value retrieval is supported, full-text retrieval is not supported.

3. Output Parameters

Parameter Name Type Description
Context String

Pass through the Context value returned by this API to obtain more logs later. The expiration time is 1 hour.
Note:

  • Applicable only for single log topic retrieval. To retrieve multiple log topics, use the Context in Topics.
ListOver Boolean

Whether all logs meeting the retrieval criteria have been returned. If not, use Context parameter to retrieve more logs.
Note: This is only valid when the search and analysis statement (Query) does not contain SQL.
Analysis Boolean

Whether the returned data is the SQL analysis result
Results Array of LogInfo

Raw logs matching the retrieval criteria


Note: This field may return null, indicating that no valid values can be obtained.
ColNames Array of String

Column names of log statistics analysis results
This parameter is valid only when UseNewAnalysis is false


Note: This field may return null, indicating that no valid values can be obtained.
AnalysisResults Array of LogItems

Statistical analysis results of logs
This parameter is valid only when UseNewAnalysis is false


Note: This field may return null, indicating that no valid values can be obtained.
AnalysisRecords Array of String

Log statistics and analysis results
This parameter is valid only when UseNewAnalysis is true


Note: This field may return null, indicating that no valid values can be obtained.
Columns Array of Column

Column attribute of log statistics and analysis results
This parameter is valid only when UseNewAnalysis is true


Note: This field may return null, indicating that no valid values can be obtained.
SamplingRate Float

Sampling rate used in this analysis
Topics SearchLogTopics

When multiple log topics are used for retrieval, basic information of each log topic, such as error message.


Note: This field may return null, indicating that no valid values can be obtained.
RequestId String The unique request ID, generated by the server, will be returned for every request (if the request fails to reach the server for other reasons, the request will not obtain a RequestId). RequestId is required for locating a problem.

4. Example

Example1 Querying Logs

This example shows you how to query the logs with HTTP response status code (http_code) of 200.

Input Example

POST / HTTP/1.1
Host: cls.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: SearchLog
<Common request parameters>

{
    "TopicId": "601c2a87-ca8e-49c9-xxxx-27286a970db5",
    "From": 1679901909686,
    "To": 1679902809686,
    "QueryString": "http_code:\"200\"",
    "Limit": 1,
    "Sort": "desc",
    "HighLight": true,
    "UseNewAnalysis": true,
    "QuerySyntax": 1
}

Output Example

{
    "Response": {
        "Context": "Y29udGV4dC0zZDVmZGI2NC1jNDZkLTQ2NzktYWM2OC1jYzg2NjUxYmVlMWExNjc5OTAyODEwNDM0",
        "ListOver": false,
        "Analysis": false,
        "ColNames": [],
        "Columns": null,
        "Results": [
            {
                "Time": 1679902806070,
                "TopicId": "601c2a87-ca8e-49c9-xxxx-27286a970db5",
                "TopicName": "CDN Demo access log log topic _10000100xxxx",
                "Source": "",
                "FileName": "",
                "HostName": "",
                "PkgId": "",
                "PkgLogId": "",
                "HighLights": [],
                "LogJson": "{\"referer\":\"http://qwunsag.2022.qq.com/prizes?activity_code=AVGCHaQFX02Eb\",\"method\":\"GET\",\"isp\":\"China Unicom\",\"remote_port\":\"45088\",\"ua\":\"Mozilla/5.0 (Linux; Android 9; INE-AL00 Build/HUAWEIINE-AL00; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/86.0.4240.99 XWEB/3211 MMWEBSDK/20210601 Mobile Safari/537.36 MMWEBID/6389 MicroMessenger/8.0.11.1980(0x28000B5B) Process/toolsmp WeChat/arm64 Weixin NetType/WIFI Language/zh_CN ABI/arm64\",\"uuid\":\"acf1010c853f4a24bb3e92cc34e283e2\",\"version\":\"1\",\"file_size\":\"186358\",\"url\":\"/loxtxt/979884858.png\",\"request_range\":\"-\",\"rsp_size\":\"186830\",\"hit\":\"hit\",\"request_time\":\"2808\",\"http_code\":\"200\",\"param\":\"-\",\"sys_address\":\"9.130.154.208\",\"proto\":\"HTTPS\",\"host\":\"test.2022.cls.cn\",\"sys_datasource\":\"cq.3.4.v1.2.17\",\"client_ip\":\"116.116.247.167\",\"time\":\"1679902806070\",\"app_id\":\"1302700768\",\"prov\":\"Inner Mongolia Autonomous Region\",\"timestamp\":\"2023-03-27T15:40:06+08:00\"}",
                "RawLog": "",
                "IndexStatus": ""
            }
        ],
        "AnalysisResults": [],
        "AnalysisRecords": null,
        "RequestId": "79f593e5-1374-4463-xxxx-c49d0b3c5290",
        "SamplingRate": 0,
        "Topics": null
    }
}

5. Developer Resources

SDK

TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.

Command Line Interface

6. Error Code

The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.

Error Code Description
FailedOperation Operation failed.
FailedOperation.InvalidContext The search cursor is invalid or does not exist.
FailedOperation.QueryError The query statement failed to run.
FailedOperation.SearchTimeout The query timed out.
FailedOperation.SyntaxError An error occurred while parsing the query statement.
FailedOperation.Timeout Operation timed out
FailedOperation.TopicIsolated The log topic has been isolated.
InternalError Internal error.
InternalError.SearchError Retrieval error
InternalError.SearchFailed Retrieval failed
InternalError.ServerBusy Internal error server busy
InvalidParameter Incorrect parameter.
LimitExceeded.LogSearch The number of concurrent queries exceeds the limit, which is 15 per topic.
LimitExceeded.SearchResources Out of search memory.
LimitExceeded.SearchResultTooLarge The number of logs returned by the search API exceeds the upper limit (20 MB).
MissingParameter Missing parameter.
OperationDenied Operation denied.
OperationDenied.AccountDestroy The account has been terminated.
OperationDenied.AccountIsolate The account has overdue payments.
OperationDenied.AccountNotExists The account does not exist.
OperationDenied.NewSyntaxNotSupported New syntax is not supported.
OperationDenied.OperationNotSupportInSearchLow The operation is not supported in IA storage.
ResourceNotFound.TopicNotExist The log topic does not exist.
Previous Topic: DescribeMachineGroupConfigsNext Topic: DescribeLogHistogram

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback