# Getting started with scheduled queries
<a name="scheduled-queries-getting-started"></a>

When you create a scheduled query, you'll configure several key components that define how your query runs and where results are delivered. Understanding these components will help you set up effective automated log analysis.

Each scheduled query consists of the following key components:

**Query configuration**  
The CloudWatch Logs Insights query string, target log groups, and query language to use for analysis.

**Schedule expression**  
A cron expression or frequency calendar that defines when the query runs. You can specify timezone settings to ensure queries run at the correct local time. The console displays a human-readable description of your schedule, such as "Run query on every Tuesday at 15:10 for a time range of 5 minutes, effective immediately, on UTC, until indefinitely."

**Time range**  
The lookback period for each query execution, defined by a start time offset from the execution time. This determines how much historical data each query execution will analyze.

**Execution schedule preview**  
The console shows the next three scheduled query runs with exact dates and times (for example, 2025/10/28 15:10, UTC; 2025/11/04 15:10, UTC; 2025/11/11 15:10, UTC), helping you verify that the schedule is configured correctly.

**Destinations**  
Where query results are delivered after successful execution. Supported destinations include Amazon S3 buckets and by default result metadata is send to the default event bus.

**Execution role**  
An IAM role that CloudWatch Logs assumes to execute the query and deliver results to the specified destinations.

Before creating scheduled queries, ensure you have the necessary permissions and resources configured.

# Creating a scheduled query
<a name="create-scheduled-query"></a>

Create a scheduled query that automatically runs CloudWatch Logs Insights queries and delivers results to your chosen destinations.

## Prerequisites
<a name="create-scheduled-query-prerequisites"></a>

Before creating a scheduled query, ensure you have the following:
+ **Log groups** - One or more log groups containing the data you want to analyze
+ **Execution IAM role** - An IAM role with the following permissions:
  + `logs:StartQuery` - Permission to start CloudWatch Logs Insights queries
  + `logs:GetQueryResults` - Permission to retrieve query results
  + `logs:DescribeLogGroups` - Permission to access log group information. This is only required for prefix based log groups for log group discovery
+ **Destination permissions** - Additional IAM permissions for your chosen destination:
  + For Amazon S3 destinations: `s3:PutObject`
+ **For AWS CLI and API usage** - Configured AWS credentials with permissions to call CloudWatch Logs APIs

For detailed IAM policy examples, see [Identity and access management for Amazon CloudWatch Logs](auth-and-access-control-cwl.md). Also to be noted you can have only 1000 scheduled queries per account.

------
#### [ Console ]

**To create a scheduled query (console)**

