Returns information on files that meet the search query. The search query can contain one or more parameters. Keep the following in mind.

  • The search query only retrieves the latest version of a file.
  • The search query applies boolean AND logic. Every additional parameter added to the query adds an AND param to the search query. This includes custom tags and custom metadata, as well as each additional tag or metadata key.


Pass authentication information in the header. You will need the JSON Web Token (JWT) and the name of the organization to authenticate. For more information, see


Responses are in JSON Format.

200 OK

Request was successful. Results can include what is in the following table.

fromResults were retrieved starting with the array index specified. By default, files are retrieved from the start of the array (index number 0). Pairing this with the size parameter allows you to see a subset of results.number
sizeIndicates the number of results to return. By default, information for all files matching the query is returned. Pairing this with the from parameter allows you to see a subset of results.number
sortSorts the results by file creation date. Values are desc (descending), asc (ascending).string
hasNextIndicates whether other files that matched the search query were found but not included in the search results. This usually happens when you’ve used from and size to restrict the size of the query. Values are true, false.boolean
hitsContains the search results.mixed (string, uuid)
orgSlugName of your organization.string
fileIdUUID for the file in the data lake.uuid
traceIdUUID generated when the RAW file is first uploaded to the data lake. All files derived from the RAW file, such as an IDS file, have the same traceId.uuid
rawFileIdUUID for the RAW file that this file was generated from.uuid
categoryFile category. Values are RAW, IDS, and PROCESSED.string
idsName, type, and version of the schema used to create the IDS file. Format is {namespace}/{idsType}:{idsVersion}string
filePathPath to the IDS JSON
createdAtDate and time that the file was created. Note that the date/timestamp is in Zulu (UTC)
integrationTetrascience integrates with many different products, such as Box, Dotmatics, and DataHub. The response contains the integration type, file type that is produced, the source, source type, integration ID and source ID.mixed (uuid, string)
integration.idID for the integration.uuid
integration.typeIntegration type. Values are EGNYTE, BOX, DOTMATICS, HRB CELLARIO, DATAHUB, PIPELINE, RAW, and API.string
integration.nameName of the integration.String
integration.workflowId (Added version TDP 3.1.0)Workflow ID for the pipeline.String
integration.masterScript (Added version TDP 3.1.0)Name of the pipeline protocol used.String
integration.taskScript (Added version TDP 3.1.0)Name of the task script for the pipeline.String
integration.taskSlug (Added version TDP 3.1.0)Name of the slug for the task.String
integration.taskExecutionId (Added version TDP 3.1.0)Execution ID.String
sourceIndicates the source of the file. This is typically the source ID, the name of an instrument that generated the data, and a brief description of the file data.mixed (string, uuid)
source.idID for the source.uuid
source.typeType of source, which is typically the name of the instrument or other lab equipment used to generate the data or report.string
source.nameName of the source.string
fileProvides file location information including the bucket, path, checksum, size, type, and version.mixed (string, number)
file.bucketName of the data lake S3 bucket the file is assigned to.array
file.pathPath to the data lake S3 bucket where the file is stored, starting with the organization’s root directory.string
file.checksumChecksum (number of bits used to verify file integrity) assigned by the data lake S3 bucket.string
file.sizeSize of the file.number
file.typeType of file.string
file.versionFile version’s ID.uuid
metadataLists metadata, if present. Metadata could include items like the instrument or other lab equipment used to create the file and/or custom metadata the user added to the file (if any).array of strings
tagsLists tags that the user added to the file.array
deletedIndicates whether the file was deleted. Values are TRUE, FALSE.boolean
outdatedIndicates whether there is at least one newer version of the file available. If a newer version is available, outdated is set to TRUE. Values are TRUE, FALSE.boolean

401 Unauthorized

There is a problem with authorization. See for more details.

500 Internal Server Error

There is a problem with the website’s server or there is a network issue.

Additional Examples

Search for Files by Category

