Object Metadata

This page discusses the metadata fields that are stored along with objects in Google Cloud Storage. To learn how to view and set metadata on objects, see Viewing and Editing Object Metadata.


Objects stored in Cloud Storage have metadata associated with them. Metadata identifies properties of the object, as well as specifies how the object should be handled when it's accessed. Metadata exists as key:value pairs. For example, the storage class of an object is represented by the metadata entry storageClass:REGIONAL. storageClass is the key for the metadata, and all objects have such a key associated with them. REGIONAL specifies the value this specific object has, and the value varies from object to object.

The mutability of metadata varies: some metadata you can edit at any time, some metadata you can only set at the time the object is created, and some metadata you can only view. For example, you can edit the value of the Cache-Control metadata at any time, but you can only assign the storageClass metadata when the object is created or rewritten, and you cannot directly edit the value for the generation metadata, though the generation value changes when the object is overwritten.

Editable metadata

There are two categories of metadata that users can change for objects:

  • Fixed-key metadata: Metadata whose keys are set, but for which you can specify a value.

  • Custom metadata: Metadata that you add by specifying both a key and a value associated with the key.

When editing metadata, you should generally avoid non-ascii characters, because they are not permitted in HTTP headers, which the XML API uses. When using the XML API, there is also a 16KB limit to the combined size of the request URL and HTTP headers, so the total size of your metadata should take this limit into account.

Fixed-key metadata

You can edit the following metadata for objects, though you must have sufficient permission to do so:

Access control metadata

Cloud Storage uses Identity and Access Management (IAM) and Access Control Lists (ACLs) to control access to objects. Use these links to learn about these access control methods and associated metadata.


The Cache-Control metadata can specify two different aspects of how data is served from Cloud Storage: whether the data can be cached and whether the data can be transformed.

Caching data

The Cache-Control metadata allows you to control whether and for how long browser and Internet caches are allowed to cache your objects. Setting the value of Cache-Control to no-cache means the object should not be cached, while setting the value to max-age=[TIME_IN_SECONDS] means the object can be cached for up to specified length of time.

Cache-Control only applies to objects that are publicly accessible, because non-public data are not cacheable. Unless otherwise specified, the Cache-Control setting for publicly accessible objects is 3600 seconds.

If you allow caching, at download time you might see older versions of objects, even after uploading a newer replacement object, because the older objects remain in the cache for a period of time. Additionally, because objects can be cached at various places on the Internet, there is no way to force a cached object to expire globally. If you want to prevent caching of publicly readable objects, you should set Cache-Control:private on the object.

Transforming data

Cache-Control metadata also allows you to serve objects as they are stored, without applying any transformations to the data, such as removing gzip content-encoding for incompatible clients. To serve an object as-is, set Cache-Control:no-transform.


The Content-Disposition metadata specifies presentation information about the data being transmitted. Setting Content-Disposition allows you to control presentation style of the content, for example determining whether an attachment should be automatically displayed or whether some form of action from the user should be required to open it. See https://tools.ietf.org/html/rfc6266 for the Content-Disposition specification.


The Content-Encoding metadata can be used to indicate that an object is compressed, while still maintaining the object's underlying Content-Type. For example, a text file that is gzip compressed can have the fact that it's a text file indicated in Content-Type and the fact that it's gzip compressed indicated in Content-Encoding. You should ensure that files are, in fact, compressed using the specified Content-Encoding before uploading them, or else unexpected behavior can occur when attempting to download the objects. For more information, see the Transcoding page.

For compressible content, such as text, using Content-Encoding: gzip saves network and storage costs and improves content serving performance. However, for content that is already inherently compressed, such as archives and many media formats, applying another level of compression and marking it in the Content-Encoding metadata is typically detrimental to both object size and performance and should be avoided.


The Content-Language metadata indicates the lanuage(s) that the object is intended for. Refer to ISO 639-1 language codes for the supported values of this metadata.


The most commonly set metadata is Content-Type (also known as MIME type), which allows browsers to render the object properly. All objects have a value specified in their Content-Type metadata, but this value does not have to match the underlying type of the object. For example, if the Content-Type is not specified by the uploader and cannot be determined, it is set to application/octet-stream or application/x-www-form-urlencoded, depending on how you uploaded the object.

Custom metadata

Custom metadata is metadata that you can add and remove. To create custom metadata, you specify both a value and a key. Once you have created a custom metadata key:value pair, you can delete the key or change the value.

The Viewing and Editing Metadata page includes information on setting custom metadata. Note that using custom metadata incurs storage and network costs.

Non-editable metadata

Some metadata cannot be edited directly. This metadata is set at the time of object creation or rewrite. As part of the object creation or rewrite, you can set some such metadata, such as the storage class of the object or customer-supplied encryption keys. Other metadata is automatically added and can only be viewed, such the generation number of the object or the time of creation.

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Cloud Storage Documentation