Get Blob Layout

The Get Blob Layout operation returns all user-defined metadata, standard HTTP properties, and system properties for the blob. In addition, it may optionally return the layout of the blob. The layout of a blob is a sub-resource of a blob that contains a breakdown of all the ranges in the blob, with an endpoint (address) where that range can be read, providing hints on how to best parallelize reads.

Using this API, you can optimize a download operation by performing the following two steps:

  1. Layout Discovery: Call Get Blob Layout to fetch the properties of the blob and discover its data distribution.
  2. Parallel Get Blob: Call Get Blob in parallel for all the blob ranges you're interested in, using the endpoints returned from the blob layout to route these requests to the optimal location.

Request

You can construct the Get Blob Layout request as follows. We recommend that you use HTTPS. Replace myaccount with the name of your storage account:

GET method request URI HTTP version
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=layout

https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=layout&snapshot=<DateTime>

https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=layout&versionid=<DateTime>

https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=layout&versionid=<DateTime>&marker=<ContinuationToken>&maxresults=1000		 HTTP/1.0

HTTP/1.1

URI parameters

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

Parameter Description
snapshot Optional. The snapshot parameter is an opaque DateTime value that, when it's present, specifies the blob snapshot to retrieve. For more information about working with blob snapshots, see Create a snapshot of a blob.
versionid Optional. The versionid parameter is an opaque DateTime value that, when it's present, specifies the version of the blob to retrieve.
marker Optional. A continuation token returned by a previous Get Blob Layout request. Use this token to retrieve the next set of ranges. The marker is used to resume pagination when the response doesn't include all ranges for the blob or the specified range. If a marker is used, an If-Match header must also be included with an Etag from the previous request. For more information on how to use an If-Match header, see Specify conditional headers for Blob Storage operations. In addition, if the previous request included a Range or x-ms-range header, this request must also contain an identical header. If the last request did not include a range header, this request must also not include one.
maxresults Optional. The maximum number of ranges to return in the response. The API will never return more ranges than the value specified by maxresults.
timeout Optional. The timeout parameter is expressed in seconds. For more information, see Setting timeouts for Blob Storage operations.

Request headers

The following table describes required and optional request headers.

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. Specifies the version of the operation to use for this request. Get Blob Layout is only supported in version 2026-02-06 or later. For more information, see Versioning for the Azure Storage services.
Range or x-ms-range Optional. Return metadata only for the ranges specified. If both Range and x-ms-range are specified, the service uses the value of x-ms-range. If neither range is specified, metadata is returned for the entire blob. For more information, see Specify the range header for Blob Storage operations.
x-ms-lease-id: <ID> Optional. If this header is specified, the operation is performed only if both of the following conditions are met:

- The blob's lease is currently active.
- The lease ID that's specified in the request matches the lease ID of the blob.

If either of these conditions isn't met, the request fails, and the Get Blob Layout operation fails with status code 412 (Precondition Failed).
x-ms-upn Optional. Valid for accounts with hierarchical namespace enabled. If true, the user identity values that are returned in the x-ms-owner, x-ms-group, and x-ms-acl response headers will be transformed from Microsoft Entra object IDs to User Principal Names. If the value is false, they're returned as Microsoft Entra object IDs. The default value is false. Note that group and application object IDs are not translated, because they don't have unique friendly names.
x-ms-client-request-id Optional. Provides a client-generated, opaque value with a 1-kibibyte (KiB) character limit, which is recorded in the analytics logs when storage analytics logging is enabled. We highly recommend that you use this header when you're correlating client-side activities with requests that are received by the server. For more information, see About Azure Storage Analytics logging.

This operation also supports the use of conditional headers to return blob layout and properties only if a specified condition is met. For more information, see Specify conditional headers for Blob Storage operations. Note that an If-Match header is required when a marker is used in the URI parameters.

Request headers (customer-provided encryption keys)

You can specify the following headers on the request to read a blob that's encrypted with a customer-provided key. Encryption with a customer-provided key (and the corresponding set of headers) is optional. If a blob has previously been encrypted with a customer-provided key, you must include these headers on the request so that the operation can be completed successfully.

Request header Description
x-ms-encryption-key Required. The Base64-encoded AES-256 encryption key.
x-ms-encryption-key-sha256 Optional. The Base64-encoded SHA256 hash of the encryption key.
x-ms-encryption-algorithm: AES256 Required. Specifies the algorithm to use for encryption. The value of this header must be AES256.

Request body

None.

Response

