CloudTrail Basics

Seven examples to get you started with CloudTrail via SDK - five basic and two intermediate.

Each example shows the same operation in both Python (boto3) and TypeScript (AWS SDK for JavaScript v3).

Prerequisites

Python: pip install boto3 (boto3 1.43.x, Python 3.10+). TypeScript: npm install @aws-sdk/client-cloudtrail (Node.js 18+).
Credentials configured via aws configure, environment variables, or an IAM role, with cloudtrail:LookupEvents and cloudtrail:*Trail* permissions as needed.
No trail is required for the first few examples - LookupEvents works against any account's built-in event history.

Basic Examples

1. Look Up Recent Events

Query the last 90 days of management events without any trail setup.

# --- Python (boto3) ---
import boto3
 
client = boto3.client("cloudtrail", region_name="us-east-1")
response = client.lookup_events(MaxResults=10)
for event in response["Events"]:
    print(event["EventName"], event["EventTime"], event["Username"])

// --- TypeScript (AWS SDK v3) ---
import { CloudTrailClient, LookupEventsCommand } from "@aws-sdk/client-cloudtrail";
 
const client = new CloudTrailClient({ region: "us-east-1" });
const response = await client.send(new LookupEventsCommand({ MaxResults: 10 }));
for (const event of response.Events ?? []) {
  console.log(event.EventName, event.EventTime, event.Username);
}

LookupEvents reads the account's built-in event history, not a trail's S3 logs.
Results are ordered newest first by default.
MaxResults caps a single page; use pagination for larger windows.
Username may be empty for service-linked or unauthenticated calls.

Related: Event History Queries via SDK - filtering with LookupAttributes.

2. Filter by Event Name

Narrow results to a specific API call, like console sign-ins.

# --- Python (boto3) ---
import boto3
 
client = boto3.client("cloudtrail")
response = client.lookup_events(
    LookupAttributes=[{"AttributeKey": "EventName", "AttributeValue": "ConsoleLogin"}],
    MaxResults=10,
)
for event in response["Events"]:
    print(event["EventTime"], event["Username"])

// --- 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: "EventName", AttributeValue: "ConsoleLogin" }],
  MaxResults: 10,
}));
for (const event of response.Events ?? []) {
  console.log(event.EventTime, event.Username);
}

LookupAttributes accepts exactly one attribute key/value pair per call.
EventName matches the exact API operation name, case-sensitive.
Useful for a quick "who's logging in" check without building a trail first.
Combine with a StartTime/EndTime window to bound the search further.

3. Create a Trail

Stand up a trail that delivers events to S3 for durable retention.

# --- Python (boto3) ---
import boto3
 
client = boto3.client("cloudtrail")
trail = client.create_trail(
    Name="baseline-trail",
    S3BucketName="my-account-cloudtrail-logs",
    IsMultiRegionTrail=True,
    EnableLogFileValidation=True,
)
print(trail["TrailARN"])

// --- TypeScript (AWS SDK v3) ---
import { CloudTrailClient, CreateTrailCommand } from "@aws-sdk/client-cloudtrail";
 
const client = new CloudTrailClient({});
const trail = await client.send(new CreateTrailCommand({
  Name: "baseline-trail",
  S3BucketName: "my-account-cloudtrail-logs",
  IsMultiRegionTrail: true,
  EnableLogFileValidation: true,
}));
console.log(trail.TrailARN);

S3BucketName must already exist and have a bucket policy allowing CloudTrail to write to it.
IsMultiRegionTrail: true captures events from every region into this one trail.
CreateTrail only defines the trail; logging doesn't start until you call StartLogging.
EnableLogFileValidation turns on digest-file delivery for tamper-evidence.

Related: Trails, S3 Delivery & Log File Validation - the full setup including org-wide trails.

4. Start Logging

A newly created trail doesn't log until you explicitly start it.

# --- Python (boto3) ---
import boto3
 
client = boto3.client("cloudtrail")
client.start_logging(Name="baseline-trail")

// --- TypeScript (AWS SDK v3) ---
import { CloudTrailClient, StartLoggingCommand } from "@aws-sdk/client-cloudtrail";
 
const client = new CloudTrailClient({});
await client.send(new StartLoggingCommand({ Name: "baseline-trail" }));

StartLogging is a separate call from CreateTrail - creating a trail alone delivers nothing.
The Name parameter accepts the trail name or its full ARN.
Logging begins asynchronously; the first log files may take several minutes to appear in S3.
StopLogging is the corresponding call to pause delivery without deleting the trail.

5. Check Trail Status

Confirm whether a trail is actively logging right now.

# --- Python (boto3) ---
import boto3
 
client = boto3.client("cloudtrail")
status = client.get_trail_status(Name="baseline-trail")
print(status["IsLogging"], status.get("LatestDeliveryTime"))

// --- TypeScript (AWS SDK v3) ---
import { CloudTrailClient, GetTrailStatusCommand } from "@aws-sdk/client-cloudtrail";
 
const client = new CloudTrailClient({});
const status = await client.send(new GetTrailStatusCommand({ Name: "baseline-trail" }));
console.log(status.IsLogging, status.LatestDeliveryTime);

