Get File Properties

The Get File Properties operation returns all user-defined metadata, standard HTTP properties, and system properties for the file. It doesn't return the content of the file. This operation is supported in version 2025-05-05 and later for File Shares with NFS protocol enabled.

Protocol availability

Enabled file share protocol	Available
SMB
NFS

Request

The Get File Properties request is constructed as follows. We recommend that you use HTTPS.

Method	Request URI	HTTP version
HEAD	https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile	HTTP/1.1
HEAD	https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?sharesnapshot=<DateTime>	HTTP/1.1

Replace the path components that are shown in the request URI with your own, as follows:

Path component	Description
myaccount	The name of your storage account.
myshare	The name of your file share.
mydirectorypath	Optional. The path to the parent directory.
myfile	The name of the file.

For information about path naming restrictions, see Name and reference shares, directories, files, and metadata.

URI parameters

The following additional parameters can be specified on the request URI:

Parameter	Description
sharesnapshot	Optional. Version 2017-04-17 and later. The sharesnapshot parameter is an opaque DateTime value that, when present, specifies the share snapshot to query for the file properties.
timeout	Optional. The timeout parameter is expressed in seconds. For more information, see Set time-outs for Azure Files operations.

Request headers

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

Common 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 for all authorized requests. Specifies the version of the operation to use for this request. This operation is supported in version 2025-05-05 and later for File Shares with NFS protocol enabled. For more information, see Versioning for the Azure Storage services.
x-ms-lease-id:<ID>	Optional. Version 2019-02-02 and later. If the header is specified, the operation is performed only if the file's lease is currently active and the lease ID specified in the request matches the lease ID of the file. If it doesn't match, the operation fails with status code 412 (Precondition Failed). This header is ignored if the file is located on a File Share with NFS protocol enabled, which doesn't support file leases.
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 Azure 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 Monitor Azure Blob Storage.
x-ms-file-request-intent	Required if Authorization header specifies an OAuth token. Acceptable value is backup. This header specifies that the Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action or Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action should be granted if they're included in the RBAC policy assigned to the identity that is authorized using the Authorization header. Available for version 2022-11-02 and later.
x-ms-allow-trailing-dot: { <Boolean> }	Optional. Version 2022-11-02 and later. The Boolean value specifies if a trailing dot present in request url should be trimmed or not. This header is ignored if the target is located on a File Share with NFS protocol enabled, which supports trailing dot by default. For more information, see Naming and referencing shares, directories, files, and metadata.

SMB only request headers

None.

NFS only request headers

None.

Request body

None.

Response

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

Status code

A successful operation returns status code 200 (OK). For information about status codes, see Status and error codes.

Response headers

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

Common response headers

