Help Center/ Log Tank Service/ API Reference/ APIs/ Log Management/ Querying Logs
Updated on 2025-11-18 GMT+08:00
View PDF

Querying Logs

Function

This API is used to query logs in a specified log stream.

URI

POST /v2/{project_id}/groups/{log_group_id}/streams/{log_stream_id}/content/query

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Project ID. For details about how to obtain it, see Obtaining a Project ID.

log_group_id

Yes

String

Log group ID. For details about how to obtain it, see Obtaining a Log Group ID.

log_stream_id

Yes

String

Log stream ID. For details about how to obtain it, see Obtaining a Log Stream ID.

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

User token obtained from IAM. For details about how to obtain it, see Obtaining a User Token.

Content-Type

Yes

String

Set this parameter to application/json;charset=UTF-8.
Table 3 Request body parameters

Parameter

Mandatory

Type

Description

start_time

Yes

String

Start time of the query (UTC, in ms).

NOTE:
Maximum query time range: 30 days

end_time

Yes

String

End time of the query (UTC, in ms).

NOTE:
Maximum query time range: 30 days

labels

No

Map<String,String>

Log filter criteria, which vary by log source.

keywords

No

String

Keyword used for log search. A keyword is a word between two adjacent delimiters, for example, error.

line_num

No

String

Sequence number of the final log event in the last query result. This parameter is not required for the first query, but is required for subsequent pagination queries. The value can be obtained from the response of the last query. The value of line_num should be between the values of start_time and end_time.

is_desc

No

Boolean

Whether the search order is descending or ascending. The default value is false, indicating that search results are displayed in ascending order.

search_type

No

String

The value is init (default value) for the first query, or forwards or backwards for a pagination query. This parameter is used together with is_desc for pagination queries.

limit

No

Integer

Number of log events queried each time. The default value is 50 when this parameter is not set. You are advised to set this parameter to 100.

highlight

No

Boolean

Whether the keyword is highlighted. The value can be true (highlighted; default) or false (not highlighted).

is_count

No

Boolean

Whether the number of log events is counted. The value can be false (not counted; default) or true (counted).

is_iterative

No

Boolean

Whether the log query is iterative. The value can be false (not iterative; default) or true (iterative).

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

logs

Array of LogContents objects

Log information.

count

Integer

Number of log events.

isQueryComplete

Boolean

Whether the query is complete.
Table 5 LogContents

Parameter

Type

Description

content

String

Raw log data.

line_num

String

Sequence number of a log line.

labels

Map<String,String>

Labels contained in a log event. The labels vary depending on log events.

Status code: 400

Table 6 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error message.

Status code: 401

Table 7 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error message.

Status code: 403

Table 8 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error message.

Status code: 500

Table 9 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error message.

Example Requests

  • Query logs.

    POST https://{endpoint}/v2/{project_id}/groups/{log_group_id}/streams/{log_stream_id}/content/query

2020-07-25/14:44:42 this log is Error NO 1
2020-07-25/14:44:43 this log is Error NO 2
2020-07-25/14:44:44 this log is Error NO 3
2020-07-25/14:44:45 this log is Error NO 4
2020-07-25/14:44:46 this log is Error NO 5
2020-07-25/14:44:47 this log is Error NO 6
2020-07-25/14:44:48 this log is Error NO 7
2020-07-25/14:44:49 this log is Error NO 8
2020-07-25/14:44:50 this log is Error NO 9
2020-07-25/14:44:51 this log is Error NO 10

  • For the first query:

    v2/{project_id}/groups/{log_group_id}/streams/{log_stream_id}/content/query

{
  "start_time" : 1595659200000,
  "end_time" : 1595659500000,
  "labels" : {
    "hostName" : "ecs-kwxtest"
  },
  "keywords" : "log",
  "limit" : 10,
  "is_count" : true
}

  • For a pagination query (Assume that the search starts from the log event containing NO 5. Log events containing NO 6, NO 7, and NO 8 are the target log events):

    v2/{project_id}/groups/{log_group_id}/streams/{log_stream_id}/content/query

{
  "start_time" : 1595659200000,
  "end_time" : 1595659500000,
  "labels" : {
    "hostName" : "ecs-kwxtest"
  },
  "keywords" : "log",
  "line_num" : "1595659490239433658",
  "is_desc" : "false",
  "search_type" : "forwards",
  "limit" : "3",
  "is_count" : true
}

  • For a pagination query (Assume that the search starts from the log event containing NO 5. Log events containing NO 8, NO 7, and NO 6 are the target log events):

    v2/{project_id}/groups/{log_group_id}/streams/{log_stream_id}/content/query

