Get file information


Retrieves the details about a file.



Path Parameters

stringin pathrequired

The unique identifier that represent a file.

The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL https://* the file_id is 123.

Query Parameters

string arrayin queryoptional

A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response.

Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.

Additionally this field can be used to query any metadata applied to the file by specifying the metadata field as well as the scope and key of the template to retrieve, for example ?field=metadata.enterprise_12345.contractTemplate.

Request Headers

stringin header

The URL, and optional password, for the shared link of this item.

This header can be used to access items that have not been explicitly shared with a user.

Use the format shared_link=[link] or if a password is required then use shared_link=[link]&shared_link_password=[password].

This header can be used on the file or folder shared, as well as on any files or folders nested within the item.

stringin header

Ensures an item is only returned if it has changed.

Pass in the item's last observed etag value into this header and the endpoint will fail with a 304 Not Modified if the item has not changed since.

stringin header

A header required to request specific representations of a file. Use this in combination with the fields query parameter to request a specific file representation.

The general format for these representations is X-Rep-Hints: [...] where [...] is one or many hints in the format [fileType?query].

For example, to request a png representation in 32x32 as well as 94x94 pixel dimensions provide the following hints.

X-Rep-Hints: [jpg?dimensions=32x32][jpg?dimensions=94x94]

Additionally, a text representation is available for all document file types in Box using the [extracted_text] representation.

X-Rep-Hints: [extracted_text]


application/jsonFile (Standard)

Returns a file object.

Not all available fields are returned by default. Use the fields query parameter to explicitly request any specific fields.


Returns an empty response when the If-None-Match header matches the current etag value of the folder. This indicates that the folder has not changed since it was last requested.

application/jsonClient error

Returned when the access token provided in the Authorization header is not recognized or not provided.

application/jsonClient error

Returned if the file is not found, or the user does not have access to the file.

application/jsonClient error

Returned if the file_id is not in a recognized format.

application/jsonClient error

Returns an error if an action is performed on a file with an incorrect media type.

  • unsupported_media_type when requesting an expiring_embed_link for a file that is not supported by Box Embed.
application/jsonClient error

An unexpected client error.

Get file information
You can now try out some of our APIs live, right here in the documentation.
Log in

Request Example

curl -i -X GET "" \
     -H "Authorization: Bearer <ACCESS_TOKEN>"
BoxFile file = new BoxFile(api, "id");
BoxFile.Info info = file.getInfo();
file_id = '11111'
file_info = client.file(file_id).get()
print('File "{0}" has a size of {1} bytes'.format(, file_info.size))
client.files.get(fileId: "11111", fields: ["name", "created_at"]) { (result: Result<File, BoxSDKError>) in
    guard case let .success(file) = result else {
        print("Error retrieving file information")

    print("File \( was created at \(file.createdAt)")

Response Example

  "type": "error",
  "code": "item_name_invalid",
  "help_url": "",
  "message": "Method Not Allowed",
  "request_id": "abcdef123456",
  "status": 400