cURL

curl -i -X POST "https://api.box.com/2.0/query" \
     -H "box-version: 2026.0" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "query": {
         "predicate": "enterprise_12345678:book:purchasePrice >= :price AND box:item:name = :name",
         "params": {
           "price": 100,
           "name": "The Hobbit"
         },
         "ancestors": [
           {
             "id": "789",
             "type": "folder"
           }
         ]
       },
       "order_by": [
         {
           "field_key": "enterprise_12345678:book:purchasePrice",
           "direction": "asc"
         }
       ],
       "limit": 1,
       "fields": [
         "box:item:name",
         "enterprise_12345678:book"
       ]
     }'

client.query.create_query_v2026_r0(
    CreateQueryV2026R0Query(
        predicate=predicate,
        params={"name": "John", "age": 50},
        ancestors=[QueryAncestorReferenceV2026R0(id="0", type="folder")],
    ),
    limit=10,
    fields=["box:item:name", search_from],
)

await client.query.createQueryV2026R0({
  query: {
    predicate: predicate,
    params: { ['name']: 'John', ['age']: 50 },
    ancestors: [
      { id: '0', type: 'folder' } satisfies QueryAncestorReferenceV2026R0,
    ],
  } satisfies QueryRequestBodyV2026R0QueryField,
  limit: 10,
  fields: ['box:item:name', searchFrom],
} satisfies QueryRequestBodyV2026R0);

try await client.query.createQueryV2026R0(requestBody: QueryRequestBodyV2026R0(query: QueryRequestBodyV2026R0QueryField(predicate: predicate, params: ["name": "John", "age": 50], ancestors: [QueryAncestorReferenceV2026R0(id: "0", type: "folder")]), limit: 10, fields: ["box:item:name", searchFrom]))

client.getQuery().createQueryV2026R0(new QueryRequestBodyV2026R0.Builder(new QueryRequestBodyV2026R0QueryField.Builder(predicate).params(mapOf(entryOf("name", "John"), entryOf("age", 50))).ancestors(Arrays.asList(new QueryAncestorReferenceV2026R0("0", "folder"))).build()).limit(10).fields(Arrays.asList("box:item:name", searchFrom)).build())

await client.Query.CreateQueryV2026R0Async(requestBody: new QueryRequestBodyV2026R0(query: new QueryRequestBodyV2026R0QueryField(predicate: predicate) { Parameters = new Dictionary<string, object>() { { "name", "John" }, { "age", 50 } }, Ancestors = Array.AsReadOnly(new [] {new QueryAncestorReferenceV2026R0(id: "0", type: "folder")}) }) { Limit = 10, Fields = Array.AsReadOnly(new [] {"box:item:name",searchFrom}) });

{
  "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"
}

Query

Box Query

Runs a query to discover Box items using a logical predicate, similar to a SQL WHERE clause. The predicate can filter across multiple metadata templates and item fields in a single request. Results can be sorted, paginated with markers, and shaped with fields so each entry includes additional item or metadata attributes.

This is the item-retrieval endpoint in the Query API (version 2026.0). Unlike the Metadata Query API, it is not limited to a single metadata template or to files and folders. For totals and grouped metrics over the same predicates, use Query Insights instead of paging through every matching item.

For predicate syntax, parameters, examples, pagination behavior, and error codes, see the Box Query guide. For shared response schemas, including Query results and result entries, see Query resources.

POST

query

cURL

curl -i -X POST "https://api.box.com/2.0/query" \
     -H "box-version: 2026.0" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "query": {
         "predicate": "enterprise_12345678:book:purchasePrice >= :price AND box:item:name = :name",
         "params": {
           "price": 100,
           "name": "The Hobbit"
         },
         "ancestors": [
           {
             "id": "789",
             "type": "folder"
           }
         ]
       },
       "order_by": [
         {
           "field_key": "enterprise_12345678:book:purchasePrice",
           "direction": "asc"
         }
       ],
       "limit": 1,
       "fields": [
         "box:item:name",
         "enterprise_12345678:book"
       ]
     }'

client.query.create_query_v2026_r0(
    CreateQueryV2026R0Query(
        predicate=predicate,
        params={"name": "John", "age": 50},
        ancestors=[QueryAncestorReferenceV2026R0(id="0", type="folder")],
    ),
    limit=10,
    fields=["box:item:name", search_from],
)

await client.query.createQueryV2026R0({
  query: {
    predicate: predicate,
    params: { ['name']: 'John', ['age']: 50 },
    ancestors: [
      { id: '0', type: 'folder' } satisfies QueryAncestorReferenceV2026R0,
    ],
  } satisfies QueryRequestBodyV2026R0QueryField,
  limit: 10,
  fields: ['box:item:name', searchFrom],
} satisfies QueryRequestBodyV2026R0);

try await client.query.createQueryV2026R0(requestBody: QueryRequestBodyV2026R0(query: QueryRequestBodyV2026R0QueryField(predicate: predicate, params: ["name": "John", "age": 50], ancestors: [QueryAncestorReferenceV2026R0(id: "0", type: "folder")]), limit: 10, fields: ["box:item:name", searchFrom]))

client.getQuery().createQueryV2026R0(new QueryRequestBodyV2026R0.Builder(new QueryRequestBodyV2026R0QueryField.Builder(predicate).params(mapOf(entryOf("name", "John"), entryOf("age", 50))).ancestors(Arrays.asList(new QueryAncestorReferenceV2026R0("0", "folder"))).build()).limit(10).fields(Arrays.asList("box:item:name", searchFrom)).build())

await client.Query.CreateQueryV2026R0Async(requestBody: new QueryRequestBodyV2026R0(query: new QueryRequestBodyV2026R0QueryField(predicate: predicate) { Parameters = new Dictionary<string, object>() { { "name", "John" }, { "age", 50 } }, Ancestors = Array.AsReadOnly(new [] {new QueryAncestorReferenceV2026R0(id: "0", type: "folder")}) }) { Limit = 10, Fields = Array.AsReadOnly(new [] {"box:item:name",searchFrom}) });

{
  "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 October 12, 2026

API reference

v2025.0

v2026.0

Box Query

Authorizations

Headers

Body

Response