Response header	Description
Last-Modified	Returns the date and time when the file was last modified. The date format follows RFC 1123. For more information, see Represent date/time values in headers. Any operation that modifies the file or its properties updates the last modified time.
x-ms-meta-name:value	A set of name-value pairs that are associated with this file as user-defined metadata.
x-ms-type: <File>	Returns the type File. Reserved for future use.
Content-Length	The size of the file in bytes. This header returns the value of the x-ms-content-length header that's stored with the file.
Content-Type	The content type that's specified for the file. If no content type is specified, the default content type is application/octet-stream.
ETag	The ETag contains a value that you can use to perform operations conditionally. The value is enclosed in quotation marks.
Content-MD5	If the Content-MD5 header has been set for the file, the Content-MD5 response header is returned so that the client can check for message content integrity.
Content-Encoding	If the Content-Encoding request header has previously been set for the file, the Content-Encoding value is returned in this header.
Content-Language	If the Content-Language request header has previously been set for the file, the Content-Language value is returned in this header.
Cache-Control	If the Cache-Control request header has previously been set for the file, the Cache-Control value is returned in this header.
Content-Disposition	Returns the value that was specified for the x-ms-content-disposition header and specifies how to process the response. The Content-Disposition response header field conveys additional information about how to process the response payload, and you can use it to attach additional metadata. For example, if it's set to attachment, Content-Disposition indicates that the user-agent shouldn't display the response, but it should display a Save As window instead.
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	Indicates the service 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-copy-completion-time:<datetime>	Version 2015-02-21 and later. The conclusion time of the last attempted Copy File operation where this file was the destination file. 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 file has never been the destination in a Copy File operation, or if this file has been modified after a concluded Copy File operation by using Set File Properties or Create File.
x-ms-copy-status-description: <error string>	Version 2015-02-21 and later. Appears only when x-ms-copy-status is failed or pending. It describes the cause of fatal or non-fatal copy operation failure. This header doesn't appear if a copy is pending, if this file has never been the destination in a Copy File operation, or if this file has been modified after a concluded Copy File operation by using Set File Properties or Create File.
x-ms-copy-id: <id>	Version 2015-02-21 and later. The string identifier for the last attempted Copy File operation where this file was the destination file. This header doesn't appear if this file has never been the destination in a Copy File operation, or if this file has been modified after a concluded Copy File operation by using Set File Properties or Create File.
x-ms-copy-progress: <bytes copied/bytes total>	Version 2015-02-21 and later. Contains the number of bytes copied and the total bytes in the source in the last attempted Copy File operation where this file was the destination file. Can show between 0 and the number of Content-Length bytes copied. This header doesn't appear if this file has never been the destination in a Copy File operation, or if this file has been modified after a concluded Copy File operation by using Set File Properties or Create File.
x-ms-copy-source: url	Version 2015-02-21 and later. A URL of up to 2 KB characters that specifies the source file that was used in the last attempted Copy File operation where this file was the destination file. This header doesn't appear if this file has never been the destination in a Copy File operation, or if this file has been modified after a concluded Copy File operation by using Set File Properties or Create File.
x-ms-copy-status: <pending ¦ success ¦ aborted ¦ failed>	Version 2015-02-21 and later. The state of the copy operation that's 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 File. - failed: Copy failed. See x-ms-copy-status-description for failure details. This header doesn't appear if this file has never been the destination in a Copy File operation, or if this file has been modified after a concluded Copy File operation by using Set File Properties or Create File.
x-ms-server-encrypted: true/false	Version 2017-04-17 and later. The value of this header is set to true if the file data and application metadata are completely encrypted by using the specified algorithm. The value is set to false if the file is unencrypted, or if only parts of the file or application metadata are encrypted.
x-ms-file-creation-time	Version 2019-02-02 and later. The UTC date/time value that represents the creation time property for a file.
x-ms-file-last-write-time	Version 2019-02-02 and later. The UTC date/time value that represents the last write time property for the file.
x-ms-file-change-time	Version 2019-02-02 and later. The UTC date/time value that represents the change time property for the file.
x-ms-file-file-id	Version 2019-02-02 and later. The file ID of the file.
x-ms-file-parent-id	Version 2019-02-02 and later. The parent file ID of the file.
x-ms-lease-duration:infinite	Version 2019-02-02 and later. When a file is leased, specifies that the lease is of infinite duration.
x-ms-lease-state:<available;leased;broken>	Version 2019-02-02 and later. When a file is leased, specifies the lease state of the file.
x-ms-lease-status:<locked;unlocked>	Version 2019-02-02 and later. When a file is leased, specifies the lease status of the file.
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 isn't present in the response.

SMB only response headers

Response header	Description
x-ms-file-permission-key	Version 2019-02-02 and later. The key of the permission of the file.
x-ms-file-attributes	Version 2019-02-02 and later. The file system attributes of the file. For more information, see the list of available attributes.

NFS only response headers

Response header	Description
x-ms-mode	Version 2025-05-05 and later. The mode of the file. See POSIX file permissions (mode).
x-ms-owner	Version 2025-05-05 and later. The user identifier (UID) of the file owner.
x-ms-group	Version 2025-05-05 and later. The group identifier (GID) of the file owner.
x-ms-link-count	Version 2025-05-05 and later. The link count of the file.
x-ms-file-file-type	Version 2025-05-05 and later. The type of the file, the possible values are: Regular, Symlink.

Response body

None.

Sample response

Response Status:  
HTTP/1.1 200 OK  
  
