← All posts

☁️AWS from Zero

S3 5 · Part 15 of 394
2 min read

Inspect an S3 object with head-object

#aws#cli#s3#storage
📑 On this page

Part 15 of AWS from Zero. Today we focus on one command:

aws s3api head-object

This command is small, but it becomes useful constantly.

What we are learning

head-object retrieves object metadata without returning the object body. Use it when you want to know whether an object exists, how large it is, what content type it has, or what metadata is attached.

Before you run it

aws sts get-caller-identity
REGION="ap-south-1"
BUCKET="aws-zero-head-object-12345"

Create a bucket:

aws s3api create-bucket \
  --bucket "$BUCKET" \
  --region "$REGION" \
  --create-bucket-configuration LocationConstraint="$REGION"

Create and upload a file:

echo "head-object demo" > object.txt
aws s3api put-object \
  --bucket "$BUCKET" \
  --key object.txt \
  --body object.txt \
  --content-type "text/plain" \
  --metadata "series=aws-from-zero"

The command

aws s3api head-object \
  --bucket "$BUCKET" \
  --key object.txt

The response includes fields like:

  • ContentLength
  • ContentType
  • ETag
  • LastModified
  • Metadata

Inspect only what matters

Use --query:

aws s3api head-object \
  --bucket "$BUCKET" \
  --key object.txt \
  --query "{Size:ContentLength,Type:ContentType,Updated:LastModified,Metadata:Metadata}" \
  --output table

This is much easier to read than the full JSON response.

One tiny variation

Check a key that does not exist:

aws s3api head-object \
  --bucket "$BUCKET" \
  --key missing.txt

Depending on your permissions, S3 may return 404 Not Found or 403 Forbidden. If you have permission to list the bucket, missing objects are easier to distinguish. Without list permission, S3 may hide whether the object exists.

Common mistake

Do not add encryption headers to a normal head-object request just because the object is encrypted with S3-managed or KMS-managed encryption. Those headers are for upload behavior, not for changing encryption during metadata reads.

For a beginner flow, keep head-object simple:

aws s3api head-object \
  --bucket "$BUCKET" \
  --key object.txt

Cleanup

aws s3 rm "s3://$BUCKET/" --recursive
aws s3api delete-bucket --bucket "$BUCKET" --region "$REGION"
rm object.txt

Next, we will copy objects inside one bucket and inspect what changed.