Skip to main content
GET
/
folders
/
{folder_id}
cURL
curl -i -X GET "https://api.box.com/2.0/folders/4353455" \
     -H "authorization: Bearer <ACCESS_TOKEN>"
{
  "id": "12345",
  "type": "folder",
  "etag": "1",
  "sequence_id": "3",
  "name": "Contracts",
  "created_at": "2012-12-12T10:53:43-08:00",
  "modified_at": "2012-12-12T10:53:43-08:00",
  "description": "Legal contracts for the new ACME deal",
  "size": 629644,
  "path_collection": {
    "total_count": 1,
    "entries": [
      {
        "id": "12345",
        "type": "folder",
        "etag": "1",
        "sequence_id": "3",
        "name": "Contracts"
      }
    ]
  },
  "created_by": {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "[email protected]"
  },
  "modified_by": {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "[email protected]"
  },
  "trashed_at": "2012-12-12T10:53:43-08:00",
  "purged_at": "2012-12-12T10:53:43-08:00",
  "content_created_at": "2012-12-12T10:53:43-08:00",
  "content_modified_at": "2012-12-12T10:53:43-08:00",
  "owned_by": {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "[email protected]"
  },
  "shared_link": {
    "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
    "effective_access": "company",
    "effective_permission": "can_download",
    "is_password_enabled": true,
    "download_count": 3,
    "preview_count": 3,
    "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
    "vanity_url": "https://acme.app.box.com/v/my_url/",
    "vanity_name": "my_url",
    "access": "open",
    "unshared_at": "2018-04-13T13:53:23-07:00",
    "permissions": {
      "can_download": true,
      "can_preview": true,
      "can_edit": false
    }
  },
  "folder_upload_email": {
    "access": "open",
    "email": "[email protected]"
  },
  "parent": {
    "id": "12345",
    "type": "folder",
    "etag": "1",
    "sequence_id": "3",
    "name": "Contracts"
  },
  "item_status": "active",
  "item_collection": {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
    "total_count": 5000,
    "offset": 2000,
    "order": [
      {
        "by": "type",
        "direction": "ASC"
      }
    ],
    "entries": [
      {
        "id": "12345",
        "type": "file",
        "etag": "1",
        "sequence_id": "3",
        "name": "Contract.pdf",
        "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
        "file_version": {
          "id": "12345",
          "type": "file_version",
          "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
        },
        "description": "Contract for Q1 renewal",
        "size": 629644,
        "path_collection": {
          "total_count": 1,
          "entries": [
            "<unknown>"
          ]
        },
        "created_at": "2012-12-12T10:53:43-08:00",
        "modified_at": "2012-12-12T10:53:43-08:00",
        "trashed_at": "2012-12-12T10:53:43-08:00",
        "purged_at": "2012-12-12T10:53:43-08:00",
        "content_created_at": "2012-12-12T10:53:43-08:00",
        "content_modified_at": "2012-12-12T10:53:43-08:00",
        "created_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "[email protected]"
        },
        "modified_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "[email protected]"
        },
        "owned_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "[email protected]"
        },
        "shared_link": {
          "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
          "effective_access": "company",
          "effective_permission": "can_download",
          "is_password_enabled": true,
          "download_count": 3,
          "preview_count": 3,
          "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
          "vanity_url": "https://acme.app.box.com/v/my_url/",
          "vanity_name": "my_url",
          "access": "open",
          "unshared_at": "2018-04-13T13:53:23-07:00",
          "permissions": {
            "can_download": true,
            "can_preview": true,
            "can_edit": false
          }
        },
        "parent": "<unknown>",
        "item_status": "active",
        "version_number": "1",
        "comment_count": 10,
        "permissions": {
          "can_delete": true,
          "can_download": true,
          "can_invite_collaborator": true,
          "can_rename": true,
          "can_set_share_access": true,
          "can_share": true,
          "can_annotate": true,
          "can_comment": true,
          "can_preview": true,
          "can_upload": true,
          "can_view_annotations_all": true,
          "can_view_annotations_self": true
        },
        "tags": [
          "approved"
        ],
        "lock": {
          "id": "11446498",
          "type": "lock",
          "created_by": {
            "id": "11446498",
            "type": "user",
            "name": "Aaron Levie",
            "login": "[email protected]"
          },
          "created_at": "2012-12-12T10:53:43-08:00",
          "expired_at": "2012-12-12T10:53:43-08:00",
          "is_download_prevented": true,
          "app_type": "office_wopiplus"
        },
        "extension": "pdf",
        "is_package": true,
        "expiring_embed_link": {
          "access_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
          "expires_in": 3600,
          "token_type": "bearer",
          "restricted_to": [
            {
              "scope": "item_download",
              "object": {
                "id": "<unknown>",
                "type": "<unknown>",
                "etag": "<unknown>",
                "sequence_id": "<unknown>",
                "name": "<unknown>"
              }
            }
          ],
          "url": "https://cloud.app.box.com/preview/expiring_embed/..."
        },
        "watermark_info": {
          "is_watermarked": true
        },
        "is_accessible_via_shared_link": true,
        "allowed_invitee_roles": [
          "editor"
        ],
        "is_externally_owned": true,
        "has_collaborations": true,
        "metadata": {
          "enterprise_27335": {
            "marketingCollateral": {
              "$canEdit": true,
              "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
              "$parent": "folder_59449484661",
              "$scope": "enterprise_27335",
              "$template": "marketingCollateral",
              "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
              "$typeVersion": 2,
              "$version": 1
            }
          }
        },
        "expires_at": "2012-12-12T10:53:43-08:00",
        "representations": {
          "entries": [
            {
              "content": {
                "url_template": "https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048/content/{+asset_path}?watermark_content=4567"
              },
              "info": {
                "url": "https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048"
              },
              "properties": {
                "dimensions": "2048x2048",
                "paged": "true",
                "thumb": "true"
              },
              "representation": "png",
              "status": {
                "state": "success"
              }
            }
          ]
        },
        "classification": {
          "name": "Top Secret",
          "definition": "Content that should not be shared outside the company.",
          "color": "#FF0000"
        },
        "uploader_display_name": "Ellis Wiggins",
        "disposition_at": "2012-12-12T10:53:43-08:00",
        "shared_link_permission_options": [
          "can_preview"
        ],
        "is_associated_with_app_item": true
      }
    ]
  },
  "sync_state": "synced",
  "has_collaborations": true,
  "permissions": {
    "can_delete": true,
    "can_download": true,
    "can_invite_collaborator": true,
    "can_rename": true,
    "can_set_share_access": true,
    "can_share": true,
    "can_upload": true
  },
  "tags": [
    "approved"
  ],
  "can_non_owners_invite": true,
  "is_externally_owned": true,
  "metadata": {
    "enterprise_27335": {
      "marketingCollateral": {
        "$canEdit": true,
        "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
        "$parent": "folder_59449484661",
        "$scope": "enterprise_27335",
        "$template": "marketingCollateral",
        "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
        "$typeVersion": 2,
        "$version": 1
      }
    }
  },
  "is_collaboration_restricted_to_enterprise": true,
  "allowed_shared_link_access_levels": [
    "open"
  ],
  "allowed_invitee_roles": [
    "editor"
  ],
  "watermark_info": {
    "is_watermarked": true
  },
  "is_accessible_via_shared_link": true,
  "can_non_owners_view_collaborators": true,
  "classification": {
    "name": "Top Secret",
    "definition": "Content that should not be shared outside the company.",
    "color": "#FF0000"
  },
  "is_associated_with_app_item": true
}
This endpoint is in the version 2024.0. No changes are required to continue using it. For more details, see Box API versioning.Learn more about Box SDK versioning strategy.

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Headers

