I tried descending order retrieval with CloudWatch Logs FilterLogEvents using startFromHead=false

Introduction

On June 18, 2026, the CloudWatch Logs FilterLogEvents API was updated to allow specifying false for the startFromHead parameter.

https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_FilterLogEvents.html

What Changed

By specifying startFromHead=false, you can retrieve events matching the specified conditions in descending order, starting from the most recent. This makes it possible to filter with a filter pattern while viewing matching logs in reverse chronological order. In the AWS CLI, this corresponds to the --no-start-from-head option. The default remains true (ascending order) as stated in the documentation, and the behavior when left unspecified is unchanged from before.

Difference Between FilterLogEvents and GetLogEvents

Here we compare FilterLogEvents and GetLogEvents, two representative APIs for directly retrieving log events in CloudWatch Logs.

GetLogEvents is designed for viewing a single stream and does not support filter patterns. Comparing these two APIs, FilterLogEvents is better suited for use cases such as "retrieve logs containing ERROR starting from the latest" or "check only the most recent REJECT flow logs." Descending retrieval has now been added to it.

Limitations

There are limitations when using startFromHead=false.

• startTime must be set to January 1, 2024 (UTC) or later
• Specifying a date before that returns an InvalidParameterException

Quoting from the official documentation:

Setting startFromHead to false is supported only when startTime is on or after Jan 1, 2024 00:00:00 UTC. A request with startFromHead set to false and a startTime before this date returns an InvalidParameterException.

Trying It Out

We send VPC flow logs to CloudWatch Logs and verify the ascending/descending behavior of FilterLogEvents.

Test Environment

• AWS CLI 2.35.8
• Region: ap-northeast-1
• Log group: /vpc/flow-logs/test-filter-log-events (VPC flow logs, aggregation interval 60 seconds)

Test 1: Retrieving in Ascending Order (--start-from-head)

First, we retrieve in ascending order using the conventional behavior. All tests commonly specify --start-time 1704067200000 (2024-01-01T00:00:00Z).

aws logs filter-log-events \
  --log-group-name "/vpc/flow-logs/test-filter-log-events" \
  --start-time 1704067200000 \
  --limit 3 \
  --start-from-head \
  --region ap-northeast-1

{
    "events": [
        {
            "logStreamName": "eni-013191c0a72b6xxxx-all",
            "timestamp": 1782063972000,
            "message": "2 123456789012 eni-013191c0a72b6xxxx x.x.x.x 192.168.27.87 443 48368 6 1 76 1782063972 1782064001 ACCEPT OK",
            "ingestionTime": 1782064035668
        },
        {
            "logStreamName": "eni-013191c0a72b6xxxx-all",
            "timestamp": 1782063972000,
            "message": "2 123456789012 eni-013191c0a72b6xxxx x.x.x.x 192.168.27.87 443 35209 6 14 2565 1782063972 1782064001 ACCEPT OK",
            "ingestionTime": 1782064035668
        },
        {
            "logStreamName": "eni-013191c0a72b6xxxx-all",
            "timestamp": 1782063972000,
            "message": "2 123456789012 eni-013191c0a72b6xxxx x.x.x.x 192.168.27.87 443 23647 6 3 180 1782063972 1782064001 ACCEPT OK",
            "ingestionTime": 1782064035668
        }
    ]
}

The timestamp of the first event is 1782063972000, and events are returned in ascending order starting from the oldest side.

Test 2: Retrieving in Descending Order (--no-start-from-head)

Next, we specify --no-start-from-head to retrieve in descending order.

aws logs filter-log-events \
  --log-group-name "/vpc/flow-logs/test-filter-log-events" \
  --start-time 1704067200000 \
  --limit 3 \
  --no-start-from-head \
  --region ap-northeast-1

{
    "events": [
        {
            "logStreamName": "eni-03971bd72581dxxxx-all",
            "timestamp": 1782064430000,
            "message": "2 123456789012 eni-03971bd72581dxxxx 192.168.23.213 192.168.27.87 2049 65221 6 6 434 1782064430 1782064432 ACCEPT OK",
            "ingestionTime": 1782064456349
        },
        {
            "logStreamName": "eni-03971bd72581dxxxx-all",
            "timestamp": 1782064430000,
            "message": "2 123456789012 eni-03971bd72581dxxxx 192.168.27.87 192.168.23.213 65221 2049 6 7 510 1782064430 1782064432 ACCEPT OK",
            "ingestionTime": 1782064456349
        },
        {
            "logStreamName": "nat-11f9b13f38e22xxxx-all",
            "timestamp": 1782064404000,
            "message": "2 123456789012 - - - - - - - - 1782064404 1782064423 - SKIPDATA",
            "ingestionTime": 1782064452153
        }
    ]
}

The timestamp of the first event is 1782064430000, and events matching the specified conditions are returned starting from the most recent side. The timestamps within the array are also arranged as 1782064430000 → 1782064430000 → 1782064404000, confirming that the events array is returned in descending order by timestamp.

Test 3: Retrieving with Filter Pattern + Descending Order

We combine filter patterns, which are a strength of FilterLogEvents, with descending retrieval. Here we specify ACCEPT as the filter pattern and retrieve in descending order.

aws logs filter-log-events \
  --log-group-name "/vpc/flow-logs/test-filter-log-events" \
  --start-time 1704067200000 \
  --filter-pattern "ACCEPT" \
  --limit 3 \
  --no-start-from-head \
  --region ap-northeast-1

{
    "events": [
        {
            "logStreamName": "eni-03971bd72581dxxxx-all",
            "timestamp": 1782064430000,
            "message": "2 123456789012 eni-03971bd72581dxxxx 192.168.23.213 192.168.27.87 2049 65221 6 6 434 1782064430 1782064432 ACCEPT OK",
            "ingestionTime": 1782064456349
        },
        {
            "logStreamName": "eni-03971bd72581dxxxx-all",
            "timestamp": 1782064430000,
            "message": "2 123456789012 eni-03971bd72581dxxxx 192.168.27.87 192.168.23.213 65221 2049 6 7 510 1782064430 1782064432 ACCEPT OK",
            "ingestionTime": 1782064456349
        },
        {
            "logStreamName": "nat-11f9b13f38e22xxxx-all",
            "timestamp": 1782064404000,
            "message": "2 123456789012 - 192.168.27.87 x.x.x.x 38256 443 6 3 180 1782064404 1782064423 ACCEPT OK",
            "ingestionTime": 1782064452153
        }
    ]
}

We were able to narrow down to only events matching the condition using the filter pattern and retrieve them in descending order. The SKIPDATA record that was included as the third item in Test 2 has been excluded, and only events containing ACCEPT are returned.

Comparison of Results

Even when a filter pattern was specified, matching events were returned in order from the newest timestamp to the oldest timestamp.

Summary

With the addition of startFromHead=false to the FilterLogEvents API, it is now possible to combine filter patterns with descending retrieval using the API alone. While the management console previously provided a way to view the latest logs, this update means the same retrieval can be done from the CLI or SDK simply by adding --no-start-from-head. Operations such as filtering by an error pattern during incident response to view only recent logs, or checking the latest logs containing a specific keyword after deployment, can now be achieved at the log group level with a single command.