Sample - Box Platform API
POST/metadata_queries/execute_read

Query files/folders by metadata

Create a search using SQL-like syntax to return items that match specific metadata.

By default, this endpoint returns only the most basic info about the items for which the query matches. To get additional fields for each item, including any of the metadata, use the fields attribute in the query.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

8 body fields
fromstringrequired
Specifies the template used in the query. Must be in the form `scope.templateKey`. Not all templates can be used in this field, most notably the built-in, Box-provided classification templates can not be used in a query.
querystringoptional
The query to perform. A query is a logical expression that is very similar to a SQL `SELECT` statement. Values in the search query can be turned into parameters specified in the `query_param` arguments list to prevent having to manually insert search values into the query string. For example, a value of `:amount` would represent the `amount` value in `query_params` object.
query_paramsobjectoptional
Set of arguments corresponding to the parameters specified in the `query`. The type of each parameter used in the `query_params` must match the type of the corresponding metadata template field.
ancestor_folder_idstringrequired
The ID of the folder that you are restricting the query to. A value of zero will return results from all folders you have access to. A non-zero value will only return results found in the folder corresponding to the ID or in any of its subfolders.
order_byarray<object>optional
A list of template fields and directions to sort the metadata query results by. The ordering `direction` must be the same for each item in the array.
limitintegeroptional
A value between 0 and 100 that indicates the maximum number of results to return for a single request. This only specifies a maximum boundary and will not guarantee the minimum number of results returned.
Default:100
markerstringoptional
Marker to use for requesting the next page.
fieldsarray<string>optional
By default, this endpoint returns only the most basic info about the items for which the query matches. This attribute can be used to specify a list of additional attributes to return for any item, including its metadata. This attribute takes a list of item fields, metadata template identifiers, or metadata template field identifiers. For example: * `created_by` will add the details of the user who created the item to the response. * `metadata.<scope>.<templateKey>` will return the mini-representation of the metadata instance identified by the `scope` and `templateKey`. * `metadata.<scope>.<templateKey>.<field>` will return all the mini-representation of the metadata instance identified by the `scope` and `templateKey` plus the field specified by the `field` name. Multiple fields for the same `scope` and `templateKey` can be defined.

4 status codes
200Returns a list of files and folders that match this metadata query.
entriesarray<MetadataQuerySearchResultItem>optional
The mini representation of the files and folders that match the search terms. By default, this endpoint returns only the most basic info about the items. To get additional fields for each item, including any of the metadata, use the `fields` attribute in the query.
limitintegeroptional
The limit that was used for this search. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed.
Default:100
next_markerstringoptional
The marker for the start of the next page of results.
400Returns an error when the request body is not valid. * `invalid_query` - Any of the provided body parameters might be incorrect. This can mean the `query` is incorrect, as well as some cases where the `from` value does not represent a valid template. * `unexpected_json_type` - An argument from the `query` string is not present in `query_param`. For example, `query` of `name = :name` requires the `query_param` to include a value for the `name` argument, for example `{ "name": "Box, Inc" }`.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
404Returns an error when a metadata template with the given `scope` and `templateKey` can not be found. The error response will include extra details. * `instance_not_found` - The template was not found. Please make sure to use the full template scope including the enterprise ID, like `enterprise_12345`.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
defaultAn unexpected client error.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.

Error handling

A 400 is returned: Returns an error when the request body is not valid.

  • invalid_query - Any of the provided body parameters might be incorrect. This can mean the query is incorrect, as well as some cases where the from value does not represent a valid template.

  • unexpected_json_type - An argument from the query string is not present in query_param. For example, query of name = :name requires the query_param to include a value for the name argument, for example { "name": "Box, Inc" }. A 404 is returned: Returns an error when a metadata template with the given scope and templateKey can not be found. The error response will include extra details.

  • instance_not_found - The template was not found. Please make sure to use the full template scope including the enterprise ID, like enterprise_12345. Any other status is an error: An unexpected client error.