​
if-none-match
string

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.

​
boxapi
string

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.

Path Parameters

​
folder_id
string
required

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.

Query Parameters

​
fields
string[]

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.

​
sort
enum<string>

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.
Available options:
id,
name,
date,
size
​
direction
enum<string>

The direction to sort results in. This can be either in alphabetical ascending (ASC) or descending (DESC) order.

Available options:
ASC,
DESC
​
offset
integer<int64>
default:0

The offset of the item at which to begin the response.

Queries with offset parameter value exceeding 10000 will be rejected with a 400 response.

​
limit
integer<int64>

The maximum number of items to return per page.

Required range: x <= 1000

Response

Returns 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) endpoint.

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

A full representation of a folder, as can be returned from any folder API endpoints by default.

​
id
string
required

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.

Example:

"12345"

​
type
enum<string>
required

The value will always be folder.

Available options:
folder
Example:

"folder"

​
etag
string | null

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.

Example:

"1"

​
sequence_id
string | null

A numeric identifier that represents the most recent user event that has been applied to this item.

This can be used in combination with the GET /events-endpoint to filter out user events that would have occurred before this identifier was read.

An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the sequence_id in the event is smaller than or equal to the sequence_id in the originally fetched resource.

Example:

"3"

​
name
string

The name of the folder.