IsLogging is a boolean reflecting the trail's current state, not its historical uptime.
LatestDeliveryTime tells you when the last log file successfully landed in S3.
Delivery-error fields (LatestDeliveryError) surface permission or bucket-policy problems.
Check this after StartLogging to confirm the trail is actually delivering, not just enabled.

Intermediate Examples

6. Filter by Username

Narrow event history to a specific IAM principal's activity.

# --- Python (boto3) ---
import boto3
 
client = boto3.client("cloudtrail")
response = client.lookup_events(
    LookupAttributes=[{"AttributeKey": "Username", "AttributeValue": "deploy-bot"}],
    MaxResults=20,
)
for event in response["Events"]:
    print(event["EventName"], event["EventTime"])

// --- 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: "Username", AttributeValue: "deploy-bot" }],
  MaxResults: 20,
}));
for (const event of response.Events ?? []) {
  console.log(event.EventName, event.EventTime);
}

Username matches the IAM user or role session name that made the call.
Useful for auditing what a CI/CD or automation identity has been doing.
Assumed-role sessions show up as role-name/session-name in some event fields.
Pair with StartTime to bound a specific deploy window.

7. Paginate a Wider Time Range

Walk multiple pages of event history for a longer lookback window.

# --- Python (boto3) ---
import boto3
from datetime import datetime, timedelta
 
client = boto3.client("cloudtrail")
paginator = client.get_paginator("lookup_events")
start = datetime.utcnow() - timedelta(days=7)
 
for page in paginator.paginate(StartTime=start):
    for event in page["Events"]:
        print(event["EventName"], event["EventTime"])

// --- TypeScript (AWS SDK v3) ---
import { CloudTrailClient, paginateLookupEvents } from "@aws-sdk/client-cloudtrail";
 
const client = new CloudTrailClient({});
const start = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
 
const pages = paginateLookupEvents({ client }, { StartTime: start });
for await (const page of pages) {
  for (const event of page.Events ?? []) {
    console.log(event.EventName, event.EventTime);
  }
}

boto3 exposes get_paginator("lookup_events"); SDK v3 ships paginateLookupEvents.
Each page is a separate request, so a 7-day window across a busy account can mean many pages.
StartTime/EndTime bound the query; omitting both defaults to the full 90-day history.
For queries beyond 90 days or needing SQL-style filtering, use CloudTrail Lake instead.

Related: CloudTrail Lake for SQL-Based Audit Queries - long-retention, SQL-based querying.

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

Each example shows the same operation in both Python (boto3) and TypeScript (AWS SDK for JavaScript v3).

Prerequisites

Python: pip install boto3 (boto3 1.43.x, Python 3.10+). TypeScript: npm install @aws-sdk/client-cloudtrail (Node.js 18+).
Credentials configured via aws configure, environment variables, or an IAM role, with cloudtrail:LookupEvents and cloudtrail:*Trail* permissions as needed.
No trail is required for the first few examples - LookupEvents works against any account's built-in event history.

Basic Examples

1. Look Up Recent Events

Query the last 90 days of management events without any trail setup.

# --- Python (boto3) ---
import boto3
 
client = boto3.client("cloudtrail", region_name="us-east-1")
response = client.lookup_events(MaxResults=10)
for event in response["Events"]:
    print(event["EventName"], event["EventTime"], event["Username"])

// --- TypeScript (AWS SDK v3) ---
import { CloudTrailClient, LookupEventsCommand } from "@aws-sdk/client-cloudtrail";
 
const client = new CloudTrailClient({ region: "us-east-1" });
const response = await client.send(new LookupEventsCommand({ MaxResults: 10 }));
for (const event of response.Events ?? []) {
  console.log(event.EventName, event.EventTime, event.Username);
}

LookupEvents reads the account's built-in event history, not a trail's S3 logs.
Results are ordered newest first by default.
MaxResults caps a single page; use pagination for larger windows.
Username may be empty for service-linked or unauthenticated calls.

Related: Event History Queries via SDK - filtering with LookupAttributes.

2. Filter by Event Name

Narrow results to a specific API call, like console sign-ins.

# --- Python (boto3) ---
import boto3
 
client = boto3.client("cloudtrail")
response = client.lookup_events(
    LookupAttributes=[{"AttributeKey": "EventName", "AttributeValue": "ConsoleLogin"}],
    MaxResults=10,
)
for event in response["Events"]:
    print(event["EventTime"], event["Username"])

// --- 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: "EventName", AttributeValue: "ConsoleLogin" }],
  MaxResults: 10,
}));
for (const event of response.Events ?? []) {
  console.log(event.EventTime, event.Username);
}

LookupAttributes accepts exactly one attribute key/value pair per call.
EventName matches the exact API operation name, case-sensitive.
Useful for a quick "who's logging in" check without building a trail first.
Combine with a StartTime/EndTime window to bound the search further.

3. Create a Trail

Stand up a trail that delivers events to S3 for durable retention.

# --- Python (boto3) ---
import boto3
 