{
  "start_time" : 1595659200000,
  "end_time" : 1595659500000,
  "labels" : {
    "hostName" : "ecs-kwxtest"
  },
  "keywords" : "log",
  "line_num" : "1595659490239433658",
  "is_desc" : "true",
  "search_type" : "backwards",
  "limit" : "3",
  "is_count" : true
}

  • For a pagination query (Assume that the search starts from the log event containing NO 5. Log events containing NO 2, NO 3, and NO 4 are the target log events):

    v2/{project_id}/groups/{log_group_id}/streams/{log_stream_id}/content/query

{
  "start_time" : 1595659200000,
  "end_time" : 1595659500000,
  "labels" : {
    "hostName" : "ecs-kwxtest"
  },
  "keywords" : "log",
  "line_num" : "1595659490239433658",
  "is_desc" : "false",
  "search_type" : "backwards",
  "limit" : "3",
  "is_count" : true
}

  • For a pagination query (Assume that the search starts from the log event containing NO 5. Log events containing NO 4, NO 3, and NO 2 are the target log events):

    v2/{project_id}/groups/{log_group_id}/streams/{log_stream_id}/content/query

{
  "start_time" : 1595659200000,
  "end_time" : 1595659500000,
  "labels" : {
    "hostName" : "ecs-kwxtest"
  },
  "keywords" : "log",
  "line_num" : "1595659490239433658",
  "is_desc" : "true",
  "search_type" : "forwards",
  "limit" : "3",
  "is_count" : true
}

Example Responses

Status code: 200

