> ## Documentation Index
> Fetch the complete documentation index at: https://developer.box.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Box query
export const Link = ({href, children, className, ...props}) => {
const localizedHref = localizeLink(href);
return
{children}
;
};
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](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](https://cloud.box.com/s/bkcwr35hypy4so1gvdza5x2vv16) and item properties. | `"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:
```json theme={null}
{
"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:
```json theme={null}
{
"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
```json theme={null}
{
"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. |