1. Open the CloudWatch Logs console at [https://us-east-1.console.aws.amazon.com/cloudwatch/home?region=us-east-1\$1logsV2:logs-insights](https://us-east-1.console.aws.amazon.com/cloudwatch/home?region=us-east-1#logsV2:logs-insights).

1. In the navigation pane, choose **Logs Insights**.

1. Choose **Create scheduled query**.

1. In the **Query definition** section:

   1. For **Query language**, choose the query language to use from the list.

   1. For **Query string**, enter your CloudWatch Logs Insights query in the box.

   1. For **Log groups**, select the log groups to query from the list.

1. In the **Schedule setup** section:

   1. For **Schedule expression**, configure when the query runs. Choose from predefined options or enter a custom cron expression.

   1. For **Effective upon creation**, specify when the schedule becomes active. Choose to start immediately or at a specific date and time using YYYY/MM/DD format.

   1. For **Time range**, specify the lookback period for each query execution. Enter the duration in minutes that defines how far back from the execution time to query.

   1. For **Continue indefinitely**, specify when the schedule ends. Choose to run indefinitely or until a specific date and time using YYYY/MM/DD format.

1. The console displays the next three scheduled query runs based on your configuration, showing the exact dates and times in UTC when the query will execute.

1. In the **Post query results to S3 - optional** section (if using S3 destination):

   1. For **S3 bucket**, select **This account** if the destination bucket is in the same AWS account, or select **Another account** if the bucket is in a different AWS account and provide the account ID of the bucket-owning account as input.

   1. For **Amazon S3 URI**, enter the Amazon S3 bucket and prefix where results will be stored (for example, `s3://my-bucket/query-results/`). If you selected **This account**, you can choose **Browse Amazon S3** to navigate and select an existing Amazon S3 location.

   1. (Optional) For **KMS key ARN**, enter the ARN of a customer managed AWS KMS key to encrypt the query results using SSE-KMS. The key must be in the same AWS Region as the destination Amazon S3 bucket.

1. In the **IAM role for posting query results to Amazon S3** section, choose one of the following options:

   1. Choose **Auto-create a new role with default permissions** to automatically set up an IAM role with the permissions required for CloudWatch Logs to deliver query results to Amazon S3.

   1. Choose **Use an existing role** to select an existing IAM role with the required policies for CloudWatch Logs to deliver query results to Amazon S3. Use the search field to find and select the appropriate IAM role from the list.

1. In the **IAM role for scheduled query execution** section, choose one of the following options:

   1. Choose **Auto-create a new role with default permissions** to automatically set up an IAM role with the permissions required for CloudWatch Logs to execute scheduled queries.

   1. Choose **Use an existing role** to select an existing IAM role with the required policies for CloudWatch Logs to execute scheduled queries. Use the search field to find and select the appropriate IAM role from the list.

1. Choose **Create schedule** to create the scheduled query.

------
#### [ AWS CLI ]

**To create a scheduled query (AWS CLI)**
+ Use the `create-scheduled-query` command to create a new scheduled query:

  ```
  aws logs create-scheduled-query \
      --name "ErrorAnalysisQuery" \
      --query-language "CWLI" \
      --query-string "fields @timestamp, @message | filter @message like /ERROR/ | stats count() by bin(5m)" \
      --schedule-expression "cron(8 * * * ? *)" \
      --execution-role-arn "arn:aws:iam::123456789012:role/CloudWatchLogsScheduledQueryRole" \
      --log-group-identifiers "/aws/lambda/my-function" "/aws/apigateway/my-api" \
      --state "ENABLED"
  ```

------
#### [ API ]

**To create a scheduled query (API)**
+ Use the `CreateScheduledQuery` action to create a new scheduled query. The following example creates a scheduled query that runs every hour:

  ```
  {
      "name": "ErrorAnalysisQuery",
      "queryLanguage": "CWLI",
      "queryString": "fields @timestamp, @message | filter @message like /ERROR/ | stats count() by bin(5m)",
      "scheduleExpression": "cron(8 * * * ? *)",
      "executionRoleArn": "arn:aws:iam::123456789012:role/CloudWatchLogsScheduledQueryRole",
      "logGroupIdentifiers": ["/aws/lambda/my-function", "/aws/apigateway/my-api"],
      "state": "ENABLED"
  }
  ```

------

After creating the scheduled query, you can view and manage it from the **Scheduled queries** page and using ListScheduledQueries API, which shows all your scheduled queries with their names, creation dates, status of last run, last triggered time, and repeat frequency.

# Viewing and managing scheduled queries
<a name="scheduled-queries-management"></a>

The following information is available for each query:

**Name**  
The unique name you assigned to the scheduled query. Select the name to view detailed configuration and execution history.

**Creation date**  
The date when the scheduled query was created, displayed in YYYY-MM-DD format.

**Status of last run**  
The execution status of the most recent query run. Possible values include:  
+ **Complete** - The query executed successfully and results were delivered to all configured destinations.
+ **Failed** - The query execution or result delivery failed. Check the execution history for error details.
+ **Invalid Query** - The query is invalid and has syntactical issues
+ **Timeout** - The query has timed out. A query times out automatically after 60 mins

**Last triggered time**  
The date and time when the query was last executed, displayed in YYYY-MM-DD HH:MM:SS format. Shows **Never** if the query has not yet run.

**Repeating every**  
The schedule frequency for the query. Shows **Custom** for queries using cron expressions or specific frequency descriptions for simpler schedules.

The **Scheduled queries** page provides an overview of all your scheduled queries, showing their current status and execution history so that you can view, monitor, and manage all your scheduled queries from a centralized location. Use this information to monitor query performance, identify issues, and manage your automated log analysis workflows.

------
#### [ Console ]

**To view scheduled queries (console)**

1. Open the CloudWatch Logs console at [https://us-east-1.console.aws.amazon.com/cloudwatch/home?region=us-east-1\$1logsV2:logs-insights](https://us-east-1.console.aws.amazon.com/cloudwatch/home?region=us-east-1#logsV2:logs-insights).

1. In the CloudWatch Logs console, choose **Scheduled query**, **View scheduled queries**.

------
#### [ AWS CLI ]

**To list scheduled queries (AWS CLI)**
+ Use the `list-scheduled-queries` command to list all scheduled queries:

  ```
  aws logs list-scheduled-queries --max-results 10
  ```

------
#### [ API ]

**To list scheduled queries (API)**
+ Use the `ListScheduledQueries` action to retrieve all scheduled queries:

  ```
  {
      "maxResults": 10
  }
  ```

------

The **Scheduled queries** page header shows the total number of scheduled queries in your account, helping you track your usage and manage your automated log analysis workflows effectively.

# Viewing scheduled query execution history
<a name="scheduled-queries-execution-history"></a>

Use the execution history to monitor the performance of your scheduled queries and troubleshoot any issues with query execution or result delivery.

The execution history shows the status of each query run, including successful executions, failures, and destination processing results. You can use this information to identify patterns, diagnose problems, and verify that your queries are running as expected.

------
#### [ Console ]

**To view execution history (console)**

1. In the CloudWatch Logs console, choose **Scheduled query**, **View scheduled queries**.

1. Select the scheduled query you want to examine.

1. Choose the **Execution history** tab.

------
#### [ AWS CLI ]

**To view execution history (AWS CLI)**

1. Use the `get-scheduled-query-history` command to retrieve execution history for a scheduled query:

   ```
   aws logs get-scheduled-query-history \
       --identifier "DailyErrorMonitoring" \
       --start-time 1743379200 \
       --end-time 1743465600 \
       --max-results 10
   ```

1. To filter by execution status, add the `--execution-statuses` parameter:

   ```
   aws logs get-scheduled-query-history \
       --identifier "DailyErrorMonitoring" \
       --start-time 1743379200 \
       --end-time 1743465600 \
       --max-results 1 \
       --execution-statuses "SUCCEEDED"
   ```

------
#### [ API ]

**To view execution history (API)**
+ Use the `GetScheduledQueryHistory` action to retrieve execution history:

  ```
  {
      "identifier": "DailyErrorMonitoring",
      "startTime": 1743379200,
      "endTime": 1743465600,
      "maxResults": 10,
      "executionStatuses": ["SUCCEEDED", "FAILED"]
  }
  ```

------

The execution history displays:
+ **Execution status** - Running, Complete, Failed, Timeout, or InvalidQuery
+ **Triggered time** - When the query was executed
+ **Destinations** - Processing status for each configured destination including S3 and EventBridge
+ **Error messages** - Details about any failures in query execution or destination processing

# Updating a scheduled query
<a name="scheduled-queries-updating"></a>

Modify your scheduled query configuration to change the query string, schedule, destinations, or execution role as your requirements evolve.

You can update any aspect of a scheduled query, including the query string, schedule expression, destinations, and execution role. Changes take effect immediately for future executions.

------
#### [ Console ]

**To update a scheduled query (console)**

1. In the CloudWatch Logs console, choose **Scheduled query**, **View scheduled queries**.

1. Select the scheduled query you want to update.

1. Choose **Edit**.

1. Modify the configuration as needed.

1. Choose **Save changes**.

------
#### [ AWS CLI ]

**To update a scheduled query (AWS CLI)**
+ Use the `update-scheduled-query` command to modify an existing scheduled query:

  ```
  aws logs update-scheduled-query \
      --identifier "arn:aws:logs:us-east-1:111122223333:scheduled-query:5e0c0228-1c29-4d26-904f-59f1f1ba3c8f" \
      --description "Monitor for ERROR level logs daily" \
      --query-language "LogsQL" \
      --query-string "fields @timestamp, @message | filter @message like /ERROR/" \
      --log-group-identifiers "/aws/lambda/my-function-1" "/aws/lambda/my-function-2"
  ```

------
#### [ API ]

**To update a scheduled query (API)**

1. Use the `UpdateScheduledQuery` action to modify scheduled query configuration:

   ```
   {
       "identifier": "arn:aws:logs:us-east-1:111122223333:scheduled-query:5e0c0228-1c29-4d26-904f-59f1f1ba3c8f",
       "queryString": "fields @timestamp, @message | filter @message like /WARNING|ERROR/ | stats count() by bin(5m)",
       "scheduleExpression": "cron(0 */2 * * ? *)",
       "state": "ENABLED"
   }
   ```

1. To update multiple configuration parameters at once:

   ```
   {
       "identifier": "arn:aws:logs:us-east-1:111122223333:scheduled-query:5e0c0228-1c29-4d26-904f-59f1f1ba3c8f",
       "queryString": "fields @timestamp, @message, @level | filter @level = 'ERROR'",
       "scheduleExpression": "cron(0 8,12,16 * * ? *)",
       "executionRoleArn": "arn:aws:iam::111122223333:role/UpdatedScheduledQueryRole",
       "logGroupIdentifiers": ["/aws/lambda/my-function", "/aws/lambda/another-function"],
       "destinationConfiguration": {
           "s3Configuration": {
               "destinationIdentifier": "s3://111122223333-sqn-results-bucket/processed-results",
               "roleArn": "arn:aws:iam::111122223333:role/Admin"
           }
       }
   }
   ```

------