The response includes an HTTP status code, a set of response headers, and optionally a response body containing the blob layout in XML format.

Status code

A successful operation returns one of two status codes:

  • HTTP 200 (OK) if the response includes a blob layout in the body.
  • HTTP 204 (No Content) if the server did not return a layout in the response body. In this case, the API is functionally equivalent to Get Blob Properties.

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
Content-Type Specifies the format in which the results are returned in the response body. The value is application/xml if the body is returned.
Content-Length Indicates the size of the response body, if it's returned.
Last-Modified The date/time when the blob was last modified. The date format follows RFC 1123. For more information, see Represent date/time values in headers.

Any operation that modifies the blob, including an update of the blob's metadata or properties, changes the last modified time of the blob.
x-ms-creation-time The date/time when the blob was created. The date format follows RFC 1123. For more information, see Represent date/time values in headers.
x-ms-meta-name:value A set of name-value pairs that correspond to the user-defined metadata that's associated with this blob.
x-ms-tag-count If the blob has any tags, returns the number of tags stored on the blob. This header isn't returned if there are no tags on the blob.
ETag Contains a value that you can use to perform operations conditionally. For more information, see Specify conditional headers for Blob Storage operations. The ETag value is enclosed in quotation marks.
x-ms-copy-completion-time:<datetime> Conclusion time of the last attempted Copy Blob operation where this blob was the destination blob. This value can specify the time of a completed, aborted, or failed copy attempt. This header doesn't appear if a copy is pending, if this blob has never been the destination in a Copy Blob operation, or if this blob has been modified after a concluded Copy Blob operation that uses Set Blob Properties, Put Blob, or Put Block List.
x-ms-copy-status-description: <error string> Appears only when x-ms-copy-status is failed or pending. Describes the cause of a fatal or non-fatal copy operation failure. This header doesn't appear if this blob has never been the destination in a Copy Blob operation, or if this blob has been modified after a concluded Copy Blob operation that uses Set Blob Properties, Put Blob, or Put Block List.
x-ms-copy-id: <id> The string identifier for the last attempted Copy Blob operation, where this blob was the destination blob. This header doesn't appear if this blob has never been the destination in a Copy Blob operation, or if this blob has been modified after a concluded Copy Blob operation that uses Set Blob Properties, Put Blob, or Put Block List.
x-ms-copy-progress: <bytes copied/bytes total> Contains the number of copied bytes and the total bytes in the source in the last attempted Copy Blob operation, where this blob was the destination blob. Can show from 0 to Content-Length copied bytes. This header doesn't appear if this blob has never been the destination in a Copy Blob operation, or if this blob has been modified after a concluded Copy Blob operation that uses Set Blob Properties, Put Blob, or Put Block List.
x-ms-copy-source: url A URL up to 2 KiB in length that specifies the source blob that was used in the last attempted Copy Blob operation, where this blob was the destination blob. This header doesn't appear if this blob has never been the destination in a Copy Blob operation, or if this blob has been modified after a concluded Copy Blob operation that uses Set Blob Properties, Put Blob, or Put Block List.

The URL that's returned in this header contains any request parameters that were used in the copy operation on the source blob. If the URL contains a Shared Access Signature (SAS) token, the signature (sig parameter) will not be included.
x-ms-copy-status: <pending \| success \| aborted \| failed> The state of the copy operation identified by x-ms-copy-id, with these values:

- success: Copy completed successfully.
- pending: Copy is in progress. Check x-ms-copy-status-description if intermittent, non-fatal errors impede copy progress but don’t cause failure.
- aborted: Copy was ended by Abort Copy Blob.
- failed: Copy failed. See x-ms-copy-status-description for failure details.

