tencent cloud

APIs

DokumentasiAPIsTencent Cloud FirewallLog APIsSearchLog

SearchLog

Download
Mode fokus
Ukuran font
Terakhir diperbarui: 2026-08-04 10:51:32

1. API Description

Domain name for API request: cfw.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 must not exceed 15.
  2. For search syntax, it's recommended to use the dedicated CQL syntax rule for log service. Please use the SyntaxRule parameter and set its value to 1. The console uses this syntax rule by default.
  3. 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 20 requests can be initiated per second for this API.

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: 2019-09-04.
Region No String Common Params. This parameter is not required for this API.
From Yes Integer

Start time for logs to be searched and analyzed, which is a Unix timestamp in milliseconds
To Yes Integer

End time for logs to be searched and analyzed, which is a Unix timestamp in milliseconds
Query Yes String

The retrieval and analysis statement has a maximum length of 12 KB.
The statement consists of [retrieval condition] | [SQL statement]. When there is no need to perform statistical analysis on logs, the pipe character | and the SQL statement can be omitted.
Use * or an empty string to search all logs.
SyntaxRule No Integer

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

  • 0: Lucene syntax
  • 1: CQL syntax (dedicated retrieval syntax for CLS, also the default syntax rule used in the console).

For details, see Retrieval condition syntax rules
TopicId No String
  • Log topic ID to be retrieved and analyzed. Only one log topic can be specified.
  • If needed, use the Topics parameter to retrieve multiple log topics.
  • The TopicId and Topics parameters cannot be used simultaneously. Only one can be selected in a single request.
    The log topic IDs are as follows:
    Access control - Internet boundary: cfw_rule_acl
    Access control - NAT boundary: cfw_rule_nat_acl
    Access control - VPC boundary: cfw_rule_vpc_acl
    Access control - DNS switch: cfw_rule_dns_acl
    Intrusion defense: cfw_rule_threatinfo
    Full traffic detection and response logs - Traffic analysis: cfw_netflow_nta
    Full traffic detection and response logs - Traffic alarm: cfw_rule_ndr_threatinfo
    Zero trust operations and maintenance - Database logon: cfw_operate_db
    Zero trust operations and maintenance - Server access: operate_remote_om
    Zero trust operations and maintenance - Web service access: operate_web_access
    Zero trust operations and maintenance - Behavioral audit: remoteom_commands
    Traffic log - Internet boundary: cfw_netflow_border
    Traffic log - NAT boundary: cfw_netflow_nat
    Traffic log - VPC boundary: cfw_netflow_vpc
    Traffic log - DNS switch: cfw_netflow_dns
    Traffic log - Private network traffic: cfw_netflow_fl
    Operation log: operate_log_all
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:

  • Valid only when the search and analysis statement (Query) does not contain SQL
  • For SQL result sorting, refer to SQL ORDER BY syntax
Limit No Integer

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

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

You can retrieve more logs in two ways:

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

Query the offset of raw logs, indicating the line number from which to start returning raw logs. Default value is 0.
Note:

  • Applicable only when the retrieval and analysis statement (Query) does not contain SQL.
  • Cannot be used with the Context parameter.
  • 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 obtained is up to 10,000 entries. The expiration time is 1 hour.
Note:

  • When passing this parameter, do not modify other parameters.
  • Applicable only for single log topic retrieval. To retrieve multiple log topics, use the Context in Topics.
  • This is valid only when the search and analysis statement (Query) does not contain SQL. For obtaining subsequent results with SQL, refer to SQL LIMIT syntax.
SamplingRate No Float

When performing statistical analysis (SQL included in Query), whether to sample raw logs first and then perform statistical analysis.
0: Automatic sampling;
0–1: Sample at the specified sampling rate, for example 0.02;
1: Indicates no sampling, that is, precision analysis.
Default value: 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 parameters AnalysisResults and ColNames are valid.
The two return methods have a slight difference in encoding format. It is recommended to use true.

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

Log statistics and 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.
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 the statistical analysis result
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 for this statistical analysis


Note: This field may return null, indicating that no valid values can be obtained.
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

Query logs with the HTTP protocol

Input Example

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

