Create a query
Create a query
A metadata query is a POST request to the /metadata_queries/execute_read-
endpoint, in which the body contains all the parts of the metadata query. Most
important here are the from attribute that specifies the template to search
for, the ancestor_folder_id to specify the folder to search in, and the
query to determine any template fields to search by.
curl -X POST https://api.box.com/2.0/metadata_queries/execute_read \
-H 'Authorization: Bearer <ACCESS_TOKEN>" '
-H 'Content-Type: application/json'
-d '{
"from": "enterprise_123456.contractTemplate",
"query": "amount >= :value",
"query_params": {
"value": 100
},
"ancestor_folder_id": "5555",
"use_index": "amountAsc",
"order_by": [
{
"field_key": "amount",
"direction": "asc"
}
],
"limit": 100
}'
For more details about all the available parameters, check out any of our other metadata query guides, or the associated endpoint reference.
Learn more about the query syntaxResponse
Any files or folders that match the query are returned in the API response.
The body of the response is a JSON object with a list of entries for each file
or folder, and a next_marker value that you can use to find the next page of
results. Each of the entries will have an item representing the file or
folder, as well as a metadata instance containing the metadata attached to the
file or folder.
{
"entries":[
{
"item":{
"type":"file",
"id":"1617554169109",
"file_version":{
"type":"file_version",
"id":"1451884469385",
"sha1":"69888bb1bff455d1b2f8afea75ed1ff0b4879bf6"
},
"sequence_id":"0",
"etag":"0",
"sha1":"69888bb1bff455d1b2f8afea75ed1ff0b4879bf6",
"name":"My Contract.docx",
"description":"",
"size":25600,
"path_collection":{
"total_count":4,
"entries":[
{
"type":"folder",
"id":"0",
"sequence_id":null,
"etag":null,
"name":"All Files"
},
{
"type":"folder",
"id":"15017998644",
"sequence_id":"0",
"etag":"0",
"name":"Contracts"
},
{
"type":"folder",
"id":"15286891196",
"sequence_id":"1",
"etag":"1",
"name":"North America"
},
{
"type":"folder",
"id":"16125613433",
"sequence_id":"0",
"etag":"0",
"name":"2017"
}
]
},
"created_at":"2017-04-20T12:55:27-07:00",
"modified_at":"2017-04-20T12:55:27-07:00",
"trashed_at":null,
"purged_at":null,
"content_created_at":"2017-01-06T17:59:01-08:00",
"content_modified_at":"2017-01-06T17:59:01-08:00",
"created_by":{
"type":"user",
"id":"193973366",
"name":"Box Admin",
"login":"admin@company.com"
},
"modified_by":{
"type":"user",
"id":"193973366",
"name":"Box Admin",
"login":"admin@company.com"
},
"owned_by":{
"type":"user",
"id":"193973366",
"name":"Box Admin",
"login":"admin@company.com"
},
"shared_link":null,
"parent":{
"type":"folder",
"id":"16125613433",
"sequence_id":"0",
"etag":"0",
"name":"2017"
},
"item_status":"active"
},
"metadata":{
"enterprise_123456":{
"someTemplate":{
"$parent":"file_161753469109",
"$version":0,
"customerName":"Phoenix Corp",
"$type":"someTemplate-3d5fcaca-f496-4bb6-9046-d25c37bc5594",
"$typeVersion":0,
"$id":"ba52e2cc-371d-4659-8d53-50f1ac642e35",
"amount":100,
"claimDate":"2016-04-10T00:00:00Z",
"region":"West",
"$typeScope":"enterprise_123456"
}
}
}
}
],
"limit": 20,
"next_marker":"AAAAAmVYB1FWec8GH6yWu2nwmanfMh07IyYInaa7DZDYjgO1H4KoLW29vPlLY173OKsci6h6xGh61gG73gnaxoS+o0BbI1/h6le6cikjlupVhASwJ2Cj0tOD9wlnrUMHHw3/ISf+uuACzrOMhN6d5fYrbidPzS6MdhJOejuYlvsg4tcBYzjauP3+VU51p77HFAIuObnJT0ff"
}
By default this API returns 20 items per page, but more items can be requested
using marker-based pagination.