Object Storage - How to retrieve object metadata with GetObjectAttributes

Objective

This guide explains how to use the GetObjectAttributes S31 API operation to retrieve metadata attributes from objects in your OVHcloud Object Storage buckets without downloading the object body.

Requirements

Instructions

Why use GetObjectAttributes?

Inspecting an object's metadata traditionally requires at least 2 separate API calls: HeadObject to retrieve the ETag, size, and storage class, and ListParts to enumerate the parts of multipart objects. Each additional call adds latency, which becomes significant at scale in data pipelines, integrity verification workflows, or storage auditing systems.

GetObjectAttributes consolidates all attribute retrieval into a single selective API call. You request exactly the attributes you need; the service returns only those fields — no object body is transferred.

Key benefits:

  • No body transfer: retrieve metadata only, regardless of object size.
  • Selective response: receive only the attributes you request.
  • Any S3-compatible client: works with AWS CLI, any S3 SDK, and direct HTTP calls.

Supported attributes

You select which attributes to retrieve by listing them in the x-amz-object-attributes request header (space-separated for AWS CLI, comma-separated for raw HTTP). Attributes not listed are absent from the response.

AttributeDescription
ETagOpaque identifier representing a specific version of the object's content
ChecksumChecksum value computed using the algorithm stored with the object at upload time
ObjectPartsMultipart structure of the object: list of parts with their number, size, and optional checksum
StorageClassStorage class of the object (STANDARD, STANDARD_IA, GLACIER_IR, DEEP_ARCHIVE, EXPRESS_ONEZONE)
ObjectSizeTotal size of the object in bytes

The Last-Modified response header is always returned regardless of which attributes are requested.

Info

The x-amz-object-attributes header is required. A request without it returns 400 Bad Request. Attribute names are case-sensitive.

Retrieve object attributes

Via AWS CLI
Via curl (S3 REST API)
# Retrieve ETag and size
aws s3api get-object-attributes \
  --bucket <bucket_name> \
  --key <object_key> \
  --object-attributes ETag ObjectSize

Successful response:

{
    "LastModified": "2026-04-15T10:23:45+00:00",
    "ETag": "d41d8cd98f00b204e9800998ecf8427e",
    "ObjectSize": 1048576
}

To request all attributes at once:

aws s3api get-object-attributes \
  --bucket <bucket_name> \
  --key <object_key> \
  --object-attributes ETag Checksum ObjectParts StorageClass ObjectSize

Checksum attribute

When Checksum is requested, the response includes the algorithm and value stored with the object at upload time. If the object was uploaded without a checksum, the Checksum element is absent from the response — this is not an error.

Supported checksum algorithms on OVHcloud Object Storage:

AlgorithmXML element in response
CRC-32ChecksumCRC32
CRC-32CChecksumCRC32C
CRC-64/NVMEChecksumCRC64NVME
SHA-1ChecksumSHA1
SHA-256ChecksumSHA256
Via AWS CLI
Via curl (S3 REST API)
aws s3api get-object-attributes \
  --bucket `<bucket_name>` \
  --key `<object_key>` \
  --object-attributes Checksum

Response (object has a CRC32 checksum):

&#123;
    "LastModified": "2026-04-15T10:23:45+00:00",
    "Checksum": &#123;
        "ChecksumCRC32": "aGVsbG8="
    &#125;
&#125;

Response (object has no checksum):

&#123;
    "LastModified": "2026-04-15T10:23:45+00:00"
&#125;

ObjectParts attribute (multipart objects)

When ObjectParts is requested on a multipart object, the response lists all parts with their number, size, and optional checksum. For single-part (non-multipart) objects, ObjectParts is returned as an empty element.

Info

Only part details (size, checksum, pagination) of objects created with checksum type COMPOSITE will be listed, i.e., when you create your multipart upload, you need to set the x-amz-checksum-type header to COMPOSITE.

Pagination: results are paginated at up to 1000 parts per response.

