Sign In to the Console
Amazon CloudWatch Logs
API Reference (API Version 2014-03-28)

AWS Documentation » Amazon CloudWatch Logs » API Reference » Actions » StartQuery
The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

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 a logGroupNames or a logGroupName 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 a logGroupNames or a logGroupName 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 2048.

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

Example

Schedule a query

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: