# AWS log group subscriptions

Control which Amazon CloudWatch log groups Better Stack ingests for an `aws` source. These endpoints manage per-log-group subscription overrides. To subscribe every newly discovered log group automatically, set `aws_auto_sub_log_groups` when you [update the source](https://betterstack.com/docs/logs/api/update-source/).

[info]
#### Connect your AWS account first
These endpoints apply to `aws` sources with an AWS account connected. See [Connect source to your AWS account](https://betterstack.com/docs/logs/api/connect-source-to-aws/).
[/info]

An override records the desired state for one log group, identified by its `region` and `name`. Set `subscribed` to `true` to ingest the log group or `false` to skip it. An override takes precedence over the source's auto-subscribe setting, and you can create one before the log group is discovered. Delete the override to return the log group to automatic behavior.

## List log group subscriptions

Returns the log group subscription overrides for an `aws` source.

[endpoint]
base_url = "https://telemetry.betterstack.com"
path = "/api/v2/sources/{source_id}/aws-log-group-subscriptions"
method = "GET"

[[path_param]]
name = "source_id"
description = "ID of the `aws` source"
required = true
type = "string"

[[query_param]]
name = "page"
description = "Page number"
type = "integer"

[[query_param]]
name = "per_page"
description = "The number of subscriptions per page (max 50)"
type = "integer"

[[header]]
name = "Authorization"
description = "Bearer `$TOKEN`"
required = true
type = "string"
[/endpoint]

[responses]
[[response]]
status = 200
description = ''''''
body = '''{
    "data": [
        {
            "id": "1",
            "type": "aws_log_group_subscription",
            "attributes": {
                "region": "us-east-1",
                "name": "/aws/lambda/checkout",
                "subscribed": true,
                "created_at": "2026-08-19T12:30:41.695Z",
                "updated_at": "2026-08-19T12:30:41.695Z"
            }
        }
    ],
    "pagination": {
        "first": "https://telemetry.betterstack.com/api/v2/sources/95/aws-log-group-subscriptions?page=1&per_page=10",
        "last": "https://telemetry.betterstack.com/api/v2/sources/95/aws-log-group-subscriptions?page=1&per_page=10",
        "prev": null,
        "next": null
    }
}'''
[/responses]

#### Example cURL

```shell
[label List log group subscriptions]
curl --request GET \
  --url https://telemetry.betterstack.com/api/v2/sources/95/aws-log-group-subscriptions \
  --header "Authorization: Bearer $TOKEN"
```

## Create a log group subscription

Creates an override that subscribes or unsubscribes one log group.

[endpoint]
base_url = "https://telemetry.betterstack.com"
path = "/api/v2/sources/{source_id}/aws-log-group-subscriptions"
method = "POST"

[[path_param]]
name = "source_id"
description = "ID of the `aws` source"
required = true
type = "string"

[[body_param]]
name = "region"
description = "AWS region of the log group, for example `us-east-1`."
required = true
type = "string"

[[body_param]]
name = "name"
description = "Name of the CloudWatch log group, for example `/aws/lambda/checkout`."
required = true
type = "string"

[[body_param]]
name = "subscribed"
description = "Whether to ingest this log group. Set to `true` to subscribe or `false` to skip it."
required = true
type = "boolean"

[[header]]
name = "Authorization"
description = "Bearer `$TOKEN`"
required = true
type = "string"
[/endpoint]

[responses]
[[response]]
status = 201
description = '''The subscription override was created.'''
body = '''{
    "data": {
        "id": "1",
        "type": "aws_log_group_subscription",
        "attributes": {
            "region": "us-east-1",
            "name": "/aws/lambda/checkout",
            "subscribed": true,
            "created_at": "2026-08-19T12:30:41.695Z",
            "updated_at": "2026-08-19T12:30:41.695Z"
        }
    }
}'''

[[response]]
status = 422
description = '''An override already exists for this region and log group name.'''
body = '''{
    "errors": ["Name has already been taken"],
    "invalid_attributes": ["name"]
}'''
[/responses]

#### Example cURL

```shell
[label Create a log group subscription]
curl --request POST \
  --url https://telemetry.betterstack.com/api/v2/sources/95/aws-log-group-subscriptions \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "region": "us-east-1",
    "name": "/aws/lambda/checkout",
    "subscribed": true
  }'
```

## Get a single log group subscription

Returns one log group subscription override.

[endpoint]
base_url = "https://telemetry.betterstack.com"
path = "/api/v2/sources/{source_id}/aws-log-group-subscriptions/{id}"
method = "GET"

[[path_param]]
name = "source_id"
description = "ID of the `aws` source"
required = true
type = "string"

[[path_param]]
name = "id"
description = "ID of the log group subscription override"
required = true
type = "string"

[[header]]
name = "Authorization"
description = "Bearer `$TOKEN`"
required = true
type = "string"
[/endpoint]

[responses]
[[response]]
status = 200
description = ''''''
body = '''{
    "data": {
        "id": "1",
        "type": "aws_log_group_subscription",
        "attributes": {
            "region": "us-east-1",
            "name": "/aws/lambda/checkout",
            "subscribed": true,
            "created_at": "2026-08-19T12:30:41.695Z",
            "updated_at": "2026-08-19T12:30:41.695Z"
        }
    }
}'''

[[response]]
status = 404
description = '''The source has no subscription override with the given ID.'''
body = '''{
    "errors": "Resource with provided ID was not found"
}'''
[/responses]

#### Example cURL

```shell
[label Get a log group subscription]
curl --request GET \
  --url https://telemetry.betterstack.com/api/v2/sources/95/aws-log-group-subscriptions/1 \
  --header "Authorization: Bearer $TOKEN"
```

## Update a log group subscription

Subscribes or unsubscribes an existing override.

[endpoint]
base_url = "https://telemetry.betterstack.com"
path = "/api/v2/sources/{source_id}/aws-log-group-subscriptions/{id}"
method = "PATCH"

[[path_param]]
name = "source_id"
description = "ID of the `aws` source"
required = true
type = "string"

[[path_param]]
name = "id"
description = "ID of the log group subscription override"
required = true
type = "string"

[[body_param]]
name = "subscribed"
description = "Whether to ingest this log group. Set to `true` to subscribe or `false` to skip it."
required = true
type = "boolean"

[[header]]
name = "Authorization"
description = "Bearer `$TOKEN`"
required = true
type = "string"
[/endpoint]

[responses]
[[response]]
status = 200
description = '''The subscription override was updated.'''
body = '''{
    "data": {
        "id": "1",
        "type": "aws_log_group_subscription",
        "attributes": {
            "region": "us-east-1",
            "name": "/aws/lambda/checkout",
            "subscribed": false,
            "created_at": "2026-08-19T12:30:41.695Z",
            "updated_at": "2026-08-19T13:05:12.104Z"
        }
    }
}'''

[[response]]
status = 404
description = '''The source has no subscription override with the given ID.'''
body = '''{
    "errors": "Resource with provided ID was not found"
}'''
[/responses]

#### Example cURL

```shell
[label Update a log group subscription]
curl --request PATCH \
  --url https://telemetry.betterstack.com/api/v2/sources/95/aws-log-group-subscriptions/1 \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "subscribed": false
  }'
```

## Delete a log group subscription

Removes the override and returns the log group to automatic behavior.

[endpoint]
base_url = "https://telemetry.betterstack.com"
path = "/api/v2/sources/{source_id}/aws-log-group-subscriptions/{id}"
method = "DELETE"

[[path_param]]
name = "source_id"
description = "ID of the `aws` source"
required = true
type = "string"

[[path_param]]
name = "id"
description = "ID of the log group subscription override"
required = true
type = "string"

[[header]]
name = "Authorization"
description = "Bearer `$TOKEN`"
required = true
type = "string"
[/endpoint]

[responses]
[[response]]
status = 204
description = '''The subscription override was deleted.'''

[[response]]
status = 404
description = '''The source has no subscription override with the given ID.'''
body = '''{
    "errors": "Resource with provided ID was not found"
}'''
[/responses]

#### Example cURL

```shell
[label Delete a log group subscription]
curl --request DELETE \
  --url https://telemetry.betterstack.com/api/v2/sources/95/aws-log-group-subscriptions/1 \
  --header "Authorization: Bearer $TOKEN"
```