Event History Queries via SDK

LookupEvents is CloudTrail's fastest path to answering "what happened, and who did it" without setting up a trail first.

This page covers filtering by event name, actor, and resource, bounding the time window, and paginating through larger result sets.

Recipe

Quick-reference recipe card - copy-paste ready.

# --- Python (boto3) ---
import boto3
from datetime import datetime, timedelta
 
client = boto3.client("cloudtrail")
response = client.lookup_events(
    LookupAttributes=[{"AttributeKey": "EventName", "AttributeValue": "DeleteBucket"}],
    StartTime=datetime.utcnow() - timedelta(days=1),
    MaxResults=20,
)
for event in response["Events"]:
    print(event["EventTime"], event["Username"], event["EventName"])

When to reach for this:

• Debugging "who changed/deleted this resource" without waiting on a trail's S3 delivery.
• A quick security check on console logins or IAM changes in the last few days.
• Building a lightweight audit widget where 90 days of history is enough.
• Confirming a specific API call actually happened, and when, before digging into a trail's raw logs.

Working Example

Filter by resource name to find every action taken against a specific S3 bucket in the last 24 hours.

# --- Python (boto3) ---
import boto3
from datetime import datetime, timedelta
 
client = boto3.client("cloudtrail")
 
response = client.lookup_events(
    LookupAttributes=[
        {"AttributeKey": "ResourceName", "AttributeValue": "acme-prod-reports"}
    ],
    StartTime=datetime.utcnow() - timedelta(hours=24),
    MaxResults=50,
)
 
for event in response["Events"]:
    print(f"{event['EventTime']} {event['Username']} {event['EventName']}")

// --- TypeScript (AWS SDK v3) ---
import { CloudTrailClient, LookupEventsCommand } from "@aws-sdk/client-cloudtrail";
 
const client = new CloudTrailClient({});
 
const response = await client.send(new LookupEventsCommand({
  LookupAttributes: [
    { AttributeKey: "ResourceName", AttributeValue: "acme-prod-reports" },
  ],
  StartTime: new Date(Date.now() - 24 * 60 * 60 * 1000),
  MaxResults: 50,
}));
 
for (const event of response.Events ?? []) {
  console.log(event.EventTime, event.Username, event.EventName);
}

What this demonstrates:

• ResourceName filters events touching a specific resource, e.g. a bucket, instance, or IAM role name.
• Only one LookupAttributes entry is allowed per call - you cannot combine ResourceName and EventName in a single filter.
• StartTime narrows the scan window, reducing pages and improving response latency.
• The response includes a CloudTrailEvent JSON string per event with the full raw event detail beyond the summary fields.

Deep Dive

How It Works

• LookupEvents reads from CloudTrail's internally-managed event history, a rolling 90-day store maintained regardless of whether any trail exists.
• It supports one LookupAttributes filter per call, chosen from a fixed set of keys: EventId, EventName, ReadOnly, Username, ResourceType, ResourceName, EventSource, and AccessKeyId.
• To combine filters (e.g. a specific user AND a specific event name), you fetch a broader result set with one filter and post-filter client-side, or make separate calls and intersect.
• Each returned Event has a summary shape (EventName, EventTime, Username, Resources) plus a CloudTrailEvent field containing the full event as a JSON string, which includes request parameters and response elements not in the summary.
• Because this is a search over indexed event history rather than a raw log scan, it responds far faster than parsing S3-delivered log files directly - the trade-off is the 90-day cap.

Parsing the Full Event Detail

The summary fields cover the basics, but request parameters (like what an IAM CreatePolicy call actually contained) live in CloudTrailEvent.

# --- Python (boto3) ---
import json
 
for event in response["Events"]:
    detail = json.loads(event["CloudTrailEvent"])
    print(detail["sourceIPAddress"], detail.get("requestParameters"))

// --- TypeScript (AWS SDK v3) ---
for (const event of response.Events ?? []) {
  const detail = JSON.parse(event.CloudTrailEvent ?? "{}");
  console.log(detail.sourceIPAddress, detail.requestParameters);
}

Common Filter Keys at a Glance

Gotchas

• Assuming multiple LookupAttributes can be combined - the API only accepts one filter per call; passing more raises a validation error. Fix: filter broadly on the one supported key, then narrow further client-side.
• Forgetting the 90-day cap - LookupEvents silently returns nothing for a StartTime older than the retention window, with no error. Fix: check the window against 90 days first; use CloudTrail Lake for anything older.
• Not paginating a busy account's results - a single MaxResults page can miss most of the matching events in an active account. Fix: use the paginator (get_paginator("lookup_events") / paginateLookupEvents) for any non-trivial window.
• Reading only the summary fields and missing request detail - Resources/EventName alone often isn't enough to reconstruct what actually happened. Fix: parse CloudTrailEvent for the full JSON detail, including request parameters.
• Treating ReadOnly filtering as data-event filtering - ReadOnly distinguishes read vs. write management events, it does not surface S3/Lambda data events, which LookupEvents doesn't cover at all. Fix: use a trail with data events enabled, queried via S3/Athena or Lake, for data-plane activity.

Alternatives

FAQs

Related

• CloudTrail Basics - the first LookupEvents calls and pagination pattern.
• CloudTrail as the API-Call Audit Log - the conceptual model for events and trails.
• CloudTrail Lake for SQL-Based Audit Queries - querying beyond the 90-day window.
• Detecting Suspicious Activity from CloudTrail - turning these queries into alerts.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).