Skip to main content
The Box Metadata API enables you to programmatically find content on the basis of Box metadata.  Using the Metadata API, you can
  • pass a set of parameters and conditions in a structure similar to a traditional SQL query, and
  • get matching files and folders along with the corresponding Metadata.
The Metadata Query API complements the Search API, which previously was the only way to use the API to find content based on metadata.

​
Using the Metadata API

Use the Metadata Query API when you want to
  • find content based strictly on Box Metadata and not document content,
  • find results that immediately reflect creates, updates, and deletes to metadata values,
  • leverage SQL-like logic to find content.
The Metadata Query API provides the ability to find content based strictly on values stored in custom metadata.  The structure of a metadata query is similar to that of an SQL query, and should feel familiar to anyone with SQL experience.  The Metadata Query API enables you to write a query against a metadata template using boolean operators — for example, AND, OR, and NOT — as well as comparison and range operators — such as equal to, greater than, less than — and get results almost instantaneously. A major benefit of the Metadata Query API is that results reflect metadata creations, updates, and immediate deletions.  And no indexing delay occurs as with the Search API. The Metadata Query API also isn’t limited on the number of characters that are queryable - just the limits of the metadata instance size itself. Unlike the Search API, however, the Metadata Query API does not support the “enterprise_content” scope. A metadata query returns results only for content to which you have Collaborator access. For more information on Metadata Querying and Indexes, see the developer documentation here.

​
Using the Search API

Use the Search API when you want
  • fuzzy matching,
  • results  based on document text and metadata,
  • enterprise-wide search.
You can use the Search API to primarily search by file or folder names, as well as the corresponding document text, to find the most relevant results.  And while you can use the Search API to search for and filter results based on metadata criteria, these searches are limited to simple boolean searches, for example, “field” = “value”. As with searches on file name or document text, metadata searches are technically “fuzzy” searches. This means that searching may return results that don’t contain the exact term you have searched for. The Box Search API relies on indexing, which is a process that happens whenever you upload or modify content or metadata.  Indexing allows the Search API to find your content more easily, but with some limitations. The Search API has two main limitations:
  • The indexing process is not instantaneous and therefore content is not immediately searchable. Indexing typically occurs within ten minutes, but can take longer depending on system load.
  • The supported operations for metadata filters are limited.  The Search API  doesn’t perform comparisons on multiple metadata fields.
If you’re an administrator, you can search using the “enterprise_content” scope.  This means that even if you don’t have access to view the file, you’re still able to get the file information for processes such as eDiscovery.

​
Metadata Query versus Search Scenarios

With both these tools at your disposal, you now can choose which to use and when. But which should you use? Here are a few situations illustrating when to use the Search API, and when to use Metadata Query API.
ScenarioWhich to use
You want to find all content in an enterprise with document text or metadata that matches the keyword “Guarantee” for eDiscovery.

Search API


The Search API matches terms in both content and metadata, and can be scoped to all content in the enterprise.

You want to find all documents with the metadata template “Contract” that have

  • a value greater than $100,000,
  • a renewal date in 2025, and
  • are associated with the North America sales region.

Metadata Query


With a metadata query, you can write boolean expressions that evaluates multiple fields in a template, such as a number, date, and string.

You want to find all documents with the metadata template “Contract” that have

  • a value greater than $100,000,
  • a renewal date in 2025, and
  • are associated with the North American sales region, and
  • contain the term “Acme” in the file name or document text.

This is not supported.


You cannot mix both fuzzy search (the document contains the term “Acme”) and the boolean expression matching metadata fields.