Search

The Box API provides a way to find content in Box using full-text search queries. Support for the Box search API is available in all our supported SDKs and the CLI.

cURL

curl -i -X GET "https://api.box.com/2.0/search?query=sales" \
     -H "authorization: Bearer <ACCESS_TOKEN>"

await client.search.searchForContent({
  ancestorFolderIds: ['0'],
  mdfilters: [
    {
      filters: searchFilters,
      scope: 'enterprise' as MetadataFilterScopeField,
      templateKey: templateKey,
    } satisfies MetadataFilter,
  ],
} satisfies SearchForContentQueryParams);

client.search.search_for_content(
    ancestor_folder_ids=["0"],
    mdfilters=[
        MetadataFilter(
            filters=search_filters,
            scope=MetadataFilterScopeField.ENTERPRISE,
            template_key=template_key,
        )
    ],
)

client.getSearch().searchForContent(new SearchForContentQueryParams.Builder().ancestorFolderIds(Arrays.asList("0")).mdfilters(Arrays.asList(new MetadataFilter.Builder().scope(MetadataFilterScopeField.ENTERPRISE).templateKey(templateKey).filters(searchFilters).build())).build())

// Find the first 10 files matching "taxes"
long offsetValue = 0;
long limitValue = 10;
BoxSearch boxSearch = new BoxSearch(api);
BoxSearchParameters searchParams = new BoxSearchParameters();
searchParams.setQuery("taxes");
searchParams.setType("file");
PartialCollection<BoxItem.Info> searchResults = boxSearch.searchRange(offsetValue, limitValue, searchParams);

items = client.search().query(query='TEST QUERY', limit=100, file_extensions=['pdf', 'doc'])
for item in items:
    print(f'The item ID is {item.id} and the item name is {item.name}')

// Search for PDF or Word documents matching "Meeting Notes"
BoxCollection<BoxItem> results = await client.SearchManager
    .QueryAsync("Meeting Notes", fileExtensions: new { "pdf", "docx" });

// Search for PDF or Word documents matching "Mobile"
client.search.query(
	'Mobile',
	{
		fields: 'name,modified_at,size,extension,permissions,sync_state',
		file_extensions: 'pdf,doc',
		limit: 200,
		offset: 0
	})
	.then(results => {
		/* results -> {
			total_count: 1,
			entries: 
			[ { type: 'file',
				id: '11111',
				sequence_id: '1',
				etag: '1',
				sha1: 'f89d97c5eea0a68e2cec911s932eca34a52355d2',
				name: 'Box for Sales - Empowering Your Mobile Worker White paper 2pg (External).pdf',
				description: '',
				size: 408979,
				path_collection: 
					{ total_count: 2,
					entries: 
					[ { type: 'folder',
						id: '0',
						sequence_id: null,
						etag: null,
						name: 'All Files' },
						{ type: 'folder',
						id: '22222',
						sequence_id: '1',
						etag: '1',
						name: 'Marketing Active Work' } ] },
				created_at: '2014-05-17T12:59:45-07:00',
				modified_at: '2014-05-17T13:00:20-07:00',
				trashed_at: null,
				purged_at: null,
				content_created_at: '2014-05-17T12:58:58-07:00',
				content_modified_at: '2014-05-17T12:58:58-07:00',
				created_by: 
					{ type: 'user',
					id: '33333',
					name: 'Example User',
					login: '[e-mail]' },
				modified_by: 
					{ type: 'user',
					id: '33333',
					name: 'Example User',
					login: '[e-mail]' },
				owned_by: 
					{ type: 'user',
					id: '33333',
					name: 'Example User',
					login: '[e-mail]' },
				shared_link: null,
				parent: 
					{ type: 'folder',
					id: '22222',
					sequence_id: '1',
					etag: '1',
					name: 'Marketing Active Work' },
				item_status: 'active' } ],
			limit: 200,
			offset: 0 }
		*/
	});

Explore the to learn more about all the different features available to the search API.

Query operators

The search API supports a few different , including AND, OR, NOT and "". These operators can be used to refine the search results to only return items that match a more complicated combination of search terms.

curl -i -X GET "https://api.box.com/2.0/search?query=box%20AND%20sales" \
    -H "Authorization: Bearer <ACCESS_TOKEN>"

Learn more about using logical operators

Search indexing

Box keeps a search index for any files or folder stored in Box. Every time a file or folder is changed, those words are added to the index. When a search is performed, the API looks in the search index for files and folders that match the query. When content is added, updated, or deleted in Box, the search index is updated accordingly.

Learn more about the Box search index

In some cases an index might not be updated even after a few seconds. In those cases we recommend reaching out to Box Support to get the issue resolved.

If your enterprise has full text search turned off (e.g. Keysafe customers), characters within a document cannot be searched. If you need to find out if full text search is turned off, reach out to your account team.

Comparison to Metadata Queries

At the surface the search API seems very similar to the , but there are several important differences in how they operate. At a high level the Metadata Queries are optimized for exactness and throughput, while regular search is optimized for relevance to a human user.

What is indexed?	This API only return files/folders based on the values in the metadata templates that are searched	This API returns files, folders and web links based on values in the item names, descriptions, contents (up to the first 10,000 bytes) as well as the associated metadata template instances
Indexing time	This API will return accurate results as soon as metadata has been added, removed, updated or deleted for a file or folder	This API is subject to a search indexing delay, which is typically a few seconds yet may be longer in some cases. This means that items may not be returned for more than a few seconds after metadata has been updated
Matching	This API uses exact matching based on SQL conventions. Results are returned based on a specified sort order	This API uses fuzzy matching and may return results that vary based on string tokenization, removal of special characters, and other search concepts. Result order is based on either relevance or the updated date of the item
Conditional logic	This API supports multi-part boolean expressions with comparison operators	This API has limited support for querying by metadata. It only supports querying 1 metadata template at a time and only allows simple query operations.
Response type	This API returns both the matched file/folder and the associated metadata matched by the query	This API only returns the matched item. A subsequent API call is needed to return each item’s metadata
Throughput	This API is currently subject to per-user rate limits and to a 10 requests per second per enterprise limit	This API supports 6 searches per second per user, up to 60 searches per minute and 12 searches per second per enterprise
Scale	This API has no limit on the number of items with the specified metadata template that can be returned. It is recommended to only send queries which match no more than 2,000 results.	This API has no limit on number of items with the specified metadata template that can be returned, yet the response time increases significantly as the number of items matching the search grows. This API does have a limit of up to 10 million results for a query. It is recommended to only send queries which match no more than 50,000 results.
Scope	This API is always limited to the content to which the user has access	This API may be either limited to the content to which the user has access (​user_content​) or to all content in the enterprise (​enterprise_content​).

Learn more about the metadata query API