Via AWS CLI
Via curl (S3 REST API)
# List all parts (default: up to 1000)
aws s3api get-object-attributes \
  --bucket <bucket_name> \
  --key <object_key> \
  --object-attributes ObjectParts

Response:

{
    "LastModified": "2026-04-20T08:10:00+00:00",
    "ObjectParts": {
        "TotalPartsCount": 3,
        "MaxParts": 1000,
        "IsTruncated": false,
        "Parts": [
            { "PartNumber": 1, "Size": 5242880 },
            { "PartNumber": 2, "Size": 5242880 },
            { "PartNumber": 3, "Size": 1048576 }
        ]
    }
}
Paginating through ObjectParts (objects with more than 1000 parts)

When an object has more than 1000 parts, IsTruncated is true and NextPartNumberMarker indicates where to resume. Use --part-number-marker to fetch subsequent pages.

Via AWS CLI
Via curl (S3 REST API)
# First page
aws s3api get-object-attributes \
  --bucket `<bucket_name>` \
  --key `<object_key>` \
  --object-attributes ObjectParts \
  --max-parts 1000

# Next page - use NextPartNumberMarker from the previous response
aws s3api get-object-attributes \
  --bucket `<bucket_name>` \
  --key `<object_key>` \
  --object-attributes ObjectParts \
  --max-parts 1000 \
  --part-number-marker `<next_part_number_marker>`

Versioned objects

By default, GetObjectAttributes operates on the current version of the object. To retrieve attributes for a specific version, add --version-id to the request.

Via AWS CLI
Via curl (S3 REST API)
aws s3api get-object-attributes \
  --bucket <bucket_name> \
  --key <object_key> \
  --version-id <version_id> \
  --object-attributes ETag ObjectSize StorageClass

The x-amz-version-id response header echoes the version ID of the retrieved object.

Info

IAM permissions with versionId: using --version-id requires the s3:GetObjectVersion and s3:GetObjectVersionAttributes permissions, instead of the default s3:GetObject + s3:GetObjectAttributes.

Encrypted objects (SSE-C)

For objects encrypted with SSE-C (customer-provided keys), you must supply the three encryption headers with every GetObjectAttributes request. The service does not store the key.

Via AWS CLI
Via curl (S3 REST API)
aws s3api get-object-attributes \
  --bucket <bucket_name> \
  --key <object_key> \
  --object-attributes ETag ObjectSize \
  --sse-customer-algorithm AES256 \
  --sse-customer-key <base64_encoded_256_bit_key> \
  --sse-customer-key-md5 <base64_encoded_md5_of_key>
Warning

All three SSE-C headers are mandatory for SSE-C objects. Omitting any one of them returns 400 Bad Request. Providing the wrong key returns 403 Forbidden.

For unencrypted and SSE-S3 objects, do not include SSE-C headers — including them returns 400 Bad Request.

IAM permissions

SituationRequired permissions
Without versionIds3:GetObject + s3:GetObjectAttributes
With versionIds3:GetObjectVersion + s3:GetObjectVersionAttributes

No additional permissions are required beyond the standard read permissions.

Error codes

HTTP codeError codeCondition
200 OK-Request successful
400 Bad RequestInvalidArgumentMissing x-amz-object-attributes, invalid attribute name, or invalid SSE-C header combination
403 ForbiddenAccessDeniedMissing IAM permission, or wrong SSE-C key
404 Not FoundNoSuchKeyObject does not exist and requester has s3:ListBucket
403 ForbiddenAccessDeniedObject does not exist and requester does NOT have s3:ListBucket
405 Method Not Allowed-The target version is a delete marker
Info

Delete markers: in a versioned bucket, if the current version of an object (or the version specified by --version-id) is a delete marker, the service returns 405 Method Not Allowed with the x-amz-delete-marker: true response header.

Go further

Join our community of users.

1: S3 is a trademark of Amazon Technologies, Inc. OVHcloud's service is not sponsored by, endorsed by, or otherwise affiliated with Amazon Technologies, Inc.

Was this page helpful?