client = boto3.client("cloudtrail")
trail = client.create_trail(
    Name="baseline-trail",
    S3BucketName="my-account-cloudtrail-logs",
    IsMultiRegionTrail=True,
    EnableLogFileValidation=True,
)
print(trail["TrailARN"])

// --- TypeScript (AWS SDK v3) ---
import { CloudTrailClient, CreateTrailCommand } from "@aws-sdk/client-cloudtrail";
 
const client = new CloudTrailClient({});
const trail = await client.send(new CreateTrailCommand({
  Name: "baseline-trail",
  S3BucketName: "my-account-cloudtrail-logs",
  IsMultiRegionTrail: true,
  EnableLogFileValidation: true,
}));
console.log(trail.TrailARN);

S3BucketName must already exist and have a bucket policy allowing CloudTrail to write to it.
IsMultiRegionTrail: true captures events from every region into this one trail.
CreateTrail only defines the trail; logging doesn't start until you call StartLogging.
EnableLogFileValidation turns on digest-file delivery for tamper-evidence.

Related: Trails, S3 Delivery & Log File Validation - the full setup including org-wide trails.

4. Start Logging

A newly created trail doesn't log until you explicitly start it.

# --- Python (boto3) ---
import boto3
 
client = boto3.client("cloudtrail")
client.start_logging(Name="baseline-trail")

// --- TypeScript (AWS SDK v3) ---
import { CloudTrailClient, StartLoggingCommand } from "@aws-sdk/client-cloudtrail";
 
const client = new CloudTrailClient({});
await client.send(new StartLoggingCommand({ Name: "baseline-trail" }));

StartLogging is a separate call from CreateTrail - creating a trail alone delivers nothing.
The Name parameter accepts the trail name or its full ARN.
Logging begins asynchronously; the first log files may take several minutes to appear in S3.
StopLogging is the corresponding call to pause delivery without deleting the trail.

5. Check Trail Status

Confirm whether a trail is actively logging right now.

# --- Python (boto3) ---
import boto3
 
client = boto3.client("cloudtrail")
status = client.get_trail_status(Name="baseline-trail")
print(status["IsLogging"], status.get("LatestDeliveryTime"))

// --- TypeScript (AWS SDK v3) ---
import { CloudTrailClient, GetTrailStatusCommand } from "@aws-sdk/client-cloudtrail";
 
const client = new CloudTrailClient({});
const status = await client.send(new GetTrailStatusCommand({ Name: "baseline-trail" }));
console.log(status.IsLogging, status.LatestDeliveryTime);

IsLogging is a boolean reflecting the trail's current state, not its historical uptime.
LatestDeliveryTime tells you when the last log file successfully landed in S3.
Delivery-error fields (LatestDeliveryError) surface permission or bucket-policy problems.
Check this after StartLogging to confirm the trail is actually delivering, not just enabled.

Intermediate Examples

6. Filter by Username

Narrow event history to a specific IAM principal's activity.

# --- Python (boto3) ---
import boto3
 
client = boto3.client("cloudtrail")
response = client.lookup_events(
    LookupAttributes=[{"AttributeKey": "Username", "AttributeValue": "deploy-bot"}],
    MaxResults=20,
)
for event in response["Events"]:
    print(event["EventName"], event["EventTime"])

// --- 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: "Username", AttributeValue: "deploy-bot" }],
  MaxResults: 20,
}));
for (const event of response.Events ?? []) {
  console.log(event.EventName, event.EventTime);
}

Username matches the IAM user or role session name that made the call.
Useful for auditing what a CI/CD or automation identity has been doing.
Assumed-role sessions show up as role-name/session-name in some event fields.
Pair with StartTime to bound a specific deploy window.

7. Paginate a Wider Time Range

Walk multiple pages of event history for a longer lookback window.

# --- Python (boto3) ---
import boto3
from datetime import datetime, timedelta
 
client = boto3.client("cloudtrail")
paginator = client.get_paginator("lookup_events")
start = datetime.utcnow() - timedelta(days=7)
 
for page in paginator.paginate(StartTime=start):
    for event in page["Events"]:
        print(event["EventName"], event["EventTime"])

// --- TypeScript (AWS SDK v3) ---
import { CloudTrailClient, paginateLookupEvents } from "@aws-sdk/client-cloudtrail";
 
const client = new CloudTrailClient({});
const start = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
 
const pages = paginateLookupEvents({ client }, { StartTime: start });
for await (const page of pages) {
  for (const event of page.Events ?? []) {
    console.log(event.EventName, event.EventTime);
  }
}

boto3 exposes get_paginator("lookup_events"); SDK v3 ships paginateLookupEvents.
Each page is a separate request, so a 7-day window across a busy account can mean many pages.
StartTime/EndTime bound the query; omitting both defaults to the full 90-day history.
For queries beyond 90 days or needing SQL-style filtering, use CloudTrail Lake instead.

Related: CloudTrail Lake for SQL-Based Audit Queries - long-retention, SQL-based querying.

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

CloudTrail Basics

Buscar en la documentación

CloudTrail Basics