Example:

"Contracts"

​
created_at
string<date-time> | null

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.

Example:

"2012-12-12T10:53:43-08:00"

​
modified_at
string<date-time> | null

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.

Example:

"2012-12-12T10:53:43-08:00"

​
description
string

The optional description of this folder.

Maximum string length: 256
Example:

"Legal contracts for the new ACME deal"

​
size
integer<int64>

The folder size in bytes.

Be careful parsing this integer as its value can get very large.

Example:

629644

​
path_collection
Path collection · object

The tree of folders that this folder is contained in, starting at the root.

​
created_by
User (Mini) · object

The user who created this folder.

​
modified_by
User (Mini) · object

The user who last modified this folder.

​
trashed_at
string<date-time> | null

The time at which this folder was put in the trash.

Example:

"2012-12-12T10:53:43-08:00"

​
purged_at
string<date-time> | null

The time at which this folder is expected to be purged from the trash.

Example:

"2012-12-12T10:53:43-08:00"

​
content_created_at
string<date-time> | null

The date and time at which this folder was originally created.

Example:

"2012-12-12T10:53:43-08:00"

​
content_modified_at
string<date-time> | null

The date and time at which this folder was last updated.

Example:

"2012-12-12T10:53:43-08:00"

​
owned_by
User (Mini) · object

The user who owns this folder.

​
shared_link
Shared link · object

The shared link for this folder. This will be null if no shared link has been created for this folder.

​
folder_upload_email
object

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, 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.

​
parent
Folder (Mini) · object

The optional folder that this folder is located within.

This value may be null for some folders such as the root folder or the trash folder.

​
item_status
enum<string>

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.
Available options:
active,
trashed,
deleted
Example:

"active"

​
item_collection
Items · object

A page of the items that are in the folder.

This field can only be requested when querying a folder's information, not when querying a folder's items.

​
sync_state
enum<string>

Specifies whether a folder should be synced to a user's device or not. This is used by Box Sync (discontinued) and is not used by Box Drive.

Available options:
synced,
not_synced,
partially_synced
Example:

"synced"

​
has_collaborations
boolean

Specifies if this folder has any other collaborators.

Example:

true

​
permissions
object

Describes the permissions that the current user has for this folder.

​
tags
string[]

The tags for this item. These tags are shown in the Box web app and mobile apps next to an item.

To add or remove a tag, retrieve the item's current tags, modify them, and then update this field.

There is a limit of 100 tags per item, and 10,000 unique tags per enterprise.

Required array length: 1 - 100 elements
Example:
["approved"]
​
can_non_owners_invite
boolean

Specifies if users who are not the owner of the folder can invite new collaborators to the folder.

Example:

true

​
is_externally_owned
boolean

Specifies if this folder is owned by a user outside of the authenticated enterprise.

Example:

true

​
metadata
Item metadata instances · object

An object containing the metadata instances that have been attached to this folder.

Each metadata instance is uniquely identified by its scope and templateKey. There can only be one instance of any metadata template attached to each folder. Each metadata instance is nested within an object with the templateKey as the key, which again itself is nested in an object with the scope as the key.

Example:
{
  "enterprise_27335": {
    "marketingCollateral": {
      "$canEdit": true,
      "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
      "$parent": "folder_59449484661",
      "$scope": "enterprise_27335",
      "$template": "marketingCollateral",
      "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
      "$typeVersion": 2,
      "$version": 1
    }
  }
}
​
is_collaboration_restricted_to_enterprise
boolean

Specifies if new invites to this folder are restricted to users within the enterprise. This does not affect existing collaborations.

Example:

true

​
allowed_shared_link_access_levels
enum<string>[]

A list of access levels that are available for this folder.

For some folders, like the root folder, this will always be an empty list as sharing is not allowed at that level.

Available options:
open,
company,
collaborators
Example:
["open"]
​
allowed_invitee_roles
enum<string>[]

A list of the types of roles that user can be invited at when sharing this folder.

Available options:
editor,
viewer,
previewer,
uploader,
previewer uploader,
viewer uploader,
co-owner
Example:
["editor"]
​
watermark_info
object

Details about the watermark applied to this folder.

​
is_accessible_via_shared_link
boolean

Specifies if the folder can be accessed with the direct shared link or a shared link to a parent folder.

Example:

true

​
can_non_owners_view_collaborators
boolean

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.

Example:

true

​
classification
object

Details about the classification applied to this folder.

​
is_associated_with_app_item
boolean

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.

Example:

true