Response Headers:  
x-ms-type: File  
x-ms-meta-m1: v1  
x-ms-meta-m2: v2  
Content-Length: 11  
Content-Type: text/plain; charset=UTF-8  
Date: <date>  
ETag: "0x8CB171DBEAD6A6B"  
Last-Modified: <date>  
x-ms-version: 2019-02-02  
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0  
x-ms-copy-id: 36650d67-05c9-4a24-9a7d-a2213e53caf6  
x-ms-copy-source: <url>  
x-ms-copy-status: success  
x-ms-copy-progress: 11/11  
x-ms-copy-completion-time: <date>  
x-ms-lease-duration: infinite   
x-ms-lease-state: leased 
x-ms-lease-status: locked   

Authorization

Only the account owner can call this operation.

File system attributes

Attribute	Win32 file attribute	Definition
ReadOnly	FILE_ATTRIBUTE_READONLY	A file that's read-only. Applications can read the file, but can't write to it or delete it.
Hidden	FILE_ATTRIBUTE_HIDDEN	The file is hidden. It isn't included in an ordinary directory listing.
System	FILE_ATTRIBUTE_SYSTEM	A file that the operating system uses a part of, or uses exclusively.
None	FILE_ATTRIBUTE_NORMAL	A file that doesn't have other attributes set. This attribute is valid only when it's used alone.
Archive	FILE_ATTRIBUTE_ARCHIVE	A file that's an archive file. Applications ordinarily use this attribute to mark files for backup or removal.
Temporary	FILE_ATTRIBUTE_TEMPORARY	A file that's being used for temporary storage.
Offline	FILE_ATTRIBUTE_OFFLINE	The data of a file isn't available immediately. This file system attribute is presented primarily to provide compatibility with Windows. Azure Files doesn't support offline storage options.
NotContentIndexed	FILE_ATTRIBUTE_NOT_CONTENT_INDEXED	The file isn't to be indexed by the content indexing service.
NoScrubData	FILE_ATTRIBUTE_NO_SCRUB_DATA	The user data stream isn't to be read by the background data integrity scanner. This file system attribute is presented primarily to provide compatibility with Windows.

POSIX file permissions (mode)

POSIX file permissions can be specified either numerically in a 12-bit numeric octal format or in a symbolic "rwx" format. Examples:

• "0644" or "rw-r--r--": User (file owner) has read, write permission. Group has read permission. Others have read permission.
• "0755" or "rwxr-xr-x": User (file owner) has read, write, and execute permission. Group has read and execute permission. Others have read and execute permission.

Numeric octal format

The three lowest order octal numbers represent the permissions for owner/user, group, and others and are indicated using an octal number (0-7), formed using a bitwise combination of '4' (Read), '2' (Write), '1' (Execute). The highest order octal number (0-7) is used to indicate a combination of '4' (SetUID), '2' (SetGID), '1' (StickyBit) permissions.

Format	Permission
0700	User (file owner) has read, write, and execute permission.
0400	User has read permission.
0200	User has write permission.
0100	User has execute permission.
0070	Group has read, write, and execute permission.
0040	Group has read permission.
0020	Group has write permission.
0010	Group has execute permission.
0007	Others have read, write, and execute permission.
0004	Others have read permission.
0002	Others have write permission.
0001	Others have execute permission.
4000	Set effective user ID on file.
2000	Set effective group ID on file.
1000	Set to indicate that the file can be deleted or renamed only by file owner, directory owner, or root user.

Symbolic "rwx" format

Permissions for owner/user, group, and others are indicated using a combination of 'r' (Read), 'w' (Write), and 'x' (Execute) characters.

Format	Permission
rwx------	User (file owner) has read, write, and execute permission.
r--------	User has read permission.
-w-------	User has write permission.
--x------	User has execute permission.
---rwx---	Group has read, write, and execute permission.
---r-----	Group has read permission.
----w----	Group has write permission.
-----x---	Group has execute permission.
------rwx	Others have read, write, and execute permission.
------r--	Others have read permission.
-------w-	Others have write permission.
--------x	Others have execute permission.

See also

Operations on Files