The request is successful.

  • For the first query:

    {
  "count" : 32,
  "logs" : [ {
    "content" : "2020-07-25/14:44:42 this <HighLightTag>log</HighLightTag> is Error NO 1",
    "labels" : {
      "hostName" : "ecs-kwxtest",
      "hostIP" : "192.168.0.156",
      "appName" : "default_appname",
      "containerName" : "CONFIG_FILE",
      "clusterName" : "CONFIG_FILE",
      "hostId" : "9787ef31-fd7b-4eff-ba71-72d580f11f55",
      "podName" : "default_procname",
      "clusterId" : "CONFIG_FILE",
      "nameSpace" : "CONFIG_FILE",
      "category" : "LTS"
    },
    "line_num" : "1595659490239433654"
  }, {
    "content" : "2020-07-25/14:44:43 this <HighLightTag>log</HighLightTag> is Error NO 2",
    "labels" : {
      "hostName" : "ecs-kwxtest",
      "hostIP" : "192.168.0.156",
      "appName" : "default_appname",
      "containerName" : "CONFIG_FILE",
      "clusterName" : "CONFIG_FILE",
      "hostId" : "9787ef31-fd7b-4eff-ba71-72d580f11f55",
      "podName" : "default_procname",
      "clusterId" : "CONFIG_FILE",
      "nameSpace" : "CONFIG_FILE",
      "category" : "LTS"
    },
    "line_num" : "1595659490239433655"
  }, {
    "content" : "2020-07-25/14:44:44 this <HighLightTag>log</HighLightTag> is Error NO 3",
    "labels" : {
      "hostName" : "ecs-kwxtest",
      "hostIP" : "192.168.0.156",
      "appName" : "default_appname",
      "containerName" : "CONFIG_FILE",
      "clusterName" : "CONFIG_FILE",
      "hostId" : "9787ef31-fd7b-4eff-ba71-72d580f11f55",
      "podName" : "default_procname",
      "clusterId" : "CONFIG_FILE",
      "nameSpace" : "CONFIG_FILE",
      "category" : "LTS"
    },
    "line_num" : "1595659490239433656"
  }, {
    "content" : "2020-07-25/14:44:45 this <HighLightTag>log</HighLightTag> is Error NO 4",
    "labels" : {
      "hostName" : "ecs-kwxtest",
      "hostIP" : "192.168.0.156",
      "appName" : "default_appname",
      "containerName" : "CONFIG_FILE",
      "clusterName" : "CONFIG_FILE",
      "hostId" : "9787ef31-fd7b-4eff-ba71-72d580f11f55",
      "podName" : "default_procname",
      "clusterId" : "CONFIG_FILE",
      "nameSpace" : "CONFIG_FILE",
      "category" : "LTS"
    },
    "line_num" : "1595659490239433657"
  }, {
    "content" : "2020-07-25/14:44:46 this <HighLightTag>log</HighLightTag> is Error NO 5",
    "labels" : {
      "hostName" : "ecs-kwxtest",
      "hostIP" : "192.168.0.156",
      "appName" : "default_appname",
      "containerName" : "CONFIG_FILE",
      "clusterName" : "CONFIG_FILE",
      "hostId" : "9787ef31-fd7b-4eff-ba71-72d580f11f55",
      "podName" : "default_procname",
      "clusterId" : "CONFIG_FILE",
      "nameSpace" : "CONFIG_FILE",
      "category" : "LTS"
    },
    "line_num" : "1595659490239433658"
  }, {
    "content" : "2020-07-25/14:44:47 this <HighLightTag>log</HighLightTag> is Error NO 6",
    "labels" : {
      "hostName" : "ecs-kwxtest",
      "hostIP" : "192.168.0.156",
      "appName" : "default_appname",
      "containerName" : "CONFIG_FILE",
      "clusterName" : "CONFIG_FILE",
      "hostId" : "9787ef31-fd7b-4eff-ba71-72d580f11f55",
      "podName" : "default_procname",
      "clusterId" : "CONFIG_FILE",
      "nameSpace" : "CONFIG_FILE",
      "category" : "LTS"
    },
    "line_num" : "1595659490239433659"
  }, {
    "content" : "2020-07-25/14:44:48 this <HighLightTag>log</HighLightTag> is Error NO 7",
    "labels" : {
      "hostName" : "ecs-kwxtest",
      "hostIP" : "192.168.0.156",
      "appName" : "default_appname",
      "containerName" : "CONFIG_FILE",
      "clusterName" : "CONFIG_FILE",
      "hostId" : "9787ef31-fd7b-4eff-ba71-72d580f11f55",
      "podName" : "default_procname",
      "clusterId" : "CONFIG_FILE",
      "nameSpace" : "CONFIG_FILE",
      "category" : "LTS"
    },
    "line_num" : "1595659490239433660"
  }, {
    "content" : "2020-07-25/14:44:49 this <HighLightTag>log</HighLightTag> is Error NO 8",
    "labels" : {
      "hostName" : "ecs-kwxtest",
      "hostIP" : "192.168.0.156",
      "appName" : "default_appname",
      "containerName" : "CONFIG_FILE",
      "clusterName" : "CONFIG_FILE",
      "hostId" : "9787ef31-fd7b-4eff-ba71-72d580f11f55",
      "podName" : "default_procname",
      "clusterId" : "CONFIG_FILE",
      "nameSpace" : "CONFIG_FILE",
      "category" : "LTS"
    },
    "line_num" : "1595659490239433661"
  }, {
    "content" : "2020-07-25/14:44:50 this <HighLightTag>log</HighLightTag> is Error NO 9",
    "labels" : {
      "hostName" : "ecs-kwxtest",
      "hostIP" : "192.168.0.156",
      "appName" : "default_appname",
      "containerName" : "CONFIG_FILE",
      "clusterName" : "CONFIG_FILE",
      "hostId" : "9787ef31-fd7b-4eff-ba71-72d580f11f55",
      "podName" : "default_procname",
      "clusterId" : "CONFIG_FILE",
      "nameSpace" : "CONFIG_FILE",
      "category" : "LTS"
    },
    "line_num" : "1595659490839420574"
  }, {
    "content" : "2020-07-25/14:44:51 this <HighLightTag>log</HighLightTag> is Error NO 10",
    "labels" : {
      "hostName" : "ecs-kwxtest",
      "hostIP" : "192.168.0.156",
      "appName" : "default_appname",
      "containerName" : "CONFIG_FILE",
      "clusterName" : "CONFIG_FILE",
      "hostId" : "9787ef31-fd7b-4eff-ba71-72d580f11f55",
      "podName" : "default_procname",
      "clusterId" : "CONFIG_FILE",
      "nameSpace" : "CONFIG_FILE",
      "category" : "LTS"
    },
    "line_num" : "1595659491839412667"
  } ]
}

  • For a pagination query (Assume that the search starts from the log event containing NO 5. Log events containing NO 6, NO 7, and NO 8 are the target log events):

    {
  "count" : 32,
  "logs" : [ {
    "content" : "2020-07-25/14:44:47 this <HighLightTag>log</HighLightTag> is Error NO 6",
    "labels" : {
      "hostName" : "ecs-kwxtest",
      "hostIP" : "192.168.0.156",
      "appName" : "default_appname",
      "containerName" : "CONFIG_FILE",
      "clusterName" : "CONFIG_FILE",
      "hostId" : "9787ef31-fd7b-4eff-ba71-72d580f11f55",
      "podName" : "default_procname",
      "clusterId" : "CONFIG_FILE",
      "nameSpace" : "CONFIG_FILE",
      "category" : "LTS"
    },
    "line_num" : "1595659490239433659"
  }, {
    "content" : "2020-07-25/14:44:48 this <HighLightTag>log</HighLightTag> is Error NO 7",
    "labels" : {
      "hostName" : "ecs-kwxtest",
      "hostIP" : "192.168.0.156",
      "appName" : "default_appname",
      "containerName" : "CONFIG_FILE",
      "clusterName" : "CONFIG_FILE",
      "hostId" : "9787ef31-fd7b-4eff-ba71-72d580f11f55",
      "podName" : "default_procname",
      "clusterId" : "CONFIG_FILE",
      "nameSpace" : "CONFIG_FILE",
      "category" : "LTS"
    },
    "line_num" : "1595659490239433660"
  }, {
    "content" : "2020-07-25/14:44:49 this <HighLightTag>log</HighLightTag> is Error NO 8",
    "labels" : {
      "hostName" : "ecs-kwxtest",
      "hostIP" : "192.168.0.156",
      "appName" : "default_appname",
      "containerName" : "CONFIG_FILE",
      "clusterName" : "CONFIG_FILE",
      "hostId" : "9787ef31-fd7b-4eff-ba71-72d580f11f55",
      "podName" : "default_procname",
      "clusterId" : "CONFIG_FILE",
      "nameSpace" : "CONFIG_FILE",
      "category" : "LTS"
    },
    "line_num" : "1595659490239433661"
  } ]
}

  • For a pagination query (Assume that the search starts from the log event containing NO 5. Log events containing NO 8, NO 7, and NO 6 are the target log events):

    {
  "count" : 32,
  "logs" : [ {
    "content" : "2020-07-25/14:44:49 this <HighLightTag>log</HighLightTag> is Error NO 8",
    "labels" : {
      "hostName" : "ecs-kwxtest",
      "hostIP" : "192.168.0.156",
      "appName" : "default_appname",
      "containerName" : "CONFIG_FILE",
      "clusterName" : "CONFIG_FILE",
      "hostId" : "9787ef31-fd7b-4eff-ba71-72d580f11f55",
      "podName" : "default_procname",
      "clusterId" : "CONFIG_FILE",
      "nameSpace" : "CONFIG_FILE",
      "category" : "LTS"
    },
    "line_num" : "1595659490239433661"
  }, {
    "content" : "2020-07-25/14:44:48 this <HighLightTag>log</HighLightTag> is Error NO 7",
    "labels" : {
      "hostName" : "ecs-kwxtest",
      "hostIP" : "192.168.0.156",
      "appName" : "default_appname",
      "containerName" : "CONFIG_FILE",
      "clusterName" : "CONFIG_FILE",
      "hostId" : "9787ef31-fd7b-4eff-ba71-72d580f11f55",
      "podName" : "default_procname",
      "clusterId" : "CONFIG_FILE",
      "nameSpace" : "CONFIG_FILE",
      "category" : "LTS"
    },
    "line_num" : "1595659490239433660"
  }, {
    "content" : "2020-07-25/14:44:47 this <HighLightTag>log</HighLightTag> is Error NO 6",
    "labels" : {
      "hostName" : "ecs-kwxtest",
      "hostIP" : "192.168.0.156",
      "appName" : "default_appname",
      "containerName" : "CONFIG_FILE",
      "clusterName" : "CONFIG_FILE",
      "hostId" : "9787ef31-fd7b-4eff-ba71-72d580f11f55",
      "podName" : "default_procname",
      "clusterId" : "CONFIG_FILE",
      "nameSpace" : "CONFIG_FILE",
      "category" : "LTS"
    },
    "line_num" : "1595659490239433659"
  } ]
}

  • For a pagination query (Assume that the search starts from the log event containing NO 5. Log events containing NO 2, NO 3, and NO 4 are the target log events):

    {
  "count" : 32,
  "logs" : [ {
    "content" : "2020-07-25/14:44:43 this <HighLightTag>log</HighLightTag> is Error NO 2",
    "labels" : {
      "hostName" : "ecs-kwxtest",
      "hostIP" : "192.168.0.156",
      "appName" : "default_appname",
      "containerName" : "CONFIG_FILE",
      "clusterName" : "CONFIG_FILE",
      "hostId" : "9787ef31-fd7b-4eff-ba71-72d580f11f55",
      "podName" : "default_procname",
      "clusterId" : "CONFIG_FILE",
      "nameSpace" : "CONFIG_FILE",
      "category" : "LTS"
    },
    "line_num" : "1595659490239433655"
  }, {
    "content" : "2020-07-25/14:44:44 this <HighLightTag>log</HighLightTag> is Error NO 3",
    "labels" : {
      "hostName" : "ecs-kwxtest",
      "hostIP" : "192.168.0.156",
      "appName" : "default_appname",
      "containerName" : "CONFIG_FILE",
      "clusterName" : "CONFIG_FILE",
      "hostId" : "9787ef31-fd7b-4eff-ba71-72d580f11f55",
      "podName" : "default_procname",
      "clusterId" : "CONFIG_FILE",
      "nameSpace" : "CONFIG_FILE",
      "category" : "LTS"
    },
    "line_num" : "1595659490239433656"
  }, {
    "content" : "2020-07-25/14:44:45 this <HighLightTag>log</HighLightTag> is Error NO 4",
    "labels" : {
      "hostName" : "ecs-kwxtest",
      "hostIP" : "192.168.0.156",
      "appName" : "default_appname",
      "containerName" : "CONFIG_FILE",
      "clusterName" : "CONFIG_FILE",
      "hostId" : "9787ef31-fd7b-4eff-ba71-72d580f11f55",
      "podName" : "default_procname",
      "clusterId" : "CONFIG_FILE",
      "nameSpace" : "CONFIG_FILE",
      "category" : "LTS"
    },
    "line_num" : "1595659490239433657"
  } ]
}

  • For a pagination query (Assume that the search starts from the log event containing NO 5. Log events containing NO 4, NO 3, and NO 2 are the target log events):

    {
  "count" : 32,
  "logs" : [ {
    "content" : "2020-07-25/14:44:45 this <HighLightTag>log</HighLightTag> is Error NO 4",
    "labels" : {
      "hostName" : "ecs-kwxtest",
      "hostIP" : "192.168.0.156",
      "appName" : "default_appname",
      "containerName" : "CONFIG_FILE",
      "clusterName" : "CONFIG_FILE",
      "hostId" : "9787ef31-fd7b-4eff-ba71-72d580f11f55",
      "podName" : "default_procname",
      "clusterId" : "CONFIG_FILE",
      "nameSpace" : "CONFIG_FILE",
      "category" : "LTS"
    },
    "line_num" : "1595659490239433657"
  }, {
    "content" : "2020-07-25/14:44:44 this <HighLightTag>log</HighLightTag> is Error NO 3",
    "labels" : {
      "hostName" : "ecs-kwxtest",
      "hostIP" : "192.168.0.156",
      "appName" : "default_appname",
      "containerName" : "CONFIG_FILE",
      "clusterName" : "CONFIG_FILE",
      "hostId" : "9787ef31-fd7b-4eff-ba71-72d580f11f55",
      "podName" : "default_procname",
      "clusterId" : "CONFIG_FILE",
      "nameSpace" : "CONFIG_FILE",
      "category" : "LTS"
    },
    "line_num" : "1595659490239433656"
  }, {
    "content" : "2020-07-25/14:44:43 this <HighLightTag>log</HighLightTag> is Error NO 2",
    "labels" : {
      "hostName" : "ecs-kwxtest",
      "hostIP" : "192.168.0.156",
      "appName" : "default_appname",
      "containerName" : "CONFIG_FILE",
      "clusterName" : "CONFIG_FILE",
      "hostId" : "9787ef31-fd7b-4eff-ba71-72d580f11f55",
      "podName" : "default_procname",
      "clusterId" : "CONFIG_FILE",
      "nameSpace" : "CONFIG_FILE",
      "category" : "LTS"
    },
    "line_num" : "1595659490239433655"
  } ]
}

Status code: 400

The request is invalid. Modify the request based on the description in error_msg before a retry.

{
  "error_code" : "LTS.0009",
  "error_msg" : "Failed to validate the request body"
}

Status code: 401

Authentication failed. Check the token and try again.

{
  "error_code" : "LTS.0003",
  "error_msg" : "Invalid token"
}

Status code: 403

The request is rejected.The server has received the request and understood it, but refuses to respond to it. The client should not repeat the request without modifications.

{
  "error_code" : "LTS.0001",
  "error_msg" : "Invalid projectId"
}

Status code: 500

The server has received the request but encountered an internal error.

{
  "error_code" : "LTS.0202",
  "error_msg" : "Failed to query lts log"
}

Status Codes

Status Code

Description

200

The request is successful.

400

The request is invalid. Modify the request based on the description in error_msg before a retry.

401

Authentication failed. Check the token and try again.

403

The request is rejected.The server has received the request and understood it, but refuses to respond to it. The client should not repeat the request without modifications.

500

The server has received the request but encountered an internal error.

503

The requested service is unavailable.

Error Codes

See Error Codes.

Parent topic: Log Management