BaseSpace Search API Reference

The BaseSpace Search API is a set of REST service endpoints that further expand the functionality of the BaseSpace API by enabling the developer with the ability to search through the API in order to create more filtered results.

OAuth Process

In order to use the Search API, you will need to include a valid access_token with the request.

For information about how to get Access Tokens, please view the [api-reference#OAuthProcess) documentation.

For information about how to use Access Tokens with your Search queries, please view the API Reference - Using the Access Token documentation.

More information about these processes can be found in the [/docs/content/documentation/authentication/obtaining-access-tokens) and App Triggering portions of this site.

URI format

The BaseSpace API encodes the version of the API in the resource URI. This guarantees that a given API will always behave the same, even if we introduce newer APIs. Example:


This path refers to API version v1pre3.

Resource Collection Requests

For requests returning collections, these query parameters are common:

  • Offset: The starting point of the collection to read, there is no maximum value for Offset. Default: 0

  • Limit: The maximum number of items to return. This value may be less than requested if the request size was reduced by the server. Default: 10, Range: 0-1024, the implicit Range of Limit for the Files resource is 0-1000.

  • SortDir: The way to sort the resulting collection, either ascending or descending. Default: 'Asc', Can be 'Asc' or 'Desc'

  • SortBy: The field to use to sort the resulting collection. This value can have multiple possibilities depending on the result type

The response will also contain these fields unless noted otherwise:

  • DisplayedCount: The number of items returned
  • TotalCount: The total number of items in the collection

Common Response Elements

These are included for all response types. In addition to Resource Collection Requests if applicable.

  • Response - The main response object

    • Items: If a list is returned, it is contained within this response element
    • Id: Id of the resource
    • Name: Name of the selected resource
    • Href: Location of the resource in the API
    • DateCreated: When this resource was created
    • UserOwnedBy: Information about the User who owns this resource
    • Status: The status of the resource, if it is inside of an appsession it is the status of the AppSession
    • HrefBaseSpaceUI: The location of this resource in the BaseSpace User Interface
    • Properties: The Properties of this resource. Some Properties are standard in BaseSpace and some are custom Properties created by Users or Apps.
  • ResponseStatus - Empty for responses with a 200 response code. For error cases, contains human-readable description of the error. The documentation on the error cases is not yet complete.

  • Notifications - An array of notifications. Documentation on this element is not complete.


  • BROWSE GLOBAL access (requires access token)

Query Parameters

  • x-access-token: The access_token that has browse global level of permission to the user's data
  • scope: The scope that you wish to have applied to the search query, possible values are sample_files, appresult_files, appresults, samples, runs, genomes, and projects
  • query: A query that you wish to apply to the search query, this is to further narrow the search results. There is a table below which shows all possible queries for the different resources above.

Search Query 'query' Options

This section describes the possible values for query when using the Search API.

Resource (`scope` value) Possible values for `query`
runs href, name, number, experimentname, reagentbarcode, flowcellbarcode, bufferbarcode, totalsize, hreffiles, hrefsamples, status, userownedby, instrument, instrumentname, instrumenttype, numcyclesread1, numcyclesread2, numcyclesindex1, numcyclesindex2
projects namedescriptionuserownedby
genomes namebuilddisplaynamespeciesnamespecies
samples namecustomidsamplenumberrootfoldersampleidprojectnameexperimentnameindexsequenceindexsequence2ispairedendread1read2numreadsrawnumreadspfismergedtotalsizestatusstatussummaryuserownedbygenomesampleappsessionrootappsessionprojectsproperty
appresults namedescriptiontotalsizeuserownedbygenomesampleappappsessionrootappsessionprojectsproperty
sample_files userownedbygenomesampleappappsessionrootappsessionprojectsfileextensionsize
appresult_files userownedbygenomeappresultappappsessionrootappsessionprojectsfileextensionsize

Each of these queryable items are objects, so in the query string you will have to go through the JSON for these resources and specify the value you would like to query, e.g. to search for a Project with a certain Name or Id you would type (<projectname>) and (<projectid>) respectively. The information available for each resource is available in the BaseSpace API Reference documentation.

For questions about the query syntax or for more advanced queries, please view the following page: This is the Query syntax for elastic search queries.

BaseSpace Search Query Examples

Some examples of search queries in BaseSpace.

Example 1

Search for a resource by name, in this example we are searching for a Run with 140609 in its name:{access_token}&query=(name:%22140609%22)

Example 2

Search for all Samples in Project with Id 2:{access_token}&query=(project.Id:2)

Example 3

Search for all Samples in Project with Id 4 and for which the Genome is hg19:{access token}&query=((