{
    "TopicId": "cfw_netflow_border",
    "From": 1782131614167,
    "To": 1782736414167,
    "Query": "protocol:HTTP",
    "SamplingRate": 1,
    "SyntaxRule": 1,
    "Limit": 1,
    "Context": "",
    "Sort": "desc",
    "UseNewAnalysis": true
}

Output Example

{
    "Response": {
        "Analysis": false,
        "Context": "Y29udGV4dC0wMmUyNmVmYi05OTZiLTQzNTctYTA1Ny03OGY1NmU3ZmRmNzUxNzgyNzM2NDc1NzE5",
        "ListOver": false,
        "RequestId": "e660b374-1538-4631-be77-c9a6e6680180",
        "Results": [
            {
                "FileName": "",
"LogJson": "{\"instance_id\":\"ins-gke2r5e0\",\"src_ip\":\"119.**.**.112\",\"dst_ip\":\"103.**.**.115\",\"src_port\":56980,\"dst_port\":80,\"protocol\":\"HTTP\",\"direction\":0,\"dst_domain\":\"www.**.com\",\"in_pkt_count\":8,\"in_pkt_len\":2998,\"out_pkt_count\":8,\"out_pkt_len\":416,\"total_pkt_count\":16,\"total_pkt_len\":3414,\"ti_tag\":\"\",\"start_time\":\"2026-06-29 14:12:11\",\"end_time\":\"2026-06-29 14:12:24\",\"supplier\":\"baidu.com\",\"src_country\":\"\",\"dst_country\":\"China\",\"src_province\":\"\",\"dst_province\":\"Guangdong Province\",\"src_city\":\"\",\"dst_city\":\"\",\"address\":\"Guangdong Province\",\"src_lat\":0,\"dst_lat\":0,\"src_lon\":0,\"dst_lon\":0,\"insert_time\":1782713553,\"count\":0,\"url\":\"\",\"domain_flag\":0,\"port_status\":0,\"level\":0,\"bot_flag\":0,\"mode\":1,\"tcp_flag\":31,\"timestamp\":\"2026-06-29 14:12:11\",\"is_serial\":1,\"pkt_flags\":\"0212101810\",\"pkt_dir\":\"01001\",\"action_src\":1,\"acl_uuid\":\"\",\"acl_rule_id\":0,\"acl_detail\":\"\"}"
                "PkgId": "5229A51C7BECDA416A3E478F-00000000000579C7",
                "PkgLogId": "29622640",
                "RawLog": "",
                "Time": 1782713531000,
                "TopicId": "cfw_netflow_border"
            }
        ],
        "SamplingRate": 0
    }
}

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 FailedOperation.InvalidContext
FailedOperation.QueryError FailedOperation.QueryError
FailedOperation.SearchTimeout FailedOperation.SearchTimeout
FailedOperation.SyntaxError FailedOperation.SyntaxError
FailedOperation.Timeout FailedOperation.Timeout
FailedOperation.TopicIsolated FailedOperation.TopicIsolated
InternalError Internal error.
InternalError.SearchError InternalError.SearchError
InternalError.SearchFailed InternalError.SearchFailed
InternalError.ServerBusy InternalError.ServerBusy
InvalidParameter Invalid parameter.
LimitExceeded.LogSearch LimitExceeded.LogSearch
LimitExceeded.SearchResources LimitExceeded.SearchResources
LimitExceeded.SearchResultTooLarge LimitExceeded.SearchResultTooLarge
MissingParameter Missing parameter.
OperationDenied Operation denied.
OperationDenied.AccountDestroy OperationDenied.AccountDestroy
OperationDenied.AccountIsolate OperationDenied.AccountIsolate
OperationDenied.AccountNotExists OperationDenied.AccountNotExists
OperationDenied.NewSyntaxNotSupported OperationDenied.NewSyntaxNotSupported
OperationDenied.OperationNotSupportInSearchLow OperationDenied.OperationNotSupportInSearchLow
ResourceNotFound.TopicNotExist ResourceNotFound.TopicNotExist
Topik sebelumnya: DescribeCfwStatusMonitorTopik selanjutnya: AddEnterpriseSecurityGroupRules

Bantuan dan Dukungan

Apakah halaman ini membantu?

masukan