This header doesn't appear if this blob has never been the destination in a Copy Blob operation, or if this blob has been modified after a completed Copy Blob operation that uses Set Blob Properties, Put Blob, or Put Block List.
x-ms-incremental-copy: true Included if the blob is an incremental copy blob.
x-ms-copy-destination-snapshot:<datetime> Included if the blob is an incremental copy blob or incremental copy snapshot, if x-ms-copy-status is success. Snapshot time of the last successful incremental copy snapshot for this blob.
x-ms-lease-duration: <infinite \| fixed> When a blob is leased, specifies whether the lease is of infinite or fixed duration.
x-ms-lease-state: <available \| leased \| expired \| breaking \| broken> The lease state of the blob.
x-ms-lease-status:<locked\| unlocked> The lease status of the blob.
Cache-Control If the Cache-Control request header has previously been set for the blob, that value is returned in this header.
x-ms-request-id This header uniquely identifies the request that was made, and you can use it to troubleshoot the request. For more information, see Troubleshoot API Operations.
x-ms-version Indicates the Blob Storage version that's being used to execute the request.
Accept-Ranges: bytes Indicates that the service supports requests for partial blob content.
x-ms-server-encrypted: true/false The value of this header is set to true if the blob data and application metadata are completely encrypted using the specified algorithm. Otherwise, the value is set to false (when the blob is unencrypted, or if only parts of the blob/application metadata are encrypted).
x-ms-encryption-key-sha256 This header is returned if the blob is encrypted with a customer-provided key.
x-ms-encryption-context If the encryption context property value is set, it will return the set value. Valid only when Hierarchical Namespace is enabled for the account.
x-ms-encryption-scope This header is returned if the blob is encrypted with an encryption scope.
x-ms-access-tier The tier of a block blob in a Blob Storage or general purpose v2 account. Valid values are Hot, Cool, Cold, Smart and Archive. For detailed information about standard blob account block blob level tiering, see Blob storage tiers.
x-ms-smart-access-tier This header is only returned for requests made against blobs in Smart tier. Valid values are Hot, Cool, and Cold. For detailed information about standard blob account block blob level tiering see Blob storage tiers.
x-ms-archive-status For blob storage or general purpose v2 accounts, the valid values are rehydrate-pending-to-hot, rehydrate-pending-to-cool, and rehydrate-pending-to-cold. If the blob is being rehydrated and is incomplete, this header is returned, which both indicates that the rehydrate is pending and displays the destination tier. For detailed information about standard blob account block blob-level tiering, see Blob storage tiers.
x-ms-access-tier-change-time Indicates the last time the tier was changed on the object. This header is returned only if a tier on block blob was ever set. The date format follows RFC 1123. For more information, see Represent date/time values in headers. For more information about standard blob account block blob-level tiering, see Blob storage tiers.
x-ms-rehydrate-priority If an object is in rehydrate pending state then this header is returned with priority of rehydrate. Valid values are High/Standard. For detailed information about standard blob account block blob level tiering see Blob storage tiers.
x-ms-or-{policy-id}_{rule-id} Returned only for block blobs. policy-id is a GUID value that represents the identifier of an object replication policy on the storage account. rule-id is a GUID value that represents the identifier of a policy rule on the blob container. If the account is ObjectReplication-enabled, the value of this header represents the replication status of blob with the given policy and rule identifiers, either complete or failed.
x-ms-or-policy-id Returned only for block blobs. If the account is ObjectReplication-enabled, the value of this header represents the policy that governs the replication.
x-ms-last-access-time Indicates the last time the blob's data was accessed based on the storage account's last access time tracking policy. The header isn't returned if the storage account doesn't have a last access time tracking policy, or the policy is disabled. For information about setting the storage account's last access time tracking policy, see Blob Storage API.
x-ms-blob-sealed Returned only for append blobs. If the append blob has been sealed, the value would be true. For more information, see Append Blob Seal
x-ms-immutability-policy-until-date Specifies the 'retention until' date set on the blob. This is the date until which the blob can be protected from being modified or deleted. Returned only if an immutability policy is set on the blob. The value of this header is RFC1123 format.
x-ms-immutability-policy-mode: unlocked/locked The immutability policy mode, returned if an immutability policy is set on the blob. Values are unlocked/locked. unlocked indicates the user may change the policy by increasing or decreasing the retention-until date. locked indicates that these actions are prohibited.
x-ms-legal-hold: true/false This header isn't returned if there's no legal hold on the blob. The value of this header is set to true if the blob contains a legal hold and its value is true. Otherwise, the value is set to false if the blob contains a legal hold and its value false.
x-ms-owner Only for accounts with hierarchical namespace enabled. Returns the owner user of the file or directory.
x-ms-group Only for accounts with hierarchical namespace enabled. Returns the owner group of the file or directory.
x-ms-permissions Only for accounts with hierarchical namespace enabled. Returns the permissions that are set for user, group, and other on the file or directory. Each individual permission is in [r,w,x,-]{3} format.
x-ms-acl Only for accounts with hierarchical namespace enabled. Returns the combined list of access and default access control list that are set for user, group and other on the file or directory. Each access control entry (ACE) consists of a scope, a type, a user or group identifier, and permissions in the format [scope]:[type]:[id]:[permissions]. The default scope indicates that the ACE belongs to the default ACL for a directory; otherwise scope is implicit and the ACE belongs to the access ACL. Each individual permission is in [r,w,x,-]{3} format.
x-ms-resource-type Only for accounts with a hierarchical namespace enabled. Returns the resource type for the path, which can be either file or directory.
x-ms-expiry-time Only for accounts with a hierarchical namespace enabled. Returns the expiration time that's set on the blob. Is returned only for files that have an expiration time set.

