StartQuery
Schedules a query of a log group using CloudWatch Logs Insights. You specify the log group and time range to query and the query string to use.
For more information, see CloudWatch Logs Insights Query Syntax.
Queries time out after 15 minutes of execution. If your queries are timing out, reduce the time range being searched or partition your query into a number of queries.
Request Syntax
{
"endTime": number
,
"limit": number
,
"logGroupName": "string
",
"logGroupNames": [ "string
" ],
"queryString": "string
",
"startTime": number
}
Request Parameters
For information about the parameters that are common to all actions, see Common Parameters.
The request accepts the following data in JSON format.
- endTime
-
The end of the time range to query. The range is inclusive, so the specified end time is included in the query. Specified as epoch time, the number of seconds since January 1, 1970, 00:00:00 UTC.
Type: Long
Valid Range: Minimum value of 0.
Required: Yes
- limit
-
The maximum number of log events to return in the query. If the query string uses the
fields
command, only the specified fields and their values are returned. The default is 1000.Type: Integer
Valid Range: Minimum value of 1. Maximum value of 10000.
Required: No
- logGroupName
-
The log group on which to perform the query.
A
StartQuery
operation must include alogGroupNames
or alogGroupName
parameter, but not both.Type: String
Length Constraints: Minimum length of 1. Maximum length of 512.
Pattern:
[\.\-_/#A-Za-z0-9]+
Required: No
- logGroupNames
-
The list of log groups to be queried. You can include up to 20 log groups.
A
StartQuery
operation must include alogGroupNames
or alogGroupName
parameter, but not both.Type: Array of strings
Length Constraints: Minimum length of 1. Maximum length of 512.
Pattern:
[\.\-_/#A-Za-z0-9]+
Required: No
- queryString
-
The query string to use. For more information, see CloudWatch Logs Insights Query Syntax.
Type: String
Length Constraints: Minimum length of 0. Maximum length of 10000.
Required: Yes
- startTime
-
The beginning of the time range to query. The range is inclusive, so the specified start time is included in the query. Specified as epoch time, the number of seconds since January 1, 1970, 00:00:00 UTC.
Type: Long
Valid Range: Minimum value of 0.
Required: Yes
Response Syntax
{
"queryId": "string"
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
- queryId
-
The unique ID of the query.
Type: String
Length Constraints: Minimum length of 0. Maximum length of 256.
Errors
For information about the errors that are common to all actions, see Common Errors.
- InvalidParameterException
-
A parameter is specified incorrectly.
HTTP Status Code: 400
- LimitExceededException
-
You have reached the maximum number of resources that can be created.
HTTP Status Code: 400
- MalformedQueryException
-
The query string is not valid. Details about this error are displayed in a
QueryCompileError
object. For more information, see QueryCompileError.For more information about valid query syntax, see CloudWatch Logs Insights Query Syntax.
HTTP Status Code: 400
- ResourceNotFoundException
-
The specified resource does not exist.
HTTP Status Code: 400
- ServiceUnavailableException
-
The service cannot complete the request.
HTTP Status Code: 500
Examples
Schedule a query
This example schedules a query of three log groups, specifying the query string and start time. It also limits the results to the most recent 100 matching events.
Sample Request
POST / HTTP/1.1
Host: logs.<region>.<domain>
X-Amz-Date: <DATE>
Authorization: AWS4-HMAC-SHA256 Credential=<Credential>, SignedHeaders=content-type;date;host;user-agent;x-amz-date;x-amz-target;x-amzn-requestid, Signature=<Signature>
User-Agent: <UserAgentString>
Accept: application/json
Content-Type: application/x-amz-json-1.1
Content-Length: <PayloadSizeBytes>
Connection: Keep-Alive
X-Amz-Target: Logs_20140328.StartQuery
{
"limit": 100,
"logGroupNames": [
"LogGroupName1",
"LogGroupName2",
"LogGroupName3"
],
"queryString": "stats count(*) by eventSource, eventName, awsRegion",
"startTime": 1546300800,
"endTime": 1546309800
}
Sample Response
HTTP/1.1 200 OK
x-amzn-RequestId: <RequestId>
Content-Type: application/x-amz-json-1.1
Content-Length: <PayloadSizeBytes>
Date: <Date>
{
"queryId": "12ab3456-12ab-123a-789e-1234567890ab"
}
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following: