Efficient listing of buckets, objects, and multipart uploads with built-in pagination support and filtering capabilities for managing large datasets.
List objects in a bucket using the recommended V2 API with improved performance and features.
/**
* List objects in a bucket (V2 API - recommended)
*/
class ListObjectsV2Command {
constructor(input: ListObjectsV2CommandInput);
}
interface ListObjectsV2CommandInput {
/** Bucket name */
Bucket: string;
/** Continuation token for pagination */
ContinuationToken?: string;
/** Character to group keys */
Delimiter?: string;
/** Encoding type for keys */
EncodingType?: EncodingType;
/** Fetch owner information */
FetchOwner?: boolean;
/** Maximum keys to return */
MaxKeys?: number;
/** Key prefix filter */
Prefix?: string;
/** Key to start listing after */
StartAfter?: string;
/** Request payer setting */
RequestPayer?: RequestPayer;
/** Expected bucket owner account ID */
ExpectedBucketOwner?: string;
/** Optional object attributes to retrieve */
OptionalObjectAttributes?: OptionalObjectAttributes[];
}
interface ListObjectsV2CommandOutput {
/** Truncation flag */
IsTruncated?: boolean;
/** List of objects */
Contents?: Object[];
/** Bucket name */
Name?: string;
/** Key prefix */
Prefix?: string;
/** Delimiter used */
Delimiter?: string;
/** Maximum keys requested */
MaxKeys?: number;
/** Common prefixes */
CommonPrefixes?: CommonPrefix[];
/** Encoding type */
EncodingType?: EncodingType;
/** Object count */
KeyCount?: number;
/** Continuation token used */
ContinuationToken?: string;
/** Next continuation token */
NextContinuationToken?: string;
/** Start after key */
StartAfter?: string;
/** Request charged information */
RequestCharged?: RequestCharged;
}
interface Object {
/** Object key */
Key?: string;
/** Last modified date */
LastModified?: Date;
/** ETag */
ETag?: string;
/** Checksum values */
ChecksumAlgorithm?: ChecksumAlgorithm[];
/** Object size in bytes */
Size?: number;
/** Storage class */
StorageClass?: ObjectStorageClass;
/** Object owner (if FetchOwner=true) */
Owner?: Owner;
/** Restore status */
RestoreStatus?: RestoreStatus;
}
interface CommonPrefix {
/** Common prefix string */
Prefix?: string;
}Usage Examples:
import { S3Client, ListObjectsV2Command } from "@aws-sdk/client-s3";
const client = new S3Client({ region: "us-east-1" });
// Basic object listing
const listObjects = new ListObjectsV2Command({
Bucket: "my-bucket"
});
const response = await client.send(listObjects);
console.log(`Found ${response.KeyCount} objects`);
response.Contents?.forEach(obj => {
console.log(`- ${obj.Key} (${obj.Size} bytes, ${obj.LastModified})`);
});
// List with prefix filter
const listWithPrefix = new ListObjectsV2Command({
Bucket: "my-bucket",
Prefix: "photos/2024/",
MaxKeys: 100
});
const prefixResponse = await client.send(listWithPrefix);
// Paginated listing
async function listAllObjects(bucket: string, prefix?: string) {
const allObjects = [];
let continuationToken: string | undefined;
do {
const command = new ListObjectsV2Command({
Bucket: bucket,
Prefix: prefix,
ContinuationToken: continuationToken,
MaxKeys: 1000
});
const response = await client.send(command);
if (response.Contents) {
allObjects.push(...response.Contents);
}
continuationToken = response.NextContinuationToken;
} while (continuationToken);
return allObjects;
}
const allObjects = await listAllObjects("my-bucket", "documents/");
console.log(`Total objects: ${allObjects.length}`);List objects using the original V1 API (use V2 when possible).
/**
* List objects in a bucket (V1 API - legacy)
*/
class ListObjectsCommand {
constructor(input: ListObjectsCommandInput);
}
interface ListObjectsCommandInput {
/** Bucket name */
Bucket: string;
/** Character to group keys */
Delimiter?: string;
/** Encoding type for keys */
EncodingType?: EncodingType;
/** Key marker for pagination */
Marker?: string;
/** Maximum keys to return */
MaxKeys?: number;
/** Key prefix filter */
Prefix?: string;
/** Request payer setting */
RequestPayer?: RequestPayer;
/** Expected bucket owner account ID */
ExpectedBucketOwner?: string;
/** Optional object attributes to retrieve */
OptionalObjectAttributes?: OptionalObjectAttributes[];
}
interface ListObjectsCommandOutput {
/** Truncation flag */
IsTruncated?: boolean;
/** Key marker */
Marker?: string;
/** Next marker */
NextMarker?: string;
/** List of objects */
Contents?: Object[];
/** Bucket name */
Name?: string;
/** Key prefix */
Prefix?: string;
/** Delimiter used */
Delimiter?: string;
/** Maximum keys requested */
MaxKeys?: number;
/** Common prefixes */
CommonPrefixes?: CommonPrefix[];
/** Encoding type */
EncodingType?: EncodingType;
/** Request charged information */
RequestCharged?: RequestCharged;
}List all versions of objects in a versioned bucket.
/**
* List all versions of objects in a versioned bucket
*/
class ListObjectVersionsCommand {
constructor(input: ListObjectVersionsCommandInput);
}
interface ListObjectVersionsCommandInput {
/** Bucket name */
Bucket: string;
/** Character to group keys */
Delimiter?: string;
/** Encoding type for keys */
EncodingType?: EncodingType;
/** Key marker for pagination */
KeyMarker?: string;
/** Maximum keys to return */
MaxKeys?: number;
/** Key prefix filter */
Prefix?: string;
/** Version ID marker for pagination */
VersionIdMarker?: string;
/** Expected bucket owner account ID */
ExpectedBucketOwner?: string;
/** Request payer setting */
RequestPayer?: RequestPayer;
/** Optional object attributes to retrieve */
OptionalObjectAttributes?: OptionalObjectAttributes[];
}
interface ListObjectVersionsCommandOutput {
/** Truncation flag */
IsTruncated?: boolean;
/** Key marker */
KeyMarker?: string;
/** Version ID marker */
VersionIdMarker?: string;
/** Next key marker */
NextKeyMarker?: string;
/** Next version ID marker */
NextVersionIdMarker?: string;
/** List of object versions */
Versions?: ObjectVersion[];
/** List of delete markers */
DeleteMarkers?: DeleteMarkerEntry[];
/** Bucket name */
Name?: string;
/** Key prefix */
Prefix?: string;
/** Delimiter used */
Delimiter?: string;
/** Maximum keys requested */
MaxKeys?: number;
/** Common prefixes */
CommonPrefixes?: CommonPrefix[];
/** Encoding type */
EncodingType?: EncodingType;
/** Request charged information */
RequestCharged?: RequestCharged;
}
interface ObjectVersion {
/** ETag */
ETag?: string;
/** Checksum algorithm */
ChecksumAlgorithm?: ChecksumAlgorithm[];
/** Object size */
Size?: number;
/** Storage class */
StorageClass?: ObjectVersionStorageClass;
/** Object key */
Key?: string;
/** Version ID */
VersionId?: string;
/** Is latest version */
IsLatest?: boolean;
/** Last modified date */
LastModified?: Date;
/** Object owner */
Owner?: Owner;
/** Restore status */
RestoreStatus?: RestoreStatus;
}
interface DeleteMarkerEntry {
/** Object owner */
Owner?: Owner;
/** Object key */
Key?: string;
/** Version ID */
VersionId?: string;
/** Is latest version */
IsLatest?: boolean;
/** Last modified date */
LastModified?: Date;
}Usage Example:
import { S3Client, ListObjectVersionsCommand } from "@aws-sdk/client-s3";
const client = new S3Client({ region: "us-east-1" });
// List all versions of objects
const listVersions = new ListObjectVersionsCommand({
Bucket: "versioned-bucket",
Prefix: "documents/"
});
const versionsResponse = await client.send(listVersions);
console.log("Object versions:");
versionsResponse.Versions?.forEach(version => {
console.log(`- ${version.Key} (${version.VersionId}) - Latest: ${version.IsLatest}`);
});
console.log("Delete markers:");
versionsResponse.DeleteMarkers?.forEach(marker => {
console.log(`- ${marker.Key} (${marker.VersionId}) - Deleted: ${marker.LastModified}`);
});Built-in paginator classes for handling large result sets automatically.
/**
* Paginator for ListObjectsV2Command
*/
class ListObjectsV2Paginator {
constructor(config: S3PaginationConfiguration, input: ListObjectsV2CommandInput);
/** Iterator for paginated results */
[Symbol.asyncIterator](): AsyncIterator<ListObjectsV2CommandOutput>;
/** Get all pages as an array */
toArray(): Promise<ListObjectsV2CommandOutput[]>;
}
/**
* Paginator for ListBucketsCommand
*/
class ListBucketsPaginator {
constructor(config: S3PaginationConfiguration, input: ListBucketsCommandInput);
/** Iterator for paginated results */
[Symbol.asyncIterator](): AsyncIterator<ListBucketsCommandOutput>;
/** Get all pages as an array */
toArray(): Promise<ListBucketsCommandOutput[]>;
}
/**
* Paginator for ListPartCommand
*/
class ListPartsPaginator {
constructor(config: S3PaginationConfiguration, input: ListPartsCommandInput);
/** Iterator for paginated results */
[Symbol.asyncIterator](): AsyncIterator<ListPartsCommandOutput>;
/** Get all pages as an array */
toArray(): Promise<ListPartsCommandOutput[]>;
}
/**
* Paginator for ListDirectoryBucketsCommand
*/
class ListDirectoryBucketsPaginator {
constructor(config: S3PaginationConfiguration, input: ListDirectoryBucketsCommandInput);
/** Iterator for paginated results */
[Symbol.asyncIterator](): AsyncIterator<ListDirectoryBucketsCommandOutput>;
/** Get all pages as an array */
toArray(): Promise<ListDirectoryBucketsCommandOutput[]>;
}
interface S3PaginationConfiguration {
/** S3 client instance */
client: S3Client;
/** Page size (optional) */
pageSize?: number;
/** Start key (optional) */
startingToken?: any;
}Paginator Usage Examples:
import {
S3Client,
ListObjectsV2Command,
ListObjectsV2Paginator
} from "@aws-sdk/client-s3";
const client = new S3Client({ region: "us-east-1" });
// Using paginator with async iterator
const paginator = new ListObjectsV2Paginator(
{ client, pageSize: 100 },
{ Bucket: "large-bucket", Prefix: "logs/" }
);
for await (const page of paginator) {
console.log(`Page contains ${page.KeyCount} objects`);
page.Contents?.forEach(obj => {
console.log(`- ${obj.Key}`);
});
}
// Get all results at once
const allPages = await paginator.toArray();
const totalObjects = allPages.reduce((sum, page) => sum + (page.KeyCount || 0), 0);
console.log(`Total objects across all pages: ${totalObjects}`);
// Manual pagination with more control
async function listObjectsWithManualPagination(bucket: string) {
const results = [];
let nextToken: string | undefined;
do {
const command = new ListObjectsV2Command({
Bucket: bucket,
ContinuationToken: nextToken,
MaxKeys: 500
});
const response = await client.send(command);
if (response.Contents) {
results.push(...response.Contents);
}
nextToken = response.NextContinuationToken;
// Add delay to avoid rate limiting
if (nextToken) {
await new Promise(resolve => setTimeout(resolve, 100));
}
} while (nextToken);
return results;
}
const allObjects = await listObjectsWithManualPagination("my-large-bucket");
console.log(`Retrieved ${allObjects.length} total objects`);Advanced filtering options for object listings.
// Optional object attributes
type OptionalObjectAttributes =
| "RestoreStatus";
// Encoding types
type EncodingType = "url";
// Storage class for objects
type ObjectStorageClass =
| "STANDARD"
| "REDUCED_REDUNDANCY"
| "GLACIER"
| "STANDARD_IA"
| "ONEZONE_IA"
| "INTELLIGENT_TIERING"
| "DEEP_ARCHIVE"
| "OUTPOSTS"
| "GLACIER_IR"
| "SNOW"
| "EXPRESS_ONEZONE";
// Request payer options
type RequestPayer = "Requester";
// Restore status for archived objects
interface RestoreStatus {
/** Restore in progress flag */
IsRestoreInProgress?: boolean;
/** Restore expiry date */
RestoreExpiryDate?: Date;
}Advanced Filtering Example:
import { S3Client, ListObjectsV2Command } from "@aws-sdk/client-s3";
const client = new S3Client({ region: "us-east-1" });
// List objects with advanced filtering
async function listObjectsWithFiltering(
bucket: string,
options: {
prefix?: string;
delimiter?: string;
startAfter?: string;
maxKeys?: number;
fetchOwner?: boolean;
} = {}
) {
const command = new ListObjectsV2Command({
Bucket: bucket,
Prefix: options.prefix,
Delimiter: options.delimiter,
StartAfter: options.startAfter,
MaxKeys: options.maxKeys || 1000,
FetchOwner: options.fetchOwner || false,
OptionalObjectAttributes: ["RestoreStatus"]
});
const response = await client.send(command);
// Process results
const results = {
objects: response.Contents || [],
commonPrefixes: response.CommonPrefixes || [],
truncated: response.IsTruncated || false,
nextToken: response.NextContinuationToken
};
// Filter by additional criteria
const activeObjects = results.objects.filter(obj =>
!obj.RestoreStatus?.IsRestoreInProgress
);
const largeObjects = results.objects.filter(obj =>
(obj.Size || 0) > 1024 * 1024 // > 1MB
);
return {
...results,
activeObjects,
largeObjects
};
}
// Usage
const filtered = await listObjectsWithFiltering("my-bucket", {
prefix: "documents/",
delimiter: "/",
maxKeys: 500,
fetchOwner: true
});
console.log(`Found ${filtered.objects.length} total objects`);
console.log(`Found ${filtered.activeObjects.length} active objects`);
console.log(`Found ${filtered.largeObjects.length} large objects`);
console.log(`Found ${filtered.commonPrefixes.length} subdirectories`);