:original_name: ListFlowLogs.html
.. _ListFlowLogs:
Querying Flow Logs
==================
Function
--------
This API is used to query flow logs.
URI
---
GET /v1/{project_id}/cfw/logs/flow
.. table:: **Table 1** Path Parameters
========== ========= ====== ===========
Parameter Mandatory Type Description
========== ========= ====== ===========
project_id Yes String Project ID
========== ========= ====== ===========
.. table:: **Table 2** Query Parameters
+-----------------------+-----------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Parameter | Mandatory | Type | Description |
+=======================+=================+=================+================================================================================================================================================================================================================================+
| fw_instance_id | Yes | String | Firewall instance ID, which is automatically generated after a CFW instance is created. You can obtain the ID by calling the API used for querying a firewall instance. For details, see the API Explorer and Help Center FAQ. |
+-----------------------+-----------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| direction | No | String | direction, including in2out and out2in |
+-----------------------+-----------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| log_type | No | String | Log type |
| | | | |
| | | | Enumeration values: |
| | | | |
| | | | - **internet** |
| | | | |
| | | | - **vpc** |
| | | | |
| | | | - **nat** |
+-----------------------+-----------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| start_time | Yes | Long | Start time, a timestamp in milliseconds, such as 1718936272648 |
+-----------------------+-----------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| end_time | Yes | Long | End time, a timestamp in milliseconds, such as 1718936272648 |
+-----------------------+-----------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| src_ip | No | String | Source IP address |
+-----------------------+-----------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| src_port | No | Integer | Source port |
| | | | |
| | | | Minimum: **0** |
| | | | |
| | | | Maximum: **65535** |
+-----------------------+-----------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| dst_ip | No | String | Destination IP address |
+-----------------------+-----------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| dst_port | No | Integer | Destination port |
| | | | |
| | | | Minimum: **0** |
| | | | |
| | | | Maximum: **65535** |
+-----------------------+-----------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| protocol | No | String | Protocol types, including TCP, UDP, ICMP, ICMPV6, etc. |
+-----------------------+-----------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| app | No | String | Application protocol |
+-----------------------+-----------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| log_id | No | String | Document ID, the first page is empty, the other pages are not empty, and the other pages can take the log_id of the last query record. |
+-----------------------+-----------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| next_date | No | Long | The next date is empty when it is the first page, not empty when it is not the first page, and the other pages can take the start_time of the last query record. |
+-----------------------+-----------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| offset | No | Integer | Offset, which specifies the start position of the record to be returned. The value must be a number no less than 0. The first page is empty, and the non-first page is not empty. |
+-----------------------+-----------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| limit | Yes | Integer | Number of records displayed on each page, in the range 1-1024 |
| | | | |
| | | | Minimum: **1** |
| | | | |
| | | | Maximum: **1024** |
+-----------------------+-----------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| enterprise_project_id | No | String | Enterprise project id, the id generated by the enterprise project after the user supports the enterprise project. |
+-----------------------+-----------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| dst_host | No | String | destination host |
+-----------------------+-----------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| src_region_name | No | String | source region name |
+-----------------------+-----------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| dst_region_name | No | String | dst region name |
+-----------------------+-----------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| src_province_name | No | String | source province name |
+-----------------------+-----------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| dst_province_name | No | String | dst province name |
+-----------------------+-----------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| src_city_name | No | String | source city name |
+-----------------------+-----------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| dst_city_name | No | String | dst city name |
+-----------------------+-----------------+-----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Request Parameters
------------------
.. table:: **Table 3** Request header parameters
+--------------+-----------+--------+----------------------------------------------------------------------------------------------------------------------------------------------------+
| Parameter | Mandatory | Type | Description |
+==============+===========+========+====================================================================================================================================================+
| X-Auth-Token | Yes | String | User token. It can be obtained by calling the IAM API used to obtain a user token. The value of X-Subject-Token in the response header is a token. |
+--------------+-----------+--------+----------------------------------------------------------------------------------------------------------------------------------------------------+
Response Parameters
-------------------
**Status code: 200**
.. table:: **Table 4** Response body parameters
+-----------+--------------------------------------------------+-----------------------------------+
| Parameter | Type | Description |
+===========+==================================================+===================================+
| data | :ref:`data ` object | Value returned for flow log query |
+-----------+--------------------------------------------------+-----------------------------------+
.. _listflowlogs__response_data:
.. table:: **Table 5** data
+-----------+------------------------------------------------------------------+---------------------------------------------------------------+
| Parameter | Type | Description |
+===========+==================================================================+===============================================================+
| total | Integer | Returned quantity |
+-----------+------------------------------------------------------------------+---------------------------------------------------------------+
| limit | Integer | Number of records displayed on each page, in the range 1-1024 |
+-----------+------------------------------------------------------------------+---------------------------------------------------------------+
| records | Array of :ref:`records ` objects | Record |
+-----------+------------------------------------------------------------------+---------------------------------------------------------------+
.. _listflowlogs__response_records:
.. table:: **Table 6** records
+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Parameter | Type | Description |
+=======================+=======================+==================================================================================================================================================================================================================+
| bytes | Double | Byte |
+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| direction | String | Direction, which can be inbound or outbound |
| | | |
| | | Enumeration values: |
| | | |
| | | - **out2in** |
| | | |
| | | - **in2out** |
+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| packets | Integer | Packet |
+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| start_time | Long | Start time, a timestamp in milliseconds, such as 1718936272648 |
+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| end_time | Long | End time, a timestamp in milliseconds, such as 1718936272648 |
+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| log_id | String | Document ID |
+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| src_ip | String | Source IP address |
+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| src_port | Integer | Source port |
+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| dst_ip | String | Destination IP address |
+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| app | String | Application protocol |
+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| dst_port | Integer | Destination port |
+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| protocol | String | Protocol type. The value 6 indicates TCP, 17 indicates UDP, 1 indicates ICMP, 58 indicates ICMPv6, and -1 indicates any protocol. Regarding the addition type, a null value indicates it is automatically added. |
+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| dst_host | String | destination host |
+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| dst_region_id | String | destination region id |
+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| dst_region_name | String | destination region name |
+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| src_region_id | String | source region id |
+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| src_region_name | String | source region name |
+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| src_province_id | String | source province id |
+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| src_province_name | String | source province name |
+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| src_city_id | String | source city id |
+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| src_city_name | String | source city name |
+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| dst_province_id | String | dst province id |
+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| dst_province_name | String | dst province name |
+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| dst_city_id | String | dst city id |
+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| dst_city_name | String | dst city name |
+-----------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
**Status code: 400**
.. table:: **Table 7** Response body parameters
+-----------------------+-----------------------+-----------------------+
| Parameter | Type | Description |
+=======================+=======================+=======================+
| error_code | String | Error code |
| | | |
| | | Minimum: **8** |
| | | |
| | | Maximum: **36** |
+-----------------------+-----------------------+-----------------------+
| error_msg | String | Description |
| | | |
| | | Minimum: **2** |
| | | |
| | | Maximum: **512** |
+-----------------------+-----------------------+-----------------------+
Example Requests
----------------
Query the flow logs on the first page of the firewall with the ID 2af58b7c-893c-4453-a984-bdd9b1bd6318 in the project 9d80d070b6d44942af73c9c3d38e0429. The query time range is 1663555012000 to 1664159798000.
.. code-block::
https://{Endpoint}/v1/9d80d070b6d44942af73c9c3d38e0429/cfw/logs/flow?fw_instance_id=2af58b7c-893c-4453-a984-bdd9b1bd6318&start_time=1663555012000&end_time=1664159798000&limit=10
Example Responses
-----------------
**Status code: 200**
OK
.. code-block::
{
"data" : {
"limit" : 10,
"records" : [ {
"app" : "SSH",
"bytes" : 34.5,
"direction" : "out2in",
"dst_ip" : "100.95.148.49",
"dst_port" : 22,
"end_time" : 1664155493000,
"log_id" : "76354",
"packets" : 25,
"protocol" : "TCP",
"src_ip" : "100.93.27.17",
"src_port" : 49634,
"start_time" : 1664155428000,
"src_province_id" : "source province id",
"src_province_name" : "source province name",
"src_city_id" : "source city id",
"src_city_name" : "source city name",
"dst_province_id" : "dst province id",
"dst_province_name" : "dst province name",
"dst_city_id" : "dst city id",
"dst_city_name" : "dst city name"
} ],
"total" : 1
}
}
**Status code: 400**
Bad Request
.. code-block::
{
"error_code" : "CFW.00500002",
"error_msg" : "time range error"
}
Status Codes
------------
=========== =====================
Status Code Description
=========== =====================
200 OK
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error
=========== =====================
Error Codes
-----------
See :ref:`Error Codes `.