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.

Getting started

Applications & integrations

Identity & access

Using the API

Troubleshooting

Content

Collaboration

Metadata & search

Events & webhooks

Users

Intelligent workflow

E-signatures

Security & compliance

Parameters

Examples

Response

Response fields

Error codes

​Parameters

​Examples

​Response

​Response fields

​Error codes

Parameters

Examples

Response

Response fields

Error codes