Amazon CloudWatch Logs

Returns detailed information about a specified scheduled query, including its configuration, current state, and execution history.

See also: AWS API Documentation

Request Syntax

client.get_scheduled_query(
    identifier='string'
)

type identifier:

string

param identifier:

[REQUIRED]

The name or ARN of the scheduled query to retrieve.

rtype:

dict

returns:

Response Syntax

{
    'scheduledQueryArn': 'string',
    'name': 'string',
    'description': 'string',
    'queryLanguage': 'CWLI'|'SQL'|'PPL',
    'queryString': 'string',
    'logGroupIdentifiers': [
        'string',
    ],
    'scheduleExpression': 'string',
    'timezone': 'string',
    'startTimeOffset': 123,
    'destinationConfiguration': {
        's3Configuration': {
            'destinationIdentifier': 'string',
            'roleArn': 'string'
        }
    },
    'state': 'ENABLED'|'DISABLED',
    'lastTriggeredTime': 123,
    'lastExecutionStatus': 'Running'|'InvalidQuery'|'Complete'|'Failed'|'Timeout',
    'scheduleStartTime': 123,
    'scheduleEndTime': 123,
    'executionRoleArn': 'string',
    'creationTime': 123,
    'lastUpdatedTime': 123
}

Response Structure

• (dict) --

  • scheduledQueryArn (string) --

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

  • name (string) --

    The name of the scheduled query.

  • description (string) --

    The description of the scheduled query.

  • queryLanguage (string) --

    The query language used by the scheduled query (LogsQL, PPL, or SQL).

  • queryString (string) --

    The CloudWatch Logs Insights query string being executed.

  • logGroupIdentifiers (list) --

    The log group identifiers being queried by the scheduled query.

    • (string) --

  • scheduleExpression (string) --

    The cron expression that defines when the scheduled query runs.

  • timezone (string) --

    The timezone in which the schedule expression is evaluated.

  • startTimeOffset (integer) --

    Time offset in seconds from the execution time for the start of the query time range.

  • destinationConfiguration (dict) --

    Configuration for destinations where the query results are delivered.

    • s3Configuration (dict) --

      Configuration for delivering query results to an Amazon S3 bucket.

      • destinationIdentifier (string) --

        The S3 URI where query results will be stored (e.g., s3://bucket-name/prefix/).

      • roleArn (string) --

        The ARN of the IAM role that CloudWatch Logs will assume to write results to the S3 bucket.

  • state (string) --

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

  • lastTriggeredTime (integer) --

    The time when the scheduled query was last executed, in Unix epoch time.

  • lastExecutionStatus (string) --

    The status of the last executed query (Running, Complete, Failed, Timeout, or InvalidQuery).

  • scheduleStartTime (integer) --

    The start time for the query schedule in Unix epoch time.

  • scheduleEndTime (integer) --

    The end time for the query schedule in Unix epoch time.

  • executionRoleArn (string) --

    The ARN of the IAM role used to execute the scheduled query.

  • creationTime (integer) --

    The time when the scheduled query was created, in Unix epoch time.

  • lastUpdatedTime (integer) --

    The time when the scheduled query was last updated, in Unix epoch time.

Deletes an existing scheduled query and all its associated configurations. This operation permanently removes the scheduled query and cannot be undone.

See also: AWS API Documentation

Request Syntax

client.delete_scheduled_query(
    identifier='string'
)

type identifier:

string

param identifier:

[REQUIRED]

The name or ARN of the scheduled query to delete.

rtype:

dict

returns:

Response Syntax

{}

Response Structure

• (dict) --

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

See also: AWS API Documentation

Request Syntax

client.create_scheduled_query(
    name='string',
    description='string',
    queryLanguage='CWLI'|'SQL'|'PPL',
    queryString='string',
    logGroupIdentifiers=[
        'string',
    ],
    scheduleExpression='string',
    timezone='string',
    startTimeOffset=123,
    destinationConfiguration={
        's3Configuration': {
            'destinationIdentifier': 'string',
            'roleArn': 'string'
        }
    },
    scheduleStartTime=123,
    scheduleEndTime=123,
    executionRoleArn='string',
    state='ENABLED'|'DISABLED',
    tags={
        'string': 'string'
    }
)

type name:

string

param name:

[REQUIRED]

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 description:

string

param description:

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

type queryLanguage:

string

param queryLanguage:

[REQUIRED]

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 queryString:

string

param queryString:

[REQUIRED]

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 logGroupIdentifiers:

list

param 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.

• (string) --

type scheduleExpression:

string

param scheduleExpression:

[REQUIRED]

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 timezone:

string

param timezone:

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

type startTimeOffset:

integer

param 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 destinationConfiguration:

dict

param 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.

• s3Configuration (dict) -- [REQUIRED]

  Configuration for delivering query results to an Amazon S3 bucket.

  • destinationIdentifier (string) -- [REQUIRED]

    The S3 URI where query results will be stored (e.g., s3://bucket-name/prefix/).

  • roleArn (string) -- [REQUIRED]

    The ARN of the IAM role that CloudWatch Logs will assume to write results to the S3 bucket.

type scheduleStartTime:

integer

param 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 scheduleEndTime:

integer

param 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 executionRoleArn:

string

param executionRoleArn:

[REQUIRED]

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 state:

string

param 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 tags:

dict

param tags:

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

For more information about tagging, see Tagging Amazon Web Services resources

• (string) --

  • (string) --

rtype:

dict

returns:

Response Syntax

{
    'scheduledQueryArn': 'string',
    'state': 'ENABLED'|'DISABLED'
}

Response Structure

• (dict) --

  • scheduledQueryArn (string) --

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

  • state (string) --

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

Updates the configuration of an existing scheduled query. This operation follows PUT semantics, replacing the existing configuration with the provided values.

See also: AWS API Documentation

Request Syntax

client.update_scheduled_query(
    identifier='string',
    description='string',
    queryLanguage='CWLI'|'SQL'|'PPL',
    queryString='string',
    logGroupIdentifiers=[
        'string',
    ],
    scheduleExpression='string',
    timezone='string',
    startTimeOffset=123,
    destinationConfiguration={
        's3Configuration': {
            'destinationIdentifier': 'string',
            'roleArn': 'string'
        }
    },
    scheduleStartTime=123,
    scheduleEndTime=123,
    executionRoleArn='string',
    state='ENABLED'|'DISABLED'
)

type identifier:

string

param identifier:

[REQUIRED]

The name or ARN of the scheduled query to update.

type description:

string

param description:

Updated description for the scheduled query.

type queryLanguage:

string

param queryLanguage:

[REQUIRED]

Updated query language to use (LogsQL, PPL, or SQL).

type queryString:

string

param queryString:

[REQUIRED]

Updated CloudWatch Logs Insights query string to execute.

type logGroupIdentifiers:

list

param logGroupIdentifiers:

Updated log group identifiers to query.

• (string) --

type scheduleExpression:

string

param scheduleExpression:

[REQUIRED]

Updated cron expression that defines when the scheduled query runs.

type timezone:

string

param timezone:

Updated timezone in which the schedule expression is evaluated.

type startTimeOffset:

integer

param startTimeOffset:

Updated time offset in seconds from the execution time for the start of the query time range.

type destinationConfiguration:

dict

param destinationConfiguration:

Updated configuration for destinations where the query results will be delivered.

• s3Configuration (dict) -- [REQUIRED]

  Configuration for delivering query results to an Amazon S3 bucket.

  • destinationIdentifier (string) -- [REQUIRED]

    The S3 URI where query results will be stored (e.g., s3://bucket-name/prefix/).

  • roleArn (string) -- [REQUIRED]

    The ARN of the IAM role that CloudWatch Logs will assume to write results to the S3 bucket.

type scheduleStartTime:

integer

param scheduleStartTime:

Updated start time for the query schedule in Unix epoch time.

type scheduleEndTime:

integer

param scheduleEndTime:

Updated end time for the query schedule in Unix epoch time.

type executionRoleArn:

string

param executionRoleArn:

[REQUIRED]

Updated ARN of the IAM role that CloudWatch Logs will assume to execute the scheduled query.

type state:

string

param state:

Updated state of the scheduled query (ENABLED or DISABLED).

rtype:

dict

returns:

Response Syntax

{
    'scheduledQueryArn': 'string',
    'name': 'string',
    'description': 'string',
    'queryLanguage': 'CWLI'|'SQL'|'PPL',
    'queryString': 'string',
    'logGroupIdentifiers': [
        'string',
    ],
    'scheduleExpression': 'string',
    'timezone': 'string',
    'startTimeOffset': 123,
    'destinationConfiguration': {
        's3Configuration': {
            'destinationIdentifier': 'string',
            'roleArn': 'string'
        }
    },
    'state': 'ENABLED'|'DISABLED',
    'lastTriggeredTime': 123,
    'lastExecutionStatus': 'Running'|'InvalidQuery'|'Complete'|'Failed'|'Timeout',
    'scheduleStartTime': 123,
    'scheduleEndTime': 123,
    'executionRoleArn': 'string',
    'creationTime': 123,
    'lastUpdatedTime': 123
}

Response Structure

• (dict) --

  • scheduledQueryArn (string) --

    The ARN of the updated scheduled query.

  • name (string) --

    The name of the updated scheduled query.

  • description (string) --

    The description of the updated scheduled query.

  • queryLanguage (string) --

    The query language used by the updated scheduled query.

  • queryString (string) --

    The query string of the updated scheduled query.

  • logGroupIdentifiers (list) --

    The log group identifiers of the updated scheduled query.

    • (string) --

  • scheduleExpression (string) --

    The schedule expression of the updated scheduled query.

  • timezone (string) --

    The timezone of the updated scheduled query.

  • startTimeOffset (integer) --

    The start time offset of the updated scheduled query.

  • destinationConfiguration (dict) --

    The destination configuration of the updated scheduled query.

    • s3Configuration (dict) --

      Configuration for delivering query results to an Amazon S3 bucket.

      • destinationIdentifier (string) --

        The S3 URI where query results will be stored (e.g., s3://bucket-name/prefix/).

      • roleArn (string) --

        The ARN of the IAM role that CloudWatch Logs will assume to write results to the S3 bucket.

  • state (string) --

    The state of the updated scheduled query.

  • lastTriggeredTime (integer) --

    The time when the updated scheduled query was last executed.

  • lastExecutionStatus (string) --

    The status of the last execution of the updated scheduled query (Running, Complete, Failed, Timeout, or InvalidQuery).

  • scheduleStartTime (integer) --

    The schedule start time of the updated scheduled query.

  • scheduleEndTime (integer) --

    The schedule end time of the updated scheduled query.

  • executionRoleArn (string) --

    The execution role ARN of the updated scheduled query.

  • creationTime (integer) --

    The creation time of the updated scheduled query.

  • lastUpdatedTime (integer) --

    The last updated time of the scheduled query.

Lists all scheduled queries in the current AWS account and region with optional filtering by state.

See also: AWS API Documentation

Request Syntax

client.list_scheduled_queries(
    maxResults=123,
    nextToken='string',
    state='ENABLED'|'DISABLED'
)

type maxResults:

integer

param maxResults:

The maximum number of scheduled queries to return in a single call.

type nextToken:

string

param nextToken:

The token for the next set of items to return. The token expires after 24 hours.

type state:

string

param state:

Filter results by the state of scheduled queries (ENABLED or DISABLED).

rtype:

dict

returns:

Response Syntax

{
    'nextToken': 'string',
    'scheduledQueries': [
        {
            'scheduledQueryArn': 'string',
            'name': 'string',
            'state': 'ENABLED'|'DISABLED',
            'lastTriggeredTime': 123,
            'lastExecutionStatus': 'Running'|'InvalidQuery'|'Complete'|'Failed'|'Timeout',
            'scheduleExpression': 'string',
            'timezone': 'string',
            'destinationConfiguration': {
                's3Configuration': {
                    'destinationIdentifier': 'string',
                    'roleArn': 'string'
                }
            },
            'creationTime': 123,
            'lastUpdatedTime': 123
        },
    ]
}

Response Structure

• (dict) --

  • nextToken (string) --

    The token for the next set of items to return. The token expires after 24 hours.

  • scheduledQueries (list) --

    The list of scheduled queries with summary information.

    • (dict) --

      Summary information about a scheduled query, used in list operations.

      • scheduledQueryArn (string) --

        The ARN of the scheduled query.

      • name (string) --

        The name of the scheduled query.

      • state (string) --

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

      • lastTriggeredTime (integer) --

        The time when the scheduled query was last executed.

      • lastExecutionStatus (string) --

        The status of the last execution (Running, Complete, Failed, Timeout, or InvalidQuery).

      • scheduleExpression (string) --

        The cron expression that defines when the scheduled query runs.

      • timezone (string) --

        The timezone in which the schedule expression is evaluated.

      • destinationConfiguration (dict) --

        Configuration for destinations where the query results are delivered.

        • s3Configuration (dict) --

          Configuration for delivering query results to an Amazon S3 bucket.

          • destinationIdentifier (string) --

            The S3 URI where query results will be stored (e.g., s3://bucket-name/prefix/).

          • roleArn (string) --

            The ARN of the IAM role that CloudWatch Logs will assume to write results to the S3 bucket.

      • creationTime (integer) --

        The time when the scheduled query was created.

      • lastUpdatedTime (integer) --

        The time when the scheduled query was last updated.

Retrieves the execution history of a scheduled query within a specified time range, including execution status and destination processing metadata.

See also: AWS API Documentation

Request Syntax

client.get_scheduled_query_history(
    identifier='string',
    startTime=123,
    endTime=123,
    executionStatuses=[
        'Running'|'InvalidQuery'|'Complete'|'Failed'|'Timeout',
    ],
    maxResults=123,
    nextToken='string'
)

type identifier:

string

param identifier:

[REQUIRED]

The name or ARN of the scheduled query to retrieve history for.

type startTime:

integer

param startTime:

[REQUIRED]

The start time for the history retrieval window in Unix epoch time.

type endTime:

integer

param endTime:

[REQUIRED]

The end time for the history retrieval window in Unix epoch time.

type executionStatuses:

list

param executionStatuses:

Filter results by execution status (Running, Complete, Failed, Timeout, or InvalidQuery).

• (string) --

type maxResults:

integer

param maxResults:

The maximum number of history records to return in a single call.

type nextToken:

string

param nextToken:

The token for the next set of items to return. The token expires after 24 hours.

rtype:

dict

returns:

Response Syntax

{
    'name': 'string',
    'scheduledQueryArn': 'string',
    'triggerHistory': [
        {
            'queryId': 'string',
            'executionStatus': 'Running'|'InvalidQuery'|'Complete'|'Failed'|'Timeout',
            'triggeredTimestamp': 123,
            'errorMessage': 'string',
            'destinations': [
                {
                    'destinationType': 'S3',
                    'destinationIdentifier': 'string',
                    'status': 'IN_PROGRESS'|'CLIENT_ERROR'|'FAILED'|'COMPLETE',
                    'processedIdentifier': 'string',
                    'errorMessage': 'string'
                },
            ]
        },
    ],
    'nextToken': 'string'
}

Response Structure

• (dict) --

  • name (string) --

    The name of the scheduled query.

  • scheduledQueryArn (string) --

    The ARN of the scheduled query.

  • triggerHistory (list) --

    The list of execution history records for the scheduled query.

    • (dict) --

      A record of a scheduled query execution, including its status and destination processing information.

      • queryId (string) --

        The unique identifier for the query execution.

      • executionStatus (string) --

        The status of the query execution (SUCCEEDED, FAILED, TIMEOUT, or INVALID_QUERY).

      • triggeredTimestamp (integer) --

        The time when the scheduled query was triggered, in Unix epoch time.

      • errorMessage (string) --

        The error message if the scheduled query execution failed. This field is only populated when the execution status indicates a failure.

      • destinations (list) --

        The list of destinations where the scheduled query results were delivered for this execution. This includes S3 buckets and EventBridge targets configured for the scheduled query.

        • (dict) --

          Information about a destination where scheduled query results are processed and delivered.

          • destinationType (string) --

            The type of destination (S3 or EVENTBRIDGE).

          • destinationIdentifier (string) --

            The destination identifier (S3 URI or EventBridge ARN).

          • status (string) --

            The processing status for this destination (IN_PROGRESS, ERROR, FAILED, or COMPLETE).

          • processedIdentifier (string) --

            The processed identifier returned for the destination (S3 key or event ID).

          • errorMessage (string) --

            Error message if the destination processing failed.

  • nextToken (string) --

    The token for the next set of items to return. The token expires after 24 hours.