Response body

When the response status code is HTTP 200 (OK), the response body contains the blob layout in XML format. The format of the response is as follows:

<?xml version="1.0" encoding="utf-8"?>
<BlobLayout>
    <Ranges>
        <Range Start="0" End="1023" EndpointIndex="0" />
        <Range Start="1024" End="4096" EndpointIndex="1" />
    </Ranges>
    <Endpoints>
        <Endpoint Index="0" Value="host1:port" />
        <Endpoint Index="1" Value="host2:port" />
    </Endpoints>
    <NextMarker>marker</NextMarker>
    <MaxResults>2</MaxResults>
</BlobLayout>

The XML response contains the following elements:

  • Ranges: Contains a list of Range elements, each specifying a contiguous range of bytes in the blob with an associated endpoint index.

    • Range: Represents a contiguous range of bytes in the blob.
      • Start: The starting byte offset of the range (inclusive).
      • End: The ending byte offset of the range (inclusive).
      • EndpointIndex: The index of the endpoint in the Endpoints list from which this range should be read.

  • Endpoints: Contains a list of Endpoint elements, each specifying a service endpoint.

    • Endpoint: Represents a service endpoint from which blob ranges can be read.
      • Index: The index of this endpoint, referenced by Range elements.
      • Value: The DNS hostname and port in the format hostname:port. This is the service endpoint that you should be subsequently reading from.

  • NextMarker: A continuation token to use in a subsequent Get Blob Layout request to retrieve the next set of ranges. This element is present only if there are additional ranges to retrieve.

  • MaxResults: The maximum number of ranges requested in the API call.

Authorization

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

Important

Microsoft recommends using Microsoft Entra ID with managed identities to authorize requests to Azure Storage. Microsoft Entra ID provides superior security and ease of use compared to Shared Key authorization.

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.

Permissions

Listed below are the RBAC action necessary for a Microsoft Entra user, group, managed identity, or service principal to call the Get Blob Layout 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.

Remarks

  • This API is only valid for append and block blobs.

  • The API may succeed with either HTTP 200 (OK) or HTTP 204 (No Content). If HTTP 204 is returned, no layout information is available for the blob, and the API is functionally equivalent to Get Blob Properties. If no layout information is available, clients should use standard Get Blob calls to download the blob.

  • If a layout is returned, you can use the host and port provided in each Range to download the contents of the blob covered by that Range. It is strongly recommended to condition those downloads on the ETag returned from the Get Blob Layout call to ensure strong consistency for reads.

  • The response headers x-ms-blob-content-* refer to the blob itself and not the layout sub-resource. The Content-Type of the response is always application/xml if a response body was returned.

  • The API accepts a Range or x-ms-range header. If the range header is omitted, the request is for the entire blob. The API will never return ranges that extend beyond the Range header.

  • The API is paginated. The API may not return enough ranges to cover the entire blob, or, for range requests, enough ranges to cover the entire requested range. If this happens, the API will return a NextMarker that you should use to request additional ranges. If a marker is used, you MUST also pass an If-Match condition that matches the ETag from the request that generated the marker. In addition, if the request that generated the marker included a Range or x-ms-range header, the subsequent request MUST include an identical header. If the request that generated the marker did not include a range header, the subsequent request MUST also not include a range header.

  • You MUST NOT assume that the list of endpoints in the response matches the list of endpoints from any prior Get Blob Layout requests to this blob. This is true even if the request is using a marker – the endpoint list may not match the endpoint list from the request that generated the marker.

  • The Endpoint returned for each range is a DNS hostname and Port, returned in the form hostname:port. This is the service endpoint that should be read for this range. You MUST use both the hostname and port specified when constructing your HTTP request. The hostname may not include the account name, so you MUST explicitly add the appropriate Host header in subsequent Get Blob API calls against this endpoint.

  • The layout of a blob can change over time, even if the blob is not modified. The layout of any given blob should be refreshed after five minutes, or whenever the blob is modified.

See also

Authorize requests to Azure Storage
Status and error codes
Blob Storage error codes
Set timeouts for Blob Storage operations Blob Service Concepts Specify conditional headers for Blob Storage operations

  • Last updated on