Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.1.0
info:
title: Amazon CloudWatch Log Group API
version: '2010-08-01'
description: Generated from AWS's published Smithy model for Amazon CloudWatch. 7 operation(s).
contact:
name: Amazon Web Services
url: https://aws.amazon.com/contact-us/
license:
name: Apache 2.0
identifier: Apache-2.0
url: https://github.com/aws/api-models-aws/blob/main/LICENSE
servers:
- url: https://logs.{region}.amazonaws.com
variables:
region:
default: us-east-1
security:
- sigv4: []
paths:
/#CreateLogGroup:
post:
operationId: CreateLogGroup
summary: Create Log Group
description: 'Creates a log group with the specified name. You can create up to 1,000,000 log groups per Region per
account. You must use the following guidelines when naming a log group: Log group names must be unique within a Region
for an Amazon Web Services account. Log group names can be between 1 and 512 characters long. Log group names consist
of the following characters: a-z, A-Z, 0-9, ''_'' (underscore), ''-'' (hyphen), ''/'' (forward slash), ''.'' (period),
and ''#'' (number sign) Log group names can''t start with the string aws/ When you create a log group, by default
the log events in the log group do not expire. To set a retention policy so that events expire and are deleted after
a specified time, use PutRetentionPolicy. If you associate an KMS key with the log group, ingested data is encrypted
using the KMS key. This association is stored as long as the data encrypted with the KMS key is still within CloudWatch
Logs. This enables CloudWatch Logs to decrypt this data whenever it is requested. If you attempt to associate a KMS
key with the log group but the KMS key does not exist or the KMS key is disabled, you receive an InvalidParameterException
error. CloudWatch Logs supports only symmetric'
responses:
'200':
description: Success
content:
application/x-amz-json-1.1:
schema:
type: string
'400':
description: InvalidParameterException; LimitExceededException; OperationAbortedException; ResourceAlreadyExistsException
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/InvalidParameterException'
'500':
description: ServiceUnavailableException
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/ServiceUnavailableException'
parameters:
- name: X-Amz-Target
in: header
required: true
schema:
type: string
enum:
- Logs_20140328.CreateLogGroup
requestBody:
required: true
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/CreateLogGroupRequest'
tags:
- Log Group
/#DeleteLogGroup:
post:
operationId: DeleteLogGroup
summary: Delete Log Group
description: Deletes the specified log group and permanently deletes all the archived log events associated with the
log group.
responses:
'200':
description: Success
content:
application/x-amz-json-1.1:
schema:
type: string
'400':
description: InvalidParameterException; OperationAbortedException; ResourceNotFoundException; ValidationException
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/InvalidParameterException'
'500':
description: ServiceUnavailableException
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/ServiceUnavailableException'
parameters:
- name: X-Amz-Target
in: header
required: true
schema:
type: string
enum:
- Logs_20140328.DeleteLogGroup
requestBody:
required: true
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/DeleteLogGroupRequest'
tags:
- Log Group
/#DescribeLogGroups:
post:
operationId: DescribeLogGroups
summary: Describe Log Groups
description: Returns information about log groups, including data sources that ingest into each log group. You can return
all your log groups or filter the results by prefix. The results are ASCII-sorted by log group name. If an account-level
retention policy applies to a log group, retentionInDays shows the retention period from that policy, and retentionPolicyName
shows the name of the policy. 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.
responses:
'200':
description: Success
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/DescribeLogGroupsResponse'
'400':
description: InvalidParameterException
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/InvalidParameterException'
'500':
description: ServiceUnavailableException
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/ServiceUnavailableException'
parameters:
- name: X-Amz-Target
in: header
required: true
schema:
type: string
enum:
- Logs_20140328.DescribeLogGroups
requestBody:
required: true
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/DescribeLogGroupsRequest'
tags:
- Log Group
/#ListLogGroups:
post:
operationId: ListLogGroups
summary: List Log Groups
description: Returns a list of log groups in the Region in your account. If you are performing this action in a monitoring
account, you can choose to also return log groups from source accounts that are linked to the monitoring account.
For more information about using cross-account observability to set up monitoring accounts and source accounts, see
CloudWatch cross-account observability. You can optionally filter the results by log group class, log group name pattern,
field indexes, data sources, field index names, or log group tags. If you specify more than one filter type, the results
include log groups that satisfy all filters. This operation is paginated. By default, your first use of this operation
returns 50 results, and includes a token to use in a subsequent operation to return more results.
responses:
'200':
description: Success
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/ListLogGroupsResponse'
'400':
description: InvalidParameterException
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/InvalidParameterException'
'500':
description: ServiceUnavailableException
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/ServiceUnavailableException'
parameters:
- name: X-Amz-Target
in: header
required: true
schema:
type: string
enum:
- Logs_20140328.ListLogGroups
requestBody:
required: true
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/ListLogGroupsRequest'
tags:
- Log Group
/#ListLogGroupsForQuery:
post:
operationId: ListLogGroupsForQuery
summary: List Log Groups For Query
description: Returns a list of the log groups that were analyzed during a single CloudWatch Logs Insights query. This
can be useful for queries that use log group name prefixes or the filterIndex command, because the log groups are
dynamically selected in these cases. For more information about field indexes, see Create field indexes to improve
query performance and reduce costs.
responses:
'200':
description: Success
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/ListLogGroupsForQueryResponse'
'400':
description: AccessDeniedException; InvalidParameterException; ResourceNotFoundException
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/AccessDeniedException'
'500':
description: ServiceUnavailableException
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/ServiceUnavailableException'
parameters:
- name: X-Amz-Target
in: header
required: true
schema:
type: string
enum:
- Logs_20140328.ListLogGroupsForQuery
requestBody:
required: true
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/ListLogGroupsForQueryRequest'
tags:
- Log Group
/#TagLogGroup:
post:
operationId: TagLogGroup
summary: Tag Log Group
description: The TagLogGroup operation is on the path to deprecation. We recommend that you use TagResource instead.
Adds or updates the specified tags for the specified log group. To list the tags for a log group, use ListTagsForResource.
To remove tags, use UntagResource. For more information about tags, see Tag Log Groups in Amazon CloudWatch Logs in
the Amazon CloudWatch Logs User Guide. CloudWatch Logs doesn't support IAM policies that prevent users from assigning
specified tags to log groups using the aws:Resource/key-name or aws:TagKeys condition keys. For more information about
using tags to control access, see Controlling access to Amazon Web Services resources using tags.
responses:
'200':
description: Success
content:
application/x-amz-json-1.1:
schema:
type: string
'400':
description: InvalidParameterException; ResourceNotFoundException
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/InvalidParameterException'
deprecated: true
parameters:
- name: X-Amz-Target
in: header
required: true
schema:
type: string
enum:
- Logs_20140328.TagLogGroup
requestBody:
required: true
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/TagLogGroupRequest'
tags:
- Log Group
/#UntagLogGroup:
post:
operationId: UntagLogGroup
summary: Untag Log Group
description: The UntagLogGroup operation is on the path to deprecation. We recommend that you use UntagResource instead.
Removes the specified tags from the specified log group. To list the tags for a log group, use ListTagsForResource.
To add tags, use TagResource. When using IAM policies to control tag management for CloudWatch Logs log groups, the
condition keys aws:Resource/key-name and aws:TagKeys cannot be used to restrict which tags users can assign.
responses:
'200':
description: Success
content:
application/x-amz-json-1.1:
schema:
type: string
'400':
description: ResourceNotFoundException
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/LogsResourceNotFoundException'
deprecated: true
parameters:
- name: X-Amz-Target
in: header
required: true
schema:
type: string
enum:
- Logs_20140328.UntagLogGroup
requestBody:
required: true
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/UntagLogGroupRequest'
tags:
- Log Group
components:
securitySchemes:
sigv4:
type: apiKey
in: header
name: Authorization
description: AWS Signature Version 4. The Authorization header carries an AWS4-HMAC-SHA256 signature over the canonical
request, with X-Amz-Date (and X-Amz-Security-Token for temporary credentials). Not a bearer token.
x-aws-sigv4:
signingName: logs
schemas:
AccessDeniedException:
type: object
properties:
message:
type: string
CreateLogGroupRequest:
type: object
properties:
logGroupName:
type: string
description: A name for the log group.
kmsKeyId:
type: string
description: The Amazon Resource Name (ARN) of the KMS key to use when encrypting log data. For more information,
see Amazon Resource Names.
tags:
type: object
additionalProperties:
type: string
description: The key-value pairs to use for the tags. You can grant users access to certain log groups while preventing
them from accessing other log groups. To do so, tag your groups and use IAM policies that refer to those tags.
To assign tags when you create a log group, you must have either the logs:TagResource or logs:TagLogGroup permission.
For more information about tagging, see Tagging Amazon Web Services resources. For more information about using
tags to control access, see Controlling access to Amazon Web Services resources using tags.
logGroupClass:
type: string
enum:
- STANDARD
- INFREQUENT_ACCESS
- DELIVERY
- ESSENTIALS
description: 'Use this parameter to specify the log group class for this log group. There are four classes: The
Standard log class supports all CloudWatch Logs features. The Infrequent Access log class supports a subset of
CloudWatch Logs features and incurs lower costs. The Essentials log class supports a subset of CloudWatch Logs
features and incurs lower costs. Use the Delivery log class only for delivering Lambda logs to store in Amazon
S3 or Amazon Data Firehose. Log events in log groups in the Delivery class are kept in CloudWatch Logs for only
one day. This log class doesn''t offer rich CloudWatch Log'
deletionProtectionEnabled:
type: boolean
description: Use this parameter to enable deletion protection for the new log group. When enabled on a log group,
deletion protection blocks all deletion operations until it is explicitly disabled. By default log groups are
created without deletion protection enabled.
required:
- logGroupName
DataSourceFilter:
type: object
properties:
name:
type: string
description: The name pattern to filter data sources by.
type:
type: string
description: The type pattern to filter data sources by.
required:
- name
DeleteLogGroupRequest:
type: object
properties:
logGroupName:
type: string
description: The name of the log group.
required:
- logGroupName
DescribeLogGroupsRequest:
type: object
properties:
accountIdentifiers:
type: array
items:
type: string
description: 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.
logGroupNamePrefix:
type: string
description: The prefix to match. logGroupNamePrefix and logGroupNamePattern are mutually exclusive. Only one of
these parameters can be passed.
logGroupNamePattern:
type: string
description: 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 DataLogs, log groups
named DataLogs, aws/DataLogs, and GroupDataLogs would match, but datalogs, Data/log/s and Groupdata 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:
type: string
description: The token for the next set of items to return. (You received this token from a previous call.)
limit:
type: integer
description: The maximum number of items returned. If you don't specify a value, the default is up to 50 items.
includeLinkedAccounts:
type: boolean
description: 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. The default for this parameter is false.
logGroupClass:
type: string
enum:
- STANDARD
- INFREQUENT_ACCESS
- DELIVERY
- ESSENTIALS
description: 'Use this parameter to limit the results to only those log groups in the specified log group class.
If you omit this parameter, log groups of all classes can be returned. If you specify either INFREQUENT_ACCESS
or ESSENTIALS, the results include log groups in both the Infrequent Access and Essentials log classes. Specifies
the log group class for this log group. There are four classes: The Standard log class supports all CloudWatch
Logs features. The Infrequent Access log class supports a subset of CloudWatch Logs features and incurs lower
costs. The Essentials log class supports a subset of Cl'
logGroupIdentifiers:
type: array
items:
type: string
description: Use this array to filter the list of log groups returned. If you specify this parameter, the only other
filter that you can choose to specify is includeLinkedAccounts. If you are using this operation in a monitoring
account, you can specify the ARNs of log groups in source accounts and in the monitoring account itself. If you
are using this operation in an account that is not a cross-account monitoring account, you can specify only log
group names in the same account as the operation.
DescribeLogGroupsResponse:
type: object
properties:
logGroups:
type: array
items:
$ref: '#/components/schemas/LogGroup'
description: An array of structures, where each structure contains the information about one log group.
nextToken:
type: string
InvalidParameterException:
type: object
properties:
message:
type: string
ListLogGroupsForQueryRequest:
type: object
properties:
queryId:
type: string
description: The ID of the query to use. This query ID is from the response to your StartQuery operation.
nextToken:
type: string
maxResults:
type: integer
description: Limits the number of returned log groups to the specified number.
required:
- queryId
ListLogGroupsForQueryResponse:
type: object
properties:
logGroupIdentifiers:
type: array
items:
type: string
description: An array of the names and ARNs of the log groups that were processed in the query.
nextToken:
type: string
ListLogGroupsRequest:
type: object
properties:
logGroupNamePattern:
type: string
description: 'Use this parameter to limit the returned log groups to only those with names that match the pattern
that you specify. This parameter is a regular expression that can match prefixes and substrings, and supports
wildcard matching and matching multiple patterns, as in the following examples. Use ^ to match log group names
by prefix. For a substring match, specify the string to match. All matches are case sensitive To match multiple
patterns, separate them with a | as in the example ^/aws/lambda|discovery You can specify as many as five different
regular expression patterns in this field, each of '
logGroupClass:
type: string
enum:
- STANDARD
- INFREQUENT_ACCESS
- DELIVERY
- ESSENTIALS
description: Use this parameter to limit the results to only those log groups in the specified log group class.
If you omit this parameter, log groups of all classes can be returned.
includeLinkedAccounts:
type: boolean
description: 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. The default for this parameter is false.
accountIdentifiers:
type: array
items:
type: string
description: 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.
nextToken:
type: string
limit:
type: integer
description: The maximum number of log groups to return. If you omit this parameter, the default is up to 50 log
groups.
dataSources:
type: array
items:
$ref: '#/components/schemas/DataSourceFilter'
description: An array of data source filters to filter log groups by their associated data sources. You can filter
by data source name, type, or both. Multiple filters within the same dimension are combined with OR logic, while
filters across different dimensions are combined with AND logic.
fieldIndexNames:
type: array
items:
type: string
description: An array of field index names to filter log groups that have specific field indexes. Only log groups
containing all specified field indexes are returned. You can specify 1 to 20 field index names, each with 1 to
512 characters.
logGroupTags:
type: array
items:
$ref: '#/components/schemas/TagFilter'
description: An array of tag filters to return only log groups that have specific tags. Multiple filters are combined
with AND logic.
ListLogGroupsResponse:
type: object
properties:
logGroups:
type: array
items:
$ref: '#/components/schemas/LogGroupSummary'
description: An array of structures, where each structure contains the information about one log group.
nextToken:
type: string
LogGroup:
type: object
properties:
logGroupName:
type: string
description: The name of the log group.
creationTime:
type: integer
description: The creation time of the log group, expressed as the number of milliseconds after Jan 1, 1970 00:00:00
UTC.
retentionInDays:
type: integer
metricFilterCount:
type: integer
description: The number of metric filters.
arn:
type: string
description: The Amazon Resource Name (ARN) of the log group. This version of the ARN includes a trailing :* after
the log group name. Use this version to refer to the ARN in IAM policies when specifying permissions for most
API actions. The exception is when specifying permissions for TagResource, UntagResource, and ListTagsForResource.
The permissions for those three actions require the ARN version that doesn't include a trailing :*.
storedBytes:
type: integer
description: The number of bytes stored.
kmsKeyId:
type: string
description: The Amazon Resource Name (ARN) of the KMS key to use when encrypting log data.
dataProtectionStatus:
type: string
enum:
- ACTIVATED
- DELETED
- ARCHIVED
- DISABLED
description: Displays whether this log group has a protection policy, or whether it had one in the past. For more
information, see PutDataProtectionPolicy.
inheritedProperties:
type: array
items:
type: string
enum:
- ACCOUNT_DATA_PROTECTION
description: Displays all the properties that this log group has inherited from account-level settings.
logGroupClass:
type: string
enum:
- STANDARD
- INFREQUENT_ACCESS
- DELIVERY
- ESSENTIALS
description: 'This specifies the log group class for this log group. There are four classes: The Standard log class
supports all CloudWatch Logs features. The Infrequent Access log class supports a subset of CloudWatch Logs features
and incurs lower costs. The Essentials log class supports a subset of CloudWatch Logs features and incurs lower
costs. Use the Delivery log class only for delivering Lambda logs to store in Amazon S3 or Amazon Data Firehose.
Log events in log groups in the Delivery class are kept in CloudWatch Logs for only one day. This log class doesn''t
offer rich CloudWatch Logs capabilities '
logGroupArn:
type: string
description: 'The Amazon Resource Name (ARN) of the log group. This version of the ARN doesn''t include a trailing
:* after the log group name. Use this version to refer to the ARN in the following situations: In the logGroupIdentifier
input field in many CloudWatch Logs APIs. In the resourceArn field in tagging APIs In IAM policies, when specifying
permissions for TagResource, UntagResource, and ListTagsForResource.'
deletionProtectionEnabled:
type: boolean
description: Indicates whether deletion protection is enabled for this log group. When enabled, deletion protection
blocks all deletion operations until it is explicitly disabled.
bearerTokenAuthenticationEnabled:
type: boolean
description: Indicates whether bearer token authentication is enabled for this log group. When enabled, bearer token
authentication is allowed on operations until it is explicitly disabled.
retentionPolicyName:
type: string
description: The name of the account-level retention policy that determines the retention period of this log group.
This field is returned only when an account-level retention policy applies to the log group. When it is returned,
retentionInDays shows the retention period from that policy instead of the retention period set on the log group.
If the policy specifies that log events never expire, retentionInDays is not returned.
LogGroupSummary:
type: object
properties:
logGroupName:
type: string
description: The name of the log group.
logGroupArn:
type: string
description: The Amazon Resource Name (ARN) of the log group.
logGroupClass:
type: string
enum:
- STANDARD
- INFREQUENT_ACCESS
- DELIVERY
- ESSENTIALS
description: The log group class for this log group. For details about the features supported by each log group
class, see Log classes
LogsResourceNotFoundException:
type: object
properties:
message:
type: string
ServiceUnavailableException:
type: object
properties:
message:
type: string
TagFilter:
type: object
properties:
key:
type: string
description: The tag key to filter on.
values:
type: array
items:
type: string
description: An optional list of tag values to filter on. If you specify a filter that contains more than one value
for a key, the response returns log groups that match any of the specified values for that key. If you don't specify
values, the response returns all log groups that are tagged with that key, with any or no value. Use * for wildcard
matching. For example, prod* matches values that start with prod. Use ! as a prefix for negation. For example,
!prod matches values that are not prod. Exact matching and negation are case-sensitive. Wildcard matching is case-insensitive.
required:
- key
TagLogGroupRequest:
type: object
properties:
logGroupName:
type: string
description: The name of the log group.
tags:
type: object
additionalProperties:
type: string
description: The key-value pairs to use for the tags.
required:
- logGroupName
- tags
UntagLogGroupRequest:
type: object
properties:
logGroupName:
type: string
description: The name of the log group.
tags:
type: array
items:
type: string
description: The tag keys. The corresponding tags are removed from the log group.
required:
- logGroupName
- tags
x-provenance:
method: harvested
publisher: Amazon Web Services
source: https://raw.githubusercontent.com/aws/api-models-aws/3cd98287b471c106254abd89279cc87308d38bfd/models/cloudwatch-logs/service/2014-03-28/cloudwatch-logs-2014-03-28.json
note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)