Query for Box items

{
  "entries": [
    {
      "id": "12345",
      "type": "file",
      "box": {
        "item": {
          "name": "My Form"
        }
      },
      "enterprise_12345678": {
        "book": {
          "$parent": "file_12345",
          "$scope": "enterprise_12345678",
          "$template": "book",
          "$version": 4,
          "isbn": "1871263670",
          "purchasePrice": 234.57,
          "publicationYear": "1937"
        }
      }
    }
  ],
  "next_marker": "xppy0jjG1kBRSc7NBBSgQmBz1Gk6VaQdg5Vyb+Ob0iA=",
  "limit": 1
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

POST

query

{
  "entries": [
    {
      "id": "12345",
      "type": "file",
      "box": {
        "item": {
          "name": "My Form"
        }
      },
      "enterprise_12345678": {
        "book": {
          "$parent": "file_12345",
          "$scope": "enterprise_12345678",
          "$template": "book",
          "$version": 4,
          "isbn": "1871263670",
          "purchasePrice": 234.57,
          "publicationYear": "1937"
        }
      }
    }
  ],
  "next_marker": "xppy0jjG1kBRSc7NBBSgQmBz1Gk6VaQdg5Vyb+Ob0iA=",
  "limit": 1
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

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

box-version

enum<string>

required

Version header.

Available options:

2026.0

Body

application/json

Request body describing the query to run, including the filtering predicate, optional sorting, pagination, and the fields to return for each result.

query

object

required

The query definition, including the filtering predicate and its optional parameters and ancestor restrictions.

Show child attributes

order_by

Query order by · object[]

The sorting criteria for the result set. Entries are applied sequentially to define multi-level sorting.

Show child attributes

limit

integer<int32>

default:50

The maximum number of results to return. Defaults to 50 when not provided.

Required range: 0 <= x <= 100

Example:

1

fields

string[]

Controls which additional fields are included in each result entry. Each value must be one of: a fully qualified item field key (for example box:item:name), a metadata template key to hydrate the full template (for example enterprise_12345678:project), or a specific metadata template field key to hydrate a single field from the template (for example enterprise_12345678:project:name). When omitted, entries include only the item type and identifier.

Example:

["box:item:name", "enterprise_12345678:book"]

marker

string

An opaque token returned from a previous response, used to continue retrieval. When provided, all other request parameters must exactly match those of the original request.

Example:

"xppy0jjG1kBRSc7NBBSgQmBz1Gk6VaQdg5Vyb+Ob0iA="

Response

Returns a paginated list of items matching the query.

A paginated list of items matching the query, using milestone-based marker pagination.

entries

Query result entry · object[]

required

The list of items matching the query predicate.

Show child attributes

next_marker

string | null

required

The marker for the start of the next page of results. When null, there are no further results available.

Example:

"xppy0jjG1kBRSc7NBBSgQmBz1Gk6VaQdg5Vyb+Ob0iA="

limit

integer<int32>

required

The limit that was used for this request. This will be the same as the limit query parameter unless that value exceeded the maximum value allowed.

Example:

50

Last modified on July 24, 2026

Create insights for Box items

⌘I

v2025.0

v2026.0

Authorizations

Headers

Body

Response