Sample - Box Platform API
GET/folders/{folder_id}

Get folder information

Retrieves details for a folder, including the first 100 entries in the folder.

Passing sort, direction, offset, and limit parameters in query allows you to manage the list of returned folder items.

To fetch more items within the folder, use the Get items in a folder endpoint.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

8 parameters
folder_idstringrequired
The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`.
fieldsarray<string>optional
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 `?fields=metadata.enterprise_12345.contractTemplate`.
sortstringoptional
Defines the **second** attribute by which items are sorted. The folder type affects the way the items are sorted: * **Standard folder**: Items are always sorted by their `type` first, with folders listed before files, and files listed before web links. * **Root folder**: This parameter is not supported for marker-based pagination on the root folder (the folder with an `id` of `0`). * **Shared folder with parent path to the associated folder visible to the collaborator**: Items are always sorted by their `type` first, with folders listed before files, and files listed before web links.
Allowed:idnamedatesize
directionstringoptional
The direction to sort results in. This can be either in alphabetical ascending (`ASC`) or descending (`DESC`) order.
Allowed:ASCDESC
offsetintegeroptional
The offset of the item at which to begin the response. Offset-based pagination is not guaranteed to work reliably for high offset values and may fail for large datasets. In those cases, reduce the number of items in the folder (for example, by restructuring the folder into smaller subfolders) before retrying the request.
Default:0
limitintegeroptional
The maximum number of items to return per page.
if-none-matchstringoptional
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.
boxapistringoptional
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.

6 status codes
200Returns a folder, including the first 100 entries in the folder. If you used query parameters like `sort`, `direction`, `offset`, or `limit` the *folder items list* will be affected accordingly. To fetch more items within the folder, use the [Get items in a folder](https://developer.box.com/reference/get-folders-id-items)) endpoint. Not all available fields are returned by default. Use the [fields](#parameter-fields) query parameter to explicitly request any specific fields.
idstringrequired
The unique identifier that represent a folder. The ID for any folder can be determined by visiting a folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folders/123` the `folder_id` is `123`.
etagstringoptional
The HTTP `etag` of this folder. This can be used within some API endpoints in the `If-Match` and `If-None-Match` headers to only perform changes on the folder if (no) changes have happened.
typestringrequired
The value will always be `folder`.
Allowed:folder
sequence_idobjectoptional
namestringoptional
The name of the folder.
created_atstringoptional
The date and time when the folder was created. This value may be `null` for some folders such as the root folder or the trash folder.
modified_atstringoptional
The date and time when the folder was last updated. This value may be `null` for some folders such as the root folder or the trash folder.
descriptionobjectoptional
sizeintegeroptional
The folder size in bytes. Be careful parsing this integer as its value can get very large.
path_collectionobjectoptional
created_byobjectoptional
modified_byobjectoptional
trashed_atstringoptional
The time at which this folder was put in the trash.
purged_atstringoptional
The time at which this folder is expected to be purged from the trash.
content_created_atstringoptional
The date and time at which this folder was originally created.
content_modified_atstringoptional
The date and time at which this folder was last updated.
owned_byobjectoptional
shared_linkobjectoptional
folder_upload_emailobjectoptional
The `folder_upload_email` parameter is not `null` if one of the following options is **true**: * The **Allow uploads to this folder via email** and the **Only allow email uploads from collaborators in this folder** are [enabled for a folder in the Admin Console](https://support.box.com/hc/en-us/articles/360043697534-Upload-to-Box-Through-Email), and the user has at least **Upload** permissions granted. * The **Allow uploads to this folder via email** setting is enabled for a folder in the Admin Console, and the **Only allow email uploads from collaborators in this folder** setting is deactivated (unchecked). If the conditions are not met, the parameter will have the following value: `folder_upload_email: null`.
parentobjectoptional
item_statusstringoptional
Defines if this item has been deleted or not. * `active` when the item has is not in the trash * `trashed` when the item has been moved to the trash but not deleted * `deleted` when the item has been permanently deleted.
Allowed:activetrasheddeleted
item_collectionobjectoptional
sync_stateobjectoptional
has_collaborationsbooleanoptional
Specifies if this folder has any other collaborators.
permissionsobjectoptional
tagsobjectoptional
can_non_owners_inviteobjectoptional
is_externally_ownedbooleanoptional
Specifies if this folder is owned by a user outside of the authenticated enterprise.
metadataobjectoptional
is_collaboration_restricted_to_enterpriseobjectoptional
allowed_shared_link_access_levelsarray<SharedLinkAccessLevel>optional
The shared link access levels the authenticated user is allowed to use when creating or updating a shared link for this folder. The list depends on item policy and user authorization. For some folders, like the root folder, this is always empty as sharing is not allowed at that level.
allowed_invitee_rolesarray<string>optional
A list of the types of roles that user can be invited at when sharing this folder.
watermark_infoobjectoptional
is_accessible_via_shared_linkbooleanoptional
Specifies if the folder can be accessed with the direct shared link or a shared link to a parent folder.
can_non_owners_view_collaboratorsbooleanoptional
Specifies if collaborators who are not owners of this folder are restricted from viewing other collaborations on this folder. It also restricts non-owners from inviting new collaborators.
classificationobjectoptional
is_associated_with_app_itembooleanoptional
This field will return true if the folder or any ancestor of the folder is associated with at least one app item. Note that this will return true even if the context user does not have access to the app item(s) associated with the folder.
collectionsarray<Collection>optional
The collections that this folder belongs to. For more information, see the [collections guide](https://developer.box.com/guides/collections).
304Returns 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.
403Returned when the access token provided in the `Authorization` header is not recognized or not provided.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
404Returned if the folder is not found, or the user does not have access to the folder.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
405Returned if the `folder_id` is not in a recognized format.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
defaultAn unexpected client error.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.

Error handling

A 403 is returned: Returned when the access token provided in the Authorization header is not recognized or not provided. A 404 is returned: Returned if the folder is not found, or the user does not have access to the folder. A 405 is returned: Returned if the folder_id is not in a recognized format. Any other status is an error: An unexpected client error.