aws s3api list-objects-v2: List S3 Objects in CI
aws s3api list-objects-v2 returns object keys and metadata under a prefix, with built-in pagination, giving CI scriptable access to bucket contents that aws s3 ls does not expose as JSON.
When a job needs structured output (keys, sizes, timestamps) rather than the human listing from aws s3 ls, list-objects-v2 is the API-level call you script against.
What it does
aws s3api list-objects-v2 lists objects in --bucket optionally restricted by --prefix. The CLI paginates automatically across the 1000-key API limit unless you set --page-size or --max-items. --query selects keys or computes things like the newest object.
Common usage
# All keys under a prefix
aws s3api list-objects-v2 \
--bucket my-artifacts --prefix builds/ \
--query 'Contents[].Key' --output text
# Newest object key under a prefix
aws s3api list-objects-v2 \
--bucket my-artifacts --prefix builds/ \
--query 'sort_by(Contents, &LastModified)[-1].Key' --output textOptions
| Flag | What it does |
|---|---|
| --bucket <name> | Bucket to list (required) |
| --prefix <path> | Restrict to keys starting with this prefix |
| --delimiter / | Group keys into CommonPrefixes (folder view) |
| --max-items <n> | Cap total items returned (client-side) |
| --page-size <n> | API page size for pagination |
| --query <jmespath> | Select keys, sort by LastModified, etc. |
In CI
The CLI auto-paginates, so Contents[].Key returns every key even past 1000; use --max-items if you only need a sample. An empty prefix returns Contents: null, and --query Contents[].Key then prints nothing rather than erroring, so guard for empty results. Prefer list-objects-v2 over the deprecated list-objects.
Common errors in CI
"An error occurred (NoSuchBucket) when calling the ListObjectsV2 operation: The specified bucket does not exist" means a wrong name or region (S3 errors are region-sensitive). "AccessDenied" means missing s3:ListBucket (note that is ListBucket on the bucket ARN, not s3:GetObject). "An error occurred (AllAccessDisabled)" appears when the bucket is blocked by an account-level policy.