Box Developer Documentation

Search

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>"
TypeScript Gen
await client.search.searchForContent({
  ancestorFolderIds: ['0' as string],
  mdfilters: [
    {
      filters: {
        ['stringField']: 'stringValue',
        ['dateField']: {
          lt: dateTimeFromString('2035-01-01T00:00:00Z'),
          gt: dateTimeFromString('2035-01-03T00:00:00Z'),
        } satisfies MetadataFieldFilterDateRange,
        ['floatField']: {
          lt: 9.5,
          gt: 10.5,
        } satisfies MetadataFieldFilterFloatRange,
        ['enumField']: 'enumValue2',
        ['multiSelectField']: ['multiSelectValue1', 'multiSelectValue2'],
      },
      scope: 'enterprise' as MetadataFilterScopeField,
      templateKey: templateKey,
    } satisfies MetadataFilter,
  ],
} satisfies SearchForContentQueryParams);
Python Gen
client.search.search_for_content(
    ancestor_folder_ids=["0"],
    mdfilters=[
        MetadataFilter(
            filters={
                "stringField": "stringValue",
                "dateField": MetadataFieldFilterDateRange(
                    lt=date_time_from_string("2035-01-01T00:00:00Z"),
                    gt=date_time_from_string("2035-01-03T00:00:00Z"),
                ),
                "floatField": MetadataFieldFilterFloatRange(lt=9.5, gt=10.5),
                "enumField": "enumValue2",
                "multiSelectField": ["multiSelectValue1", "multiSelectValue2"],
            },
            scope=MetadataFilterScopeField.ENTERPRISE.value,
            template_key=template_key,
        )
    ],
)
Java
// 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);
Python
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}')
.NET
// Search for PDF or Word documents matching "Meeting Notes"
BoxCollection<BoxItem> results = await client.SearchManager
    .QueryAsync("Meeting Notes", fileExtensions: new { "pdf", "docx" });
Node
// 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: 'user@example.com' },
				modified_by: 
					{ type: 'user',
					id: '33333',
					name: 'Example User',
					login: 'user@example.com' },
				owned_by: 
					{ type: 'user',
					id: '33333',
					name: 'Example User',
					login: 'user@example.com' },
				shared_link: null,
				parent: 
					{ type: 'folder',
					id: '22222',
					sequence_id: '1',
					etag: '1',
					name: 'Marketing Active Work' },
				item_status: 'active' } ],
			limit: 200,
			offset: 0 }
		*/
	});
iOS
let iterator = client.search.query(query: "Quarterly Business Review")
iterator.next { results in
    switch results {
    case let .success(page):
        for item in page.entries {
            switch item {
            case let .file(file):
                print("- File \(file.name) (ID: \(file.id))")
            case let .folder(folder):
                print("- Folder \(file.name) (ID: \(file.id))")
            case let .webLink(webLink):
                print("- Web Link \(file.name) (ID: \(file.id))")
            }
        }

    case let .failure(error):
        print(error)
    }
}

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

Query operators

The search API supports a few different search operators, 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 10 minutes. 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 Metadata Query API, 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.

Metadata Query APISearch API
What is indexed?This API only return files/folders based on the values in the metadata templates that are searchedThis 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 timeThis API will return accurate results as soon as metadata has been added, removed, updated or deleted for a file or folderThis API is subject to a search indexing delay, which is typically 10 minutes yet may be longer in some cases. This means that items may not be returned for more than 10 minutes after metadata has been updated
MatchingThis API uses exact matching based on SQL conventions. Results are returned based on a specified sort orderThis 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 logicThis API supports multi-part boolean expressions with comparison operatorsThis 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 typeThis API returns both the matched file/folder and the associated metadata matched by the queryThis API only returns the matched item. A subsequent API call is needed to return each item's metadata
ThroughputThis API is currently subject to per-user rate limits and to a 10 requests per second per enterprise limitThis API supports 6 searches per second per user, up to 60 searches per minute and 12 searches per second per enterprise
ScaleThis 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.
ScopeThis API is always limited to the content to which the user has accessThis 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