Azure blob storage Index tags- upload file with index tags using REST API

Azure blob storage Index tags- upload file with index tags using REST API

As datasets get larger, finding specific objects from millions of blobs is very difficult. Azure blob storage provides a feature called Blob Index tags which are key-value pairs associated with blob. Blob index tags are primarily used to categorize data in your storage account using key-value tag attributes. These tags are automatically indexed and exposed as a searchable multi-dimensional index to easily find data.

Note: This feature is available only with Azure blob storage (hierarchical namespace disabled) and not with Azure datalake.

Advantages and Limitations-

Blob index tags let you:

  • Dynamically categorize your blobs using key-value index tags

  • Quickly find specifically tagged blobs across an entire storage account (all containers)

  • Specify conditional behaviours for blob APIs based on the evaluation of index tags

  • Use index tags for advanced controls on features like blob lifecycle management

The following limits apply to blob index tags:

  • Each blob can have up to 10 blob index tags

  • Tag keys must be between one and 128 characters

  • Tag values must be between zero and 256 characters

  • Tag keys and values are case-sensitive

  • Tag keys and values only support string data types. Any numbers, dates, times, or special characters are saved as strings

  • Tag keys and values must adhere to the following naming rules:

    • Alphanumeric characters:

      • a through z (lowercase letters)

      • A through Z (uppercase letters)

      • 0 through 9 (numbers)

    • Valid special characters: space, plus, minus, period, colon, equals, underscore, forward slash ( +-.:=_/)

We can set these tags while uploading files manually as well as while uploading via API. Follow the below steps to add tags while uploading files from Postman.


  1. Azure storage account with container should be created.

  2. Register one app in Azure AD and get the client id and client secret for the same. This app will be used to assign RBAC and get bearer token.


  1. For index tags data operation, the app needs to have Azure Blob Data Owner role. Thus, assign this role to the app.

  2. Follow the steps mentioned in this blog and create a PUT blob request in Postman. You can skip the role assignment step from this blob as we have already set the Blob Data Owner role.

  3. Add one more header parameter as x-ms-tags with the required tags in key-value format as below.

    Here, we have mentioned two tags- fileType=demo and env=dev.

  4. Send the request and it will create a blob with given tags in storage account.


In this blog, we understood basic idea about what are blob index tags and how to upload blob with index tags using rest API.

Thank you for reading.

Keep learning!

Note: To learn more about search blob by index tags API, follow the second part of this blog here.

Did you find this article valuable?

Support Suraj Somani by becoming a sponsor. Any amount is appreciated!