# Object Storage API, Amazon S3-compatible REST: HeadObject

Returns object metadata.

The method is equivalent to [get](get.md), except the object is not included in the response.

For more information on getting started with the API and the general request format, see [How to use the S3 API](../../index.md).

## Request {#request}

```http
HEAD /{bucket}/{key} HTTP/2
```

### Path parameters {#path-parameters}

Parameter | Description
----- | -----
`bucket` | Bucket name.
`key` | Object key.


### Query parameters {#request-params}

Parameter | Description
----- | -----
`range` | Defines the range of bytes to load from the object, e.g., `?range=bytes=1-5`.<br/><br/>If used together with the `Range` header, only the header value will be taken.
`response-content-type` | Sets the `Content-Type` response header.
`response-content-language` | Sets the `Content-Language` response header.
`response-expires` | Sets the `Expires` response header.
`response-cache-control` | Sets the `Cache-Control` response header.
`response-content-disposition` | Sets the `Content-Disposition` response header.
`response-content-encoding` | Sets the `Content-Encoding` response header.
`versionId` | Link to a specific version of the object.


### Headers {#request-headers}

Use the appropriate [common headers](../common-request-headers.md) in your request.

You can also use the following headers in your request:

Header | Description
----- | -----
`Range` | Defines the range of bytes to load from the object, e.g., `--header 'Range: bytes=1-5'`.<br/><br/>If used together with the `range` query parameter, only the header value will be taken.<br/><br/>To learn more about the `Range` header, see [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-range).
`If-Modified-Since` | If it is specified, Object Storage returns the following:<br/>- Object. If it has been modified since the specified time.<br/>- Code 304. If the object has not been modified since the specified time.<br/><br/>If a request has both the `If-Modified-Since` and `If-None-Match` headers and their checks result in `If-Modified-Since -> true` and `If-None-Match -> false`, Object Storage returns a 304 code. For more information, see [RFC 7232](https://tools.ietf.org/html/rfc7232).
`If-Unmodified-Since` | If it is specified, Object Storage returns the following:<br/>- Object. If it has not been modified since the specified time.<br/>- Code 412. If the object has been modified since the specified time.<br/><br/>If a request has both the `If-Unmodified-Since` and `If-Match` headers and their checks result in `If-Unmodified-Since -> false` and `If-Match -> true`, Object Storage returns a 200 code and the requested data. For more information, see [RFC 7232](https://tools.ietf.org/html/rfc7232).
`If-Match` | If it is specified, Object Storage returns the following:<br/><br/>- Object. If its `ETag` matches the provided one.<br/>- Code 412. If its `ETag` does not match the provided one.<br/><br/><br/>If a request has both the `If-Unmodified-Since` and `If-Match` headers and their checks result in `If-Unmodified-Since -> false` and `If-Match -> true`, Object Storage returns a 200 code and the requested data. For more information, see [RFC 7232](https://tools.ietf.org/html/rfc7232).
`If-None-Match` | If it is specified, Object Storage returns the following:<br/><br/>- Object. If its `ETag` does not match the provided one.<br/>- Code 304. If its `ETag` matches the provided one.<br/><br/><br/>If a request has both the `If-Modified-Since` and `If-None-Match` headers and their checks result in `If-Modified-Since -> true` and `If-None-Match -> false`, Object Storage returns a 304 code. For more information, see [RFC 7232](https://tools.ietf.org/html/rfc7232).

## Response {#response}

### Headers {#response-headers}

In addition to [common headers](../common-response-headers.md), you can see in a response the headers listed in the table below.


Header | Description
----- | -----
`X-Amz-Meta-*` | User-defined object metadata.
`X-Amz-Storage-Class` | [Storage class](../../../concepts/storage-class.md) of the object.<br/>It can be either `COLD` if the object is in a cold storage or `ICE` if it is in an ice storage.<br/><br/>If the object is in a standard storage, there is no header.
`X-Amz-Server-Side-Encryption` | Encryption algorithm used to encrypt the object. It is returned if the object was uploaded with [encryption](../../../operations/buckets/encrypt.md) enabled.
`X-Amz-Server-Side-Encryption-Aws-Kms-Key-Id` | [KMS key](../../../../kms/concepts/key.md) ID. It is returned if the object was uploaded with [encryption](../../../operations/buckets/encrypt.md) enabled.
`X-Amz-Object-Lock-Mode` | <p>Type of [retention](../../../concepts/object-lock.md) put on the object (if the bucket is [versioned](../../../concepts/versioning.md) and object lock is enabled in it):</p><ul><li>`GOVERNANCE`: Governance-mode retention.</li><li>`COMPLIANCE`: Compliance-mode retention.</li></ul><p>For an object version, you can use only retention (the `X-Amz-Object-Lock-Mode` and `X-Amz-Object-Lock-Retain-Until-Date` headers), only legal hold (`X-Amz-Object-Lock-Legal-Hold`), or both at the same time. For more information about their combined use, see [Object lock types](../../../concepts/object-lock.md#types).</p>
`X-Amz-Object-Lock-Retain-Until-Date` | Retention end date and time in any format described in the [HTTP standard](https://www.rfc-editor.org/rfc/rfc9110#name-date-time-formats), e.g., `Mon, 12 Dec 2022 09:00:00 GMT`. Specify it only with the `X-Amz-Object-Lock-Mode` header.
`X-Amz-Object-Lock-Legal-Hold` | <p>Type of [legal hold](../../../concepts/object-lock.md) put on the object (if the bucket is [versioned](../../../concepts/versioning.md) and object lock is enabled in it):</p><ul><li>`ON`: Enabled.</li><li>`OFF`: Disabled.</li></ul><p>For an object version, you can use only retention (the `X-Amz-Object-Lock-Mode` and `X-Amz-Object-Lock-Retain-Until-Date` headers), only legal hold (`X-Amz-Object-Lock-Legal-Hold`), or both at the same time. For more information about their combined use, see [Object lock types](../../../concepts/object-lock.md#types).</p>


### Response codes {#response-codes}

For a list of possible responses, see [Responses](../response-codes.md).

#### Related articles {#related-articles}

* [Object](../../../concepts/object.md)

* [Getting information about an object](../../../operations/objects/info.md)

#### See also {#see-also}

* [Getting started with the AWS S3 API in Yandex Object Storage](../../s3-api-quickstart.md)

* [Debugging requests using the AWS CLI](../../signing-requests.md#debugging)

* [Example of sending a signed request using curl](../../../api-ref/authentication.md#s3-api-example)

* [Code example for generating a signature](../../../concepts/pre-signed-urls.md#code-examples)