Box query

The Box Query API lets you search for and find objects in Box. You can filter and sort results using metadata templates and item fields, so you can build detailed queries.

It goes beyond basic file and folder search and supports more types of Box items.

To create a query, call the POST https://api.box.com/2.0/query endpoint with query details.

Parameters

To make a call, you must pass the following parameters. Mandatory parameters are in bold.

Parameter	Type	Description	Example
query.predicate	string	A filter for your query, in SQL-like syntax. Use :parameter placeholders for values. See supported operators for metadata template fields and .	"amount >= :value"
query.params	object	Values for each :placeholder in the predicate. Each key matches the placeholder name without :. Value types must match the predicate fields.	{ "value": 100 }
query.ancestors	array	Limits results to items inside specific ancestors and their sub-items. Each object needs an id and type (such as folder). You need read access to every ancestor listed.	[{ "id": "123", "type": "folder" }]
query.order_by	array	How to sort results. Each object needs field_key and direction (asc or desc). Add multiple objects to sort by more than one field.	[{ "field_key": "box:item:created_at", "direction": "desc" }]
limit	integer	Maximum number of results to return. Default is 50. Must be between 0 and 100.	50
fields	array	Extra fields to include in each result. By default, results include only item type and ID. Each value can be an item field key or a metadata template or field key.	["box:item:created_at", "enterprise_123:templateKey:someField"]
marker	string	Token from a previous response to get the next page of results. Use only when continuing a previous request, and keep all other parameters the same.	"AAAAAmVYB1FWec8GH6..."

Examples

Query on two custom Metadata templates:

{
"query": {
	"predicate": "enterprise_12345678:contract:status = :contractStatus AND
enterprise_12345678:project:inceptionDate >= :date",
	"params": {
		"contractStatus": "Signed",
		"date": "2020-01-01T00:00:00Z"
	},
},
"order_by": [
{
	"field_key": "enterprise_12345678:project:projectId",
	"direction": "asc"
	},
	],
	"limit": 10,
	"include_total_count": true,
	"fields": [
		"box:item:name",
		"enterprise_12345678:project"
	]
}

Query on one custom metadata template and item information:

{
"query": {
	"predicate": "enterprise_12345678:inventory:book:purchasePrice >= :p1 AND
box:item:name = :name",
	"params": {
		"p1": 100,
		"name": "The Hobbit"
	},
	"ancestors": [
		"folder_789"
	],
},
"order_by": [
	{
		"field_key": "enterprise_12345678:inventory:book:purchasePrice",
		"direction": "asc"
	},
],
"limit": 1,
"include_total_count": true,
"fields": [
	"box:item:name",
	"enterprise_12345678:book"
	]
}

Response

{
	"entries": [
		{
			"id": "12345",
			"type": "file",
			"box": {
				"item": {
					"name": "My Form"
				},
			},
		"enterprise_12345678": {
			"book": {
				"$id": "82ba3e97-496c-475d-85f2-078c690c434c",
				"$parent": "file_12345",
				"$scope": "enterprise_12345678",
				"$template": "book",
				"$type": "book-b52189dd-caa3-44e9-ba36-d31079bb10e6",
				"isbn": "1871263670",
				"purchasePrice": 234.57,
				"publicationYear": "1937"
			}
		}
	}
	],
	"next_marker": "xppy0jjG1kBRSc7NBBSgQmBz1Gk6VaQdg5Vyb+Ob0iA=A="
}

Response fields

Field	Type	Description
entries	array	The list of items that match the query. Each object contains a type and ID for a single item matching the predicate. If a fields parameter is specified in the request, then additional item and/or metadata fields are provided.
next_marker	string or null	A token that can be used to get the next page of results. If there are no more results, this value is null. Otherwise, the value can be provided as the marker parameter to a follow up request to retrieve additional entries.

Pagination uses markers, not snapshots. If you combine all pages, you may not get a complete list of matching items at one moment in time. New matches may appear after you start, and items from earlier pages can be missing from later pages if they are changed or deleted while you are fetching the results.

Error codes

Error Code	Error Type	Error Message
400	UNEXPECTED_JSON_TYPE	Expected JSON with type string.
400	INVALID_QUERY	Failed to parse query: Unexpected end of input.
400	INVALID_QUERY	Scope is invalid.
401	UNAUTHORIZED	The provided access token is invalid.
403	FORBIDDEN	Query API found either too many items or too many inaccessible items matching the query.
404	INSTANCE_NOT_FOUND	The templates you referenced were not found.
404	ITEM_NOT_FOUND	Item not found.
500	INTERNAL_SERVER_ERROR	Internal server error.