--- title: "S3 Tagging" slug: "s3-tagging" updated: 2026-10-27T17:23:57Z published: 2026-10-27T17:23:57Z canonical: "docs.vastdata.com/s3-tagging" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.vastdata.com/llms.txt > Use this file to discover all available pages before exploring further. # S3 Tagging An S3 tag is a key-value pair that is used to categorize objects. You can add tags to new objects when you upload them or add tags to existing buckets and objects. S3 object tags and bucket tags can be added to objects and buckets via S3 API calls. Tags are stored per element. If [VAST Catalog](/docs-5-3/docs/en/vast-catalog-overview) is enabled, S3 tags are saved together with other element attributes, which lets you search for data based on S3 tags. ## Restrictions and Limitations - You can associate up to 40 tags with an object. - The key and values are case sensitive. - Tags that are associated with an object must have unique tag keys. - A tag key can be up to 128 Unicode characters in length, and tag values can be up to 256 Unicode characters in length. - Tags are not supported in [lifecycle rules](/docs-5-3/docs/en/overview-of-lifecycle-rules), such as to limit the scope of objects to those that have a given tag. Managing Identity Policies ## Object Tagging and Replication If you configure replication on S3 buckets and objects that have tags, the tags are replicated. ## Managing S3 Tags The following S3 API requests and headers are supported and require user permission to perform the relevant actions. Permission to perform these actions can be granted through S3 identity policies. | Operation | Request Type | Action Requiring Permission | More details | | --- | --- | --- | --- | | Set tags to an object | `PutObjectTagging` | Permission to perform the `s3:PutObjectTagging` action. | You specify tags in the request body. When this operation sets the tags for an object, it will overwrite any current tags the bucket already has. You cannot use this operation to add tags to an existing list of tags. | | Return the tag-set associated with an object | `GetObjectTagging` | Permission to perform the `s3:GetObjectTagging` action | The object tags are returned in the response body. | | Remove the entire tag set associated with an object | `DeleteObjectTagging` | Permission to perform the s3:DeleteObjectTagging action | | | Set tags on a bucket | `PutBucketTagging` | Permissions to perform the `s3:PutBucketTagging` action | When this operation sets the tags for a bucket, it will overwrite any current tags the bucket already has. You cannot use this operation to add tags to an existing list of tags. | | Return the tag set associated with a bucket | `GetBucketTagging` | Permission to perform the `s3:GetBucketTagging` action | | | Delete the tags from a bucket | `DeleteBucketTagging` | Permission to perform the `s3:DeleteBucketTagging` action. | | | Set tags when uploading an object | When uploading with a `PutObject` or `CreateMultipartUpload` request, you can use the `x-amz-tagging` header to set tags. | Permission to perform the `s3:PutObject` action. | The tag-set must be encoded as URL Query parameters. (For example, "Key1=Value1") | | Return object tag count | The `GetObject` response contains the object tag count in the `x-amz-tagging-count` header. | Permission to perform the `s3:GetObject` action | | | Copy or replace tags when copying an object | When making an `CopyObject` request to copy an object, you can use the `x-amz-tagging-directive` header to specify whether to copy (default behavior) the tags or replace tags by a new set of tags. If replacing the tags, provide the tags using the `x-amz-tagging` header. The tag-set must be URL encoded. | Permission to perform the `S3::CopyObject` action | `x-amz-tagging-directive` specifies whether the object tag-set is copied from the source object or replaced with a tag-set provided in the request. Valid values: - `COPY` - `REPLACE` | ## Tagging Examples This example uses the [put_object_tagging](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3/client/put_object_tagging.html) Boto3 client method to create a tagset consisting of a single tag with key "department" and value "Sales": ```plaintext put_object_tagging( Bucket=S3_BUCKET, Key=s3_key, Tagging={ 'TagSet': [ { 'Key': 'Department', 'Value': 'Sales' }] }, ) ``` In this example, also using Boto client, tags are passed in a [put_object](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3/client/put_object.html) request ```plaintext put_object(Bucket=S3_BUCKET, Key=s3_key, Tagging="Department=Sales&Company=Vast") ``` ## Querying VAST Catalog for S3 Tags VAST Catalog indexes S3 tags in a column called `user_tags`, enabling data to be searchable by the key-value pairs contained in the tags. For more granular searchability, you can also define a VAST Catalog column per key value so that users can use VAST Catalog to search for data by key value. For example, if you use tagging to classify objects per department, using tags with key "Department" and values per department, such as "Sales", "Marketing," and "Product", you can add a column for the key value "Department" and that will enable users to search for all objects belonging to "Sales," by querying the "Department" column that you defined and searching for the value "Sales". For details of how to configure VAST Catalog and add columns for S3 tags, see [Configuring VAST Catalog](/docs-5-3/docs/en/configuring-vast-catalog). For details of how to query VAST Catalog from VMS, see [Querying VAST Catalog from the VAST Web UI](/docs-5-3/docs/en/querying-vast-catalog-from-the-vast-web-ui). For all information about VAST Catalog, see [VAST Catalog](/docs-5-3/docs/en/vast-catalog-overview).