Request Syntax Request Parameters Response Syntax Response Elements Errors See Also

CreateScheduledQuery

Creates a new Scheduled Query that runs CloudWatch Logs Insights queries on a schedule and delivers results to specified destinations.

Request Syntax


{
   "description": "string",
   "destinationConfiguration": { 
      "s3Configuration": { 
         "destinationIdentifier": "string",
         "roleArn": "string"
      }
   },
   "executionRoleArn": "string",
   "logGroupIdentifiers": [ "string" ],
   "name": "string",
   "queryLanguage": "string",
   "queryString": "string",
   "scheduleEndTime": number,
   "scheduleExpression": "string",
   "scheduleStartTime": number,
   "startTimeOffset": number,
   "state": "string",
   "tags": { 
      "string" : "string" 
   },
   "timezone": "string"
}

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.

description

An optional description for the scheduled query to help identify its purpose.

Type: String

Length Constraints: Maximum length of 1024.

Required: No

destinationConfiguration

Configuration for destinations where the query results will be delivered after successful execution. You can configure delivery to S3 buckets or EventBridge event buses.

Type: DestinationConfiguration object

Required: No

executionRoleArn

The Amazon Resource Name (ARN) of the IAM role that CloudWatch Logs will assume to execute the scheduled query and deliver results to the specified destinations.

Type: String

Length Constraints: Minimum length of 1.

Required: Yes

logGroupIdentifiers

The log group identifiers to query. You can specify log group names or log group ARNs. If querying log groups in a source account from a monitoring account, you must specify the ARN of the log group.

Type: Array of strings

Array Members: Minimum number of 1 item. Maximum number of 50 items.

Length Constraints: Minimum length of 1. Maximum length of 2048.

Pattern: [\w#+=/:,.@-]*

Required: No

name

A unique name for the scheduled query within the region for an AWS account. The name can contain letters, numbers, underscores, hyphens, forward slashes, periods, and hash symbols.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 255.

Pattern: ^[a-zA-Z0-9_\-/.#]+$

Required: Yes

queryLanguage

The query language to use for the scheduled query. Valid values are LogsQL (CloudWatch Logs Insights query language), PPL (OpenSearch Service Piped Processing Language), and SQL (OpenSearch Service Structured Query Language).

Type: String

Valid Values: CWLI | SQL | PPL

Required: Yes

queryString

The CloudWatch Logs Insights query string to execute. This is the actual query that will be run against your log data on the specified schedule.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 10000.

Required: Yes

scheduleEndTime

The end time for the query schedule in Unix epoch time (seconds since January 1, 1970, 00:00:00 UTC). If not specified, the schedule runs indefinitely.

Type: Long

Valid Range: Minimum value of 0.

Required: No

scheduleExpression

A cron expression that defines when the scheduled query runs. The format is cron(fields) where fields consist of six space-separated values: minutes, hours, day_of_month, month, day_of_week, year.

Type: String

Length Constraints: Maximum length of 256.

Required: Yes

scheduleStartTime

The start time for the query schedule in Unix epoch time (seconds since January 1, 1970, 00:00:00 UTC). If not specified, the schedule starts immediately.

Type: Long

Valid Range: Minimum value of 0.

Required: No

startTimeOffset

Time offset in seconds from the execution time for the start of the query time range. This defines the lookback period for the query (for example, 3600 for the last hour).

Type: Long

Required: No

state

The initial state of the scheduled query. Valid values are ENABLED (the query will run according to its schedule) and DISABLED (the query is paused and will not run). If not provided, defaults to ENABLED.

Type: String

Valid Values: ENABLED | DISABLED

Required: No

tags

An optional list of key-value pairs to associate with the resource.

For more information about tagging, see Tagging AWS resources

Type: String to string map

Map Entries: Maximum number of 50 items.

Key Length Constraints: Minimum length of 1. Maximum length of 128.

Key Pattern: ^([\p{L}\p{Z}\p{N}_.:/=+\-@]+)$

Value Length Constraints: Maximum length of 256.

Value Pattern: ^([\p{L}\p{Z}\p{N}_.:/=+\-@]*)$

Required: No

timezone

The timezone in which the schedule expression is evaluated. If not provided, defaults to UTC.

Type: String

Length Constraints: Minimum length of 1.

Required: No

Response Syntax


{
   "scheduledQueryArn": "string",
   "state": "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.

scheduledQueryArn

The Amazon Resource Name (ARN) of the created scheduled query.

Type: String

state

The current state of the scheduled query (ENABLED or DISABLED).

Type: String

Valid Values: ENABLED | DISABLED

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have sufficient permissions to perform this action.

HTTP Status Code: 400

ConflictException

This operation attempted to create a resource that already exists.

HTTP Status Code: 400

InternalServerException

An internal server error occurred while processing the request. This is typically a temporary issue and the request can be retried.

HTTP Status Code: 500

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 400

ServiceQuotaExceededException

This request exceeds a service quota.

HTTP Status Code: 400

ThrottlingException

The request was throttled because of quota limits.

HTTP Status Code: 400

ValidationException

One of the parameters for the request is not valid.

HTTP Status Code: 400