CloudWatchLogs / Client / describe_log_groups



Lists the specified log groups. You can list all your log groups or filter the results by prefix. The results are ASCII-sorted by log group name.

CloudWatch Logs doesn’t support IAM policies that control access to the DescribeLogGroups action by using the aws:ResourceTag/key-name condition key. Other CloudWatch Logs actions do support the use of the aws:ResourceTag/key-name condition key to control access. For more information about using tags to control access, see Controlling access to Amazon Web Services resources using tags.

If you are using CloudWatch cross-account observability, you can use this operation in a monitoring account and view data from the linked source accounts. For more information, see CloudWatch cross-account observability.

See also: AWS API Documentation

Request Syntax

response = client.describe_log_groups(
  • accountIdentifiers (list) –

    When includeLinkedAccounts is set to True, use this parameter to specify the list of accounts to search. You can specify as many as 20 account IDs in the array.

    • (string) –

  • logGroupNamePrefix (string) –

    The prefix to match.


    logGroupNamePrefix and logGroupNamePattern are mutually exclusive. Only one of these parameters can be passed.

  • logGroupNamePattern (string) –

    If you specify a string for this parameter, the operation returns only log groups that have names that match the string based on a case-sensitive substring search. For example, if you specify Foo, log groups named FooBar, aws/Foo, and GroupFoo would match, but foo, F/o/o and Froo would not match.

    If you specify logGroupNamePattern in your request, then only arn, creationTime, and logGroupName are included in the response.


    logGroupNamePattern and logGroupNamePrefix are mutually exclusive. Only one of these parameters can be passed.

  • nextToken (string) – The token for the next set of items to return. (You received this token from a previous call.)

  • limit (integer) – The maximum number of items returned. If you don’t specify a value, the default is up to 50 items.

  • includeLinkedAccounts (boolean) –

    If you are using a monitoring account, set this to True to have the operation return log groups in the accounts listed in accountIdentifiers.

    If this parameter is set to true and accountIdentifiers contains a null value, the operation returns all log groups in the monitoring account and all log groups in all source accounts that are linked to the monitoring account.

Return type:



Response Syntax

    'logGroups': [
            'logGroupName': 'string',
            'creationTime': 123,
            'retentionInDays': 123,
            'metricFilterCount': 123,
            'arn': 'string',
            'storedBytes': 123,
            'kmsKeyId': 'string',
            'dataProtectionStatus': 'ACTIVATED'|'DELETED'|'ARCHIVED'|'DISABLED',
            'inheritedProperties': [
    'nextToken': 'string'

Response Structure

  • (dict) –

    • logGroups (list) –

      The log groups.

      If the retentionInDays value is not included for a log group, then that log group’s events do not expire.

      • (dict) –

        Represents a log group.

        • logGroupName (string) –

          The name of the log group.

        • creationTime (integer) –

          The creation time of the log group, expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC.

        • retentionInDays (integer) –

          The number of days to retain the log events in the specified log group. Possible values are: 1, 3, 5, 7, 14, 30, 60, 90, 120, 150, 180, 365, 400, 545, 731, 1096, 1827, 2192, 2557, 2922, 3288, and 3653.

          To set a log group so that its log events do not expire, use DeleteRetentionPolicy.

        • metricFilterCount (integer) –

          The number of metric filters.

        • arn (string) –

          The Amazon Resource Name (ARN) of the log group.

        • storedBytes (integer) –

          The number of bytes stored.

        • kmsKeyId (string) –

          The Amazon Resource Name (ARN) of the KMS key to use when encrypting log data.

        • dataProtectionStatus (string) –

          Displays whether this log group has a protection policy, or whether it had one in the past. For more information, see PutDataProtectionPolicy.

        • inheritedProperties (list) –

          Displays all the properties that this log group has inherited from account-level settings.

          • (string) –

    • nextToken (string) –

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


  • CloudWatchLogs.Client.exceptions.InvalidParameterException

  • CloudWatchLogs.Client.exceptions.ServiceUnavailableException