Files in the data lake are categorized as RAW, IDS, or PROCESSED. Adding the category parameter to your search query can speed up your search and provide more targeted results. Note that when RAW files are processed, source as well as custom tags and metadata, remain the same for the resulting IDS file. The following fetches IDS files.

curl --location --request GET '' \
--header 'ts-auth-token: {JWT_TOKEN}' \
--header 'x-org-slug: tetrascience'

Search for File Created after a Specific Date

Use the fromDate parameter to search for all files created after a certain date. The following fetches all RAW files created on or after November 1, 2020.

curl --location --request GET '' \
--header 'ts-auth-token: {JWT_TOKEN}' \
--header 'x-org-slug: tetrascience'

Search for Files by Date Range to Narrow Search Results

Sometimes when you search, many results are returned. To better target your results and speed up searching, use fromDate and toDate parameters to only fetch information about files created within a specific date range. In the following example, information about IDS files that were created between November 1 - 15, 2020 are retrieved.

curl --location --request GET '' \
--header 'ts-auth-token: {JWT_TOKEN}' \
--header 'x-org-slug: tetrascience'

Search for Pending Unprocessed Files (Pre-Tagged)

To search for files that will be processed by a third-party system, use the tag parameter to search for files tagged as pending. The following example searches for files created on or after November 1, 2020 that have pending in the metadata tags.

curl --location --request GET '' \
--header 'ts-auth-token: {JWT_TOKEN}' \
--header 'x-org-slug: tetrascience'

Search for Files Without a Specific Tag

To search for files without a specific tag, use the excludeTags parameter. The following command finds files without created on or after November 1, 2020 that have not completed processing.

curl --location --request GET '' \
--header 'ts-auth-token: {JWT_TOKEN}' \
--header 'x-org-slug: tetrascience'

Paginating Results

One way to chunk a large result set is to paginate with the from and size parameters. from indicates where the resultset begins. Note that the resultset is ordered by date. size indicates how many results to fetch per request. The following command retrieves information about 15 IDS files, starting with the 10th result of the unfiltered, complete resultset.

curl --location --request GET '' \
--header 'ts-auth-token: {JWT_TOKEN}' \
--header 'x-org-slug: tetrascience'

Search by IDS Type and Version

To find files for a specific IDS type and version, use the ids parameter. The format is {namespace}/{slug}:{version}. In the following example, information for files with the following ids type and version are retrieved: common/test-empower:v3.0.0.

curl --location --request GET '' \
--header 'ts-auth-token: {JWT_TOKEN}' \
--header 'x-org-slug: tetrascience'

Note: To find a value, use the data lake schemas API, which can be found here:

Find All Files Generated by a Specific Pipeline Workflow

(Added version TDP 3.1.0) To find files generated by a specific workflow, use the workflowId parameter. In the following example, information for files with the workflowId eeac26b1-5034-4a1d-a97f-0c8b8cd2ea1e that was generated from August 21, 2021 to the present date are retrieved.

curl --location --request GET '' \
--header 'ts-auth-token: {JWT token here}' \
--header 'x-org-slug: tetrascience' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0c1Rva2VuU2NoZW1hVmVyc2lvbiI6MSwiYXV0aFN0YWNrcyI6eyJpbmZvcm1hdGljcyI6eyJ1c2VySWQiOiI3OWM0NWViNi03ZDY5LTQyM2EtOTg0Yi0xMzM2YTMzMjJjYTkiLCJvcmdhbml6YXRpb25zIjp7IjAxNjljZDc5LTA3NmQtNGY3Yy04Y2QzLTE1ODQxMGZkZTUwZSI6eyJzbHVnIjoidGV0cmFzY2llbmNlIiwicm9sZXMiOlsiYWRtaW4iXX19fX0sImlhdCI6MTYwNjczMDk0OSwiZXhwIjoxNjA5MzIyOTQ5fQ.r5LkZkIJsWT1VMMLYMW84hJdYdbQyknz4yyrCPjcLQw'
Click Try It! to start a request and see the response here!