Set Blob Tags

The Set Blob Tags operation sets user-defined tags for the specified blob as one or more key-value pairs.


The Set Blob Tags request may be constructed as follows. We recommend that you use HTTPS. Replace myaccount with the name of your storage account:

PUT method request URI HTTP version<DateTime>

URI parameters

You can specify the following additional parameters on the request URI:

Parameter Description
versionid Optional for version 2019-12-12 and later. The versionid parameter is an opaque DateTime value that, when present, specifies the version of the blob to retrieve.
timeout Optional. The timeout parameter is expressed in seconds. For more information, see Set time-outs for Blob Storage operations.

Request headers

The required and optional request headers are described in the following table:

Request header Description
Authorization Required. Specifies the authorization scheme, account name, and signature. For more information, see Authorize requests to Azure Storage.
Date or x-ms-date Required. Specifies the Coordinated Universal Time (UTC) for the request. For more information, see Authorize requests to Azure Storage.
x-ms-version Required for all authorized requests. Specifies the version of the operation to use for this request. For more information, see Versioning for the Azure Storage services.
Content-Length Required. The length of the request content in bytes. This header refers to the content length of the tags document, not of the blob itself.
Content-Type Required. The value of this header should be application/xml; charset=UTF-8.
Content-MD5 Optional. An MD5 hash of the request content. This hash is used to verify the integrity of the request content during transport. If the two hashes don't match, the operation fails with error code 400 (Bad Request).

This header is associated with the request content, and not with the content of the blob itself.
x-ms-content-crc64 Optional. A CRC64 hash of the request content. This hash is used to verify the integrity of the request content during transport. If the two hashes don't match, the operation fails with error code 400 (Bad Request).

This header is associated with the request content, and not with the content of the blob itself.

If both Content-MD5 and x-ms-content-crc64 headers are present, the request fails with error code 400 (Bad Request).
x-ms-lease-id:<ID> Required if the blob has an active lease.

To perform this operation on a blob with an active lease, specify the valid lease ID for this header. If a valid lease ID isn't specified on the request, the operation fails with status code 403 (Forbidden).
x-ms-client-request-id Optional. Provides a client-generated, opaque value with a 1-kibibyte (KiB) character limit that's recorded in the logs when logging is configured. We highly recommend that you use this header to correlate client-side activities with requests that the server receives. For more information, see Monitor Azure Blob Storage.

This operation supports the x-ms-if-tags conditional header to set blob tags only if a specified condition is met. For more information, see Specify conditional headers for Blob Storage operations.

Request body

The format of the request body is as follows:

<?xml version="1.0" encoding="utf-8"?>  

The request body must be a well-formed UTF-8 XML document and contain a tag set that represents the tags for the blob.

The tag set may contain no more than 10 tags. Tag keys and values are case-sensitive. Tag keys must be from 1 to 128 characters, and tag values must be from 0 to 256 characters. Valid tag key and value characters include:

  • Lowercase and uppercase letters (a-z, A-Z)
  • Digits (0-9)
  • A space ( )
  • Plus (+), minus (-), period (.), slash (/), colon (:), equals (=), and underscore (_)


The response includes an HTTP status code and a set of response headers.

Status code

A successful operation returns status code 204 (No Content).

For more information about status codes, see Status and error codes.

Response headers

The response for this operation includes the following headers. The response may also include additional standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.

Response header Description
x-ms-request-id Uniquely identifies the request that was made and can be used to troubleshoot the request. For more information, see Troubleshoot API operations.
x-ms-version The Blob Storage version that was used to execute the request.
Date A UTC date/time value that's generated by the service, which indicates the time when the response was initiated.
x-ms-client-request-id Can be used to troubleshoot requests and corresponding responses. The value of this header is equal to the value of the x-ms-client-request-id header if it's present in the request and the value contains no more than 1,024 visible ASCII characters. If the x-ms-client-request-id header isn't present in the request, it won't be present in the response.

Response body



Authorization is required when calling any data access operation in Azure Storage. You can authorize the Set Blob Tags operation as described below.

Azure Storage supports using Microsoft Entra ID to authorize requests to blob data. With Microsoft Entra ID, you can use Azure role-based access control (Azure RBAC) to grant permissions to a security principal. The security principal may be a user, group, application service principal, or Azure managed identity. The security principal is authenticated by Microsoft Entra ID to return an OAuth 2.0 token. The token can then be used to authorize a request against the Blob service.

To learn more about authorization using Microsoft Entra ID, see Authorize access to blobs using Microsoft Entra ID.


Listed below are the RBAC action necessary for a Microsoft Entra user, group, or service principal to call the Set Blob Tags operation, and the least privileged built-in Azure RBAC role that includes this action:

To learn more about assigning roles using Azure RBAC, see Assign an Azure role for access to blob data.


The Set Blob Tags operation is supported in REST API version 2019-12-12 and later.

The Set Blob Tags operation overwrites all existing tags on the blob. To remove all tags from a blob, send a Set Blob Tags request with an empty <TagSet>.

This operation doesn't update the ETag or last modified time of the blob. It's possible to set tags on an archived blob.

The storage service maintains strong consistency between a blob and its tags. Changes to blob tags are immediately visible to subsequent Get Blob Tags operations on the blob. The secondary index, however, is eventually consistent. Changes to a blob's tags might not be immediately visible to Find Blobs by Tags operations.

If a request provides invalid tags, Blob Storage returns status code 400 (Bad Request).


Pricing requests can originate from clients that use Blob Storage APIs, either directly through the Blob Storage REST API, or from an Azure Storage client library. These requests accrue charges per transaction. The type of transaction affects how the account is charged. For example, read transactions accrue to a different billing category than write transactions. The following table shows the billing category for Set Blob Tags requests based on the storage account type:

Operation Storage account type Billing category
Set Blob Tags Premium block blob
Standard general-purpose v2
Other operations
Set Blob Tags Standard general-purpose v1 Write operations

To learn about pricing for the specified billing category, see Azure Blob Storage Pricing.

See also

Manage and find Blob Storage data with blob index tags
Authorize requests to Azure Storage
Status and error codes
Blob Storage error codes