# Search The platform provides system methods to search and filter results by their metadata. For example, [`/system/findDataObjects`](#api-method-system-finddataobjects) can return a list of all data objects that you can access, filtered by name, tags, types, regions, properties, and other metadata attributes. For searching structured metadata with [Omics Data Catalog](https://documentation.dnanexus.com/user/omics-data-catalog), use [`/system/findDataCatalogs`](https://documentation.dnanexus.com/developer/system-methods#api-method-system-finddatacatalogs) to discover catalogs and [`/dataCatalog-xxxx/findRecords`](https://documentation.dnanexus.com/developer/omics-data-catalog#api-method-datacatalog-xxxx-findrecords) to search metadata records available to you. ## Regular Expressions and Globbing In some of these API methods, you can restrict your search to names matching a particular [regular expression](https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions) or a [glob](https://en.wikipedia.org/wiki/Glob_\(programming\)) (wildcard pattern). For the glob pattern, the wildcard `"*"` matches a string of any length and the wildcard `"?"` matches a single character. (The bracket notation `[]` is not supported.) If you are searching for the actual characters `*` , `?`, or `\`, you must escape them with a backslash, for example, `\*` instead of `*`. Because backslashes must themselves be escaped in JSON strings, your API input requires double escaping: the input string `"\\*a\\?xfoo\\\\"` matches the exact string `"*a?xfoo\"`. ## Pagination of Results The `limit` and `starting` input parameters, together with the `next` output field, can be used to paginate the results. The `limit` parameter determines the maximum number of returned results. If there are more results than `limit` allowed for, then `next` is non-null and may be used as the `starting` argument for a subsequent call. If the call is repeated with the `starting` input parameter set to the previous call's `next` return value, then the next unique subset of results is returned. Repeat this process until `next` is `null` to retrieve all results. ## Search API Method Specifications ### API method: `/system/findDataObjects` #### Specification Searches for data objects satisfying particular constraints. By default this returns all entities and objects for which the user has at least "VIEW" permission (permission acquired by PUBLIC nature of a project is not counted in this criterion). This constraint cannot be removed. However, additional constraints can be specified that can further restrict the objects that are returned. **Ordering of results**: Data objects from the same project always appear together in the search results in descending order of their last modified timestamp, unless overwritten by the `sortBy` input field. Ties are broken in ascending order of their IDs. #### Inputs * `class` **string** (optional) The entity type to restrict the search by. * Must be one of `"record"`, `"file"`, `"applet"`, or `"workflow"`. * `state` **string** (optional) The state to filter results by. Defaults to `"any"`. * Must be one of `"open"`, `"closing"`, `"closed"`, or `"any"`. * `visibility` **string** (optional) The visibility filter for results. Defaults to `"visible"`. * Must be one of `"hidden"`, `"visible"`, or `"either"`. * `name` **string or mapping** (optional) If a string, the exact case-sensitive name that the results must have. If a mapping, then it can have a subset of the following fields: * `regexp` **string** (mutually exclusive with `glob`, required if `glob` is not present) A PCRE ([external link](https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions)) regular expression that the name of all results must match. * `flags` **string** (optional, can only be present if `regexp` is present) This field can only have value "i", which denotes that case-insensitive matching should be performed with the regular expression. * `glob` **string** (mutually exclusive with `regexp`, required if `regexp` is not present) A wildcard pattern that the name of all results must match. The valid wildcard characters are `"*"` (0 or more characters) and `"?"` (1 character). * `id` **array of strings** (optional) If provided, results must have object IDs among the provided list of IDs. If the ID is not accessible to the user or does not exist, that ID is not included in the results array. The array may have no more than 1000 elements. The number of results may exceed the number of IDs provided here because an object appears once in the results for each accessible project it is found in, unless `scope.project` is set. * `type` **string or mapping** (optional) Specifies the types that matching results must have. Can be provided in the following ways: * A string to match a single type exactly, for example, `"gene"`. * An AND condition requiring all specified types to match, for example, `{"$and": ["gene", "coding"]}`. * An OR condition requiring at least one specified type to match, for example, `{"$or": ["gene", "transcript"]}`. * Complex nested conditions: `{"$or": ["gene", {"$and": ["transcript", "protein"]}]}`. * `tags` **string or mapping** (optional) Specifies the tags that matching results must have. Can be provided in the following ways: * A string to match a single tag exactly, for example, `"validated"`. * An AND condition requiring all specified tags to match, for example, `{"$and": ["validated", "curated"]}`. * An OR condition requiring at least one specified tag to match, for example, `{"$or": ["validated", "provisional"]}`. * Complex nested conditions: `{"$or": ["validated", {"$and": ["curated", "published"]}]}`. * `region` **string or array of strings** (optional) If a string, then the result set contains only entities whose associated `region` matches the string. If an array, then the result set contains only entities whose associated `region` is one of the specified strings. * `properties` **mapping** (optional) Specifies the properties that matching results must have. Can be provided in the following ways: * A mapping of key-value pairs where each key is a property name and each value can be: * A string: The property must have exactly this value, for example, `{"species": "human"}`. * A boolean `true`: The property must exist with any value, for example, `{"sequenced": true}`. * A boolean `false`: The property must not exist, for example, `{"deprecated": false}`. * The mapping `{$ne: value}`: The property must not equal the specified value, for example, `{"species": {$ne: "mouse"}}`. * An AND condition requiring all specified property constraints to match, for example, `{"$and": [{"species": "human"}, {"sequenced": true}]}`. * An OR condition requiring at least one specified property constraint to match, for example, `{"$or": [{"species": "human"}, {"species": "mouse"}]}`. * Complex nested conditions: `{"$or": [{"species": "human"}, {"$and": [{"sequenced": true}, {"quality": "high"}]}]}`. * `link` **string** (optional) An object ID to which matching objects must link to in their details. * `scope` **mapping** (optional) Restrict the search to a particular project. * `project` **string** (required) ID of the project in which all results must reside. * `folder` **string** (optional) Folder path in `project` in which all results must reside. Defaults to `"/"`. * `recurse` **boolean** (optional) Whether the search should be performed recursively on subfolders as well. Defaults to `true`. * `sortBy` **mapping** (optional) Changes the ordering that the result set is returned in. Must be specified with the `scope` field. * `field` **string** (required) The field that determines the sort order of the result set. * Must be `"created"`. * `ordering` **string** (required) The arrangement of the result set based on the field. * Must be one of `"ascending"` or `"descending"`. * `level` **string** (optional) The minimum permissions level by which to restrict the list of projects searched. Defaults to `"VIEW"`. * Must be one of `"VIEW"`, `"UPLOAD"`, `"CONTRIBUTE"`, or `"ADMINISTER"`. * `modified` **mapping** (optional) If at least one of the following keys is specified, the resulting data objects must have been last modified in the indicated time period. If not specified, there is no constraint on when the data object was last modified. If a `modified` hash does not contain at least one of the following keys, an error is thrown. * `after` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) (optional) If specified, only return results that were last modified at or after this time. * `before` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) (optional) If specified, only return results that were last modified at or before this time. * `created` **mapping** (optional) If at least one of the following keys is specified, the resulting data objects must have been created in the indicated time period. If not specified, there is no constraint on data object creation time. If a `created` hash does not contain at least one of the following keys, an error is thrown. * `after` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) (optional) If specified, only return results created at or after this time. * `before` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) (optional) If specified, only return results created at or before this time. * `describe` **boolean or mapping** (optional) Controls whether extra metadata is retrieved with the results. Defaults to `false`. * If a **mapping**, represents the input for calling the result's corresponding describe method. * `starting` **mapping** (optional) Continue a previous query that had reached its limit. The non-null value that was returned as `next` in the query's output should be provided here. * `limit` **integer** (optional) Maximum number of results that may be returned. Defaults to `1000`. Must be between 1 and 1000 (inclusive). * `archivalState` **string** (optional) The archival state to filter results by. Requires the additional input `class` having the value `"file"`. `scope.project` and `scope.folder` must also be set. Defaults to `"any"`. * Must be one of `"archived"`, `"live"`, `"archival"`, `"unarchiving"`, or `"any"`. #### Outputs * `results` **array of mappings** List of results, each with the following fields: * `project` **string** ID of the project in which the result was found. * `id` **string** ID of the result. * `describe` **mapping** The output of the result's corresponding describe method. * Only present when `describe` was supplied as an input. * `next` **mapping** (nullable) Pagination cursor, or `null` if all results were reported in `results`. If a mapping, pass this value directly to `starting` in a subsequent query if more results are desired. #### Errors * InvalidInput * The input is not a hash * `class` (if supplied) is not one of: "record", "file", "applet", or "workflow" * `state` (if supplied) is not one of: "open", "closing", "closed", or "any" * `visibility` (if supplied) is not one of: "hidden", "visible", or "either" * `level` (if supplied) is not one of: "VIEW", "UPLOAD", "CONTRIBUTE", or "ADMINISTER" * `name` (if supplied) is not a string or a mapping such that any of the following is satisfied * `flags` is present, but key `regexp` is missing or the value supplied to `flags` is not "i". * Mutually exclusive keys `glob` and `regexp` are provided together * Neither `glob` nor `regexp` is present * `id` (if supplied) is an array containing greater than 1000 elements * `type`, `properties`, or `tags` (if supplied) do not take any of the specified values * `region` (if supplied) is not a supported region. See [Regions](https://documentation.dnanexus.com/developer/api/regions) for more information * `modified` or `created` (if supplied) does not contain either an `after` or `before` timestamp * `limit` is not between 1 and 1000 * `sortBy` was specified without also specifying `scope` * `archivalState` if supplied, is not one of "archived", "live", "archival", "unarchiving", or "any". Also returns error if the value of class is not "file", `scope.project` is not set, or `scope.folder` is not set. * PermissionDenied * VIEW access to the project specified in `scope.project` is required if `scope.project` is supplied. ### API method: `/system/findDatabases` #### Specification Searches for database data objects satisfying particular constraints. By default this returns all database objects from projects for which the user has at least "VIEW" permission and which are accessible through the license. Permission acquired by PUBLIC nature of a project is counted in this criterion only when `public` key of the input is set to true. Additional constraints can be specified that can further restrict the objects that are returned. **Ordering of results**: Database data objects from the same project always appear together in the search results in descending order of their last modified timestamp, with ties broken in ascending order of their IDs. #### Inputs * `databaseName` **string or mapping** (optional) If a string, the exact case-sensitive `databaseName` that the results must have. If a mapping, then it can have a subset of the following fields: * `regexp` **string** (mutually exclusive with `glob`, required if `glob` is not present) A PCRE ([external link](https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions)) regular expression that the `databaseName` of all results must match. * `flags` **string** (optional, can only be present if `regexp` is present) This field can only have value "i", which denotes that case-insensitive matching should be performed with the regular expression. * `glob` **string** (mutually exclusive with `regexp`, required if `regexp` is not present) A wildcard pattern that the `databaseName` of all results must match. The valid wildcard characters are `"*"` (0 or more characters) and `"?"` (1 character). * `uniqueDatabaseName` **string or mapping** (optional) If a string, the exact case-sensitive uniqueDatabaseName that the results must have. If a mapping, then it can have a subset of the following fields: * `regexp` **string** (mutually exclusive with `glob`, required if `glob` is not present) A PCRE ([external link](https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions)) regular expression that the uniqueDatabaseName of all results must match. * `flags` **string** (optional, can only be present if `regexp` is present) This field can only have value "i", which denotes that case-insensitive matching should be performed with the regular expression. * `glob` **string** (mutually exclusive with `regexp`, required if `regexp` is not present) A wildcard pattern that the uniqueDatabaseName of all results must match. The valid wildcard characters are `"*"` (0 or more characters) and `"?"` (1 character). * `visibility` **string** (optional) The visibility filter for results. Defaults to `"visible"`. * Must be one of `"hidden"`, `"visible"`, or `"either"`. * `region` **string or array of strings** (optional) If a string, then the result set contains only entities whose associated `region` matches the string. If an array, then the result set contains only entities whose associated `region` is one of the specified strings. * `scope` **mapping** (optional) Restrict the search to a particular project. * `project` **string** (required) ID of the project in which all results must reside. * `folder` **string** (optional) Folder path in `project` in which all results must reside. Defaults to `"/"`. * `recurse` **boolean** (optional) Whether the search should be performed recursively on subfolders as well. Defaults to `true`. * `level` **string** (optional) The minimum permissions level by which to restrict the list of projects searched. Defaults to `"VIEW"`. * Must be one of `"VIEW"`, `"UPLOAD"`, `"CONTRIBUTE"`, or `"ADMINISTER"`. * `public` **boolean** (optional) Whether the search should be performed also on PUBLIC projects. Defaults to `false`. * `modified` **mapping** (optional) If at least one of the following keys is specified, the resulting data objects must have been last modified in the indicated time period. If not specified, there is no constraint on when the data object was last modified. If a `modified` hash does not contain at least one of the following keys, an error is thrown. * `after` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) (optional) If specified, only return results that were last modified at or after this time. * `before` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) (optional) If specified, only return results that were last modified at or before this time. * `created` **mapping** (optional) If at least one of the following keys is specified, the resulting data objects must have been created in the indicated time period. If not specified, there is no constraint on data object creation time. If a `created` hash does not contain at least one of the following keys, an error is thrown. * `after` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) (optional) If specified, only return results created at or after this time. * `before` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) (optional) If specified, only return results created at or before this time. * `describe` **boolean or mapping** (optional) Controls whether extra metadata is retrieved with the results. Defaults to `false`. * If a **mapping**, represents the input for calling the result's corresponding describe method. * `starting` **mapping** (optional) Continue a previous query that had reached its limit. The non-null value that was returned as `next` in the query's output should be provided here. * `limit` **integer** (optional) Maximum number of results that may be returned. Defaults to `1000`. Must be between 1 and 1000 (inclusive). #### Outputs * `results` **array of mappings** List of results, each with the following fields: * `project` **string** ID of the project in which the result was found. * `id` **string** ID of the result. * `level` **string** Permission level of the project in which the result was found. * `describe` **mapping** The output of the result's corresponding describe method. * Only present when `describe` was supplied as an input. * `next` **mapping** (nullable) Pagination cursor, or `null` if all results were reported in `results`. If a mapping, pass this value directly to `starting` in a subsequent query if more results are desired. #### Errors * InvalidInput * `databaseName` or `uniqueDatabaseName` (if supplied) is not a string or a mapping such that any of the following is satisfied \* `flags` is present, but key `regexp` is missing or the value supplied to `flags` is not "i". * Mutually exclusive keys `glob` and `regexp` are provided together * Neither `glob` nor `regexp` is present * `level` (if supplied) is not one of: "VIEW", "UPLOAD", "CONTRIBUTE", or "ADMINISTER" * `region` (if supplied) is not one of the supported regions. See [Regions](https://documentation.dnanexus.com/developer/api/regions) for more information * `modified` or `created` (if supplied) does not contain either an `after` or `before` timestamp * `limit` is not between 1 and 1000 * ResourceNotFound * Project specified in `scope.project` or `starting.project` needs to be under license to be accessible for this action * PermissionDenied * VIEW access to the project specified in `scope.project` is required if `scope.project` is supplied * VIEW access to the project specified in `starting.project` is required if `starting` is supplied ### API method: `/system/findExecutions` #### Specification Searches for execution (job or analysis) objects. **Ordering of results**: Jobs and analyses returned by `/system/findExecutions`, `/system/findJobs`, and `/system/findAnalyses` are sorted by their created timestamp (in descending order, that is, the latest execution appears first). Ties are broken in ascending order of their IDs. Job tries with the same created timestamp and same job ID are returned in an undefined order that is consistent across API calls. #### Inputs * `class` **string** (optional) Entity type to restrict the search by. * Must be one of `"job"` or `"analysis"`. * `includeSubjobs` **boolean** (optional) If set to false, only non-subjob executions are returned, which includes master jobs, origin jobs, or analyses. Defaults to `true`. * `includeRestarted` **boolean** (optional) If set to true, returns information about initial job tries for restarted jobs and jobs within execution subtrees rooted in these initial tries (for jobs belonging to root executions launched after July 12, 2023 00:13 UTC) also to the final job tries and execution subtrees rooted in the final job tries which are returned for both `true` and `false` values of this input argument. When setting `includeRestarted` flag to true, use the `describe` input argument to output the values of `try` to distinguish between different tries of the same output job ID. Defaults to `false`. * `launchedBy` **string** (optional) ID of the user who launched the job. * `name` **string or mapping** (optional) If a string, the exact case-sensitive name that the results must have. If a mapping, then it can have a subset of the following fields: * `regexp` **string** (mutually exclusive with `glob`, required if `glob` is not present) A PCRE ([external link](https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions)) regular expression that the name of all results must match. * `flags` **string** (optional, can only be present if `regexp` is present) This field can only have value "i", which denotes that case-insensitive matching should be performed with the regular expression. * `glob` **string** (mutually exclusive with `regexp`, required if `regexp` is not present) A wildcard pattern that the name of all results must match. The valid wildcard characters are `"*"` (0 or more characters) and `"?"` (1 character). * `id` **array of strings** (optional) If provided, results must have execution IDs among the provided list of IDs. The array may have no more than 1000 elements. Job IDs (if provided) output information for the latest tries. `/system/describeExecutions` can be used to fetch information about specific job tries. * `executable` **string** (optional) ID of the executable (app or applet) that the results were responsible for running. * `project` **string** (optional) ID of the project context, or the project in which the job was launched. * `tags` **string or mapping** (optional) Specifies the tags that matching results must have. Can be provided in the following ways: * A string to match a single tag exactly, for example, `"completed"`. * An AND condition requiring all specified tags to match, for example, `{"$and": ["completed", "verified"]}`. * An OR condition requiring at least one specified tag to match, for example, `{"$or": ["completed", "in_progress"]}`. * Complex nested conditions: `{"$or": ["completed", {"$and": ["verified", "reviewed"]}]}`. * `properties` **mapping** (optional) Specifies the properties that matching results must have. Can be provided in the following ways: * A mapping of key-value pairs where each key is a property name and each value can be: * A string: The property must have exactly this value, for example, `{"status": "success"}`. * A boolean `true`: The property must exist with any value, for example, `{"benchmark": true}`. * An AND condition requiring all specified property constraints to match, for example, `{"$and": [{"status": "success"}, {"benchmark": true}]}`. * An OR condition requiring at least one specified property constraint to match, for example, `{"$or": [{"status": "success"}, {"status": "partial_success"}]}`. * Complex nested conditions: `{"$or": [{"status": "success"}, {"$and": [{"benchmark": true}, {"quality": "high"}]}]}`. * `state` **string or array of strings** (optional) States that the results must be in. Possible values by execution type: | Execution type | States | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Job | `idle`, `waiting_on_input`, `runnable`, `running`, `waiting_on_output`, `done`, `restarted`, `restartable`, `debug_hold`, `failed`, `terminating`, `terminated` | | Analysis | `in_progress`, `done`, `partially_failed`, `failed`, `terminating`, `terminated` | Queries to `/system/findExecutions` can use states from either list. * `rootExecution` **string or array of strings** (optional) One or more IDs of the top-level (user-initiated) execution. The results are constrained to executions in those execution trees. If `includeRestarted` input is set to true, trees for all tries with the specified root executions (all tries of the root executions, and everything rooted in all the tries) are returned for root executions launched after July 12, 2023 00:13 UTC. * `originJob` **string or array of strings** (optional) Restrict results to executions which have one of the provided string IDs as an origin job. An *origin job* is one launched via `/app-xxxx/run` or `/applet-xxxx/run`, or as a stage in an analysis. If `includeRestarted` input is set to true, trees for all tries with the specified origin jobs are returned for origin jobs that belong to root executions launched after July 12, 2023 00:13 UTC. * `parentJob` **string** (optional, nullable) If the value is a string, then all results must be executions directly launched by `parentJob`. If the value is `null`, then only executions with no parent job are searched. Use `null` values for this field and `parentAnalysis` to restrict the search to root executions only. * `parentJobTry` **non-negative integer** (optional) If `includeRestarted` is true and `parentJobTry` is specified, only the children of `parentJobTry` of `parentJob` are returned. If `parentJob` string is specified but `parentJobTry` is not specified, only the children of the latest `parentJob` try are returned. * `parentAnalysis` **string** (optional, nullable) If the value is a string, then all results must be executions launched as stages of `parentAnalysis`. If the value is `null`, then only executions which do not have a parent analysis are searched. Use `null` values for this field and `parentJob` to restrict the search to root executions only. * `created` **mapping** (optional) If at least one of the following keys is specified, the resulting execution objects must have been created in the indicated time period. If not specified, there is no constraint on execution object creation time. If a `created` hash does not contain at least one of the following keys, an error is thrown. * `after` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) (optional) If specified, only return results created at or after this time. * `before` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) (optional) If specified, only return results created at or before this time. * `describe` **boolean or mapping** (optional) Controls whether extra metadata is retrieved with the results. Defaults to `false`. * If a **mapping**, represents the input for calling the corresponding describe method on each result. The mapping should be of the format `{"fields": {"field1": true, "field2": true, ...}}`. * `starting` **string** (optional) Continue a previous query that had reached its limit. The non-null value that was returned as `next` in the query's output should be provided here. * `limit` **integer** (optional) Maximum number of results that may be returned. Defaults to `1000`. Must be between 1 and 1000 (inclusive). #### Outputs * `results` **array of mappings** List of results, each with the following fields: * `id` **string** ID of the result. * `describe` **mapping** The output of the result's corresponding describe method. * Only present when `describe` was set as an input. * `next` **string** (nullable) Pagination cursor, or `null` if all results were reported in `results`. If a string, pass this value directly to `starting` in a subsequent query if more results are desired. #### Errors * InvalidInput * `id` input cannot be specified with `includeRestarted` set to `true` * `parentJobTry` cannot be specified without specifying `parentJob` input * `parentJobTry` cannot be specified without `includeRestarted` set to `true` See [Errors (Protocols)](https://documentation.dnanexus.com/developer/api/protocols) for additional information. ### API method: `/system/findAnalyses` This method is the same as [`/system/findExecutions`](#api-method-system-findexecutions) with the `class` constraint set to "analysis". ### API method: `/system/findJobs` This method is the same as `/system/findExecutions` with the `class` constraint set to "job". ### API method: `/system/findApps` #### Specification This API method provides functionality to search for apps. The ordering of results is arbitrary. Only apps for which the requesting user has access to are returned. This includes apps where the user is on the authorized users list. #### Inputs * `name` **string or mapping** (optional) If a string, the exact case-sensitive name that the results must have. If a mapping, then it can have a subset of the following fields: * `regexp` **string** (mutually exclusive with `glob`, required if `glob` is not present) A PCRE ([external link](https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions)) regular expression that the name of all results must match. * `flags` **string** (optional, can only be present if `regexp` is present) This field can only have value "i", which denotes that case-insensitive matching should be performed with the regular expression. * `glob` **string** (mutually exclusive with `regexp`, required if `regexp` is not present) A wildcard pattern that the name of all results must match. The valid wildcard characters are `"*"` (0 or more characters) and `"?"` (1 character). * `category` **string or mapping** (optional) Specifies the category or categories that matching apps must have. Can be provided in the following ways: * A string to match a single category exactly, for example, `"Alignment"`. * An AND condition requiring all specified categories to match, for example, `{"$and": ["Alignment", "NGS"]}`. * An OR condition requiring at least one specified category to match, for example, `{"$or": ["Alignment", "Variant Calling"]}`. * Complex nested conditions: `{"$or": ["Alignment", {"$and": ["NGS", "RNA-Seq"]}]}`. * `allVersions` **boolean** (optional) Whether to remove the restriction that only app versions tagged with "default" are returned. Defaults to `false`. * `published` **boolean** (optional) If true, only published apps are returned. If false, only unpublished apps are returned. * `billTo` **string or array of strings** (optional) If a string, then the result set contains only apps whose `billTo` matches the string. If an array, then the result set contains only apps whose `billTo` is one of the specified entities. * `createdBy` **string** (optional) ID of the user who created the app. * `developer` **string** (optional) ID of a developer the app must have. * `authorizedUser` **string** (optional) userID, orgID or "PUBLIC" that must exist in each app's `authorizedUsers` list. * `modified` **mapping** (optional) If at least one of the following keys is specified, the resulting apps must have been last modified in the indicated time period. If not specified, there is no constraint on when the app was last modified. If a `modified` hash does not contain at least one of the following keys, an error is thrown. * `after` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) (optional) If specified, only return results that were last modified at or after this time. * `before` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) (optional) If specified, only return results that were last modified at or before this time. * `created` **mapping** (optional) If at least one of the following keys is specified, the resulting apps must have been created in the indicated time period. If not specified, there is no constraint on app creation time. If a `created` hash does not contain at least one of the following keys, an error is thrown. * `after` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) (optional) If specified, only return results created at or after this time. * `before` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) (optional) If specified, only return results created at or before this time. * `describe` **boolean or mapping** (optional) Controls whether extra metadata is retrieved with the results. Defaults to `false`. * If a **mapping**, represents the input for calling [`/app-xxxx/describe`](https://documentation.dnanexus.com/developer/running-analyses/apps#api-method-app-xxxx-yyyy-describe) on each of the returned results. * `starting` **string** (optional) Continue a previous query that had reached its limit. The value that was returned as `next` in the query's output should be provided here. * `limit` **integer** (optional) Maximum number of results that may be returned. Defaults to `1000`. Must be between 1 and 1000 (inclusive). #### Outputs * `results` **array of mappings** List of results, each with the following fields: * `id` **string** ID of the result. * `describe` **mapping** The output of the result's corresponding describe method. * Only present when `describe` was set as an input. * `next` **string** (nullable) Pagination cursor, or `null` if all results were reported in `results`. If a string, pass this value directly to `starting` in a subsequent query if more results are desired. #### Errors See [Errors (Protocols)](https://documentation.dnanexus.com/developer/api/protocols) ### API method: `/system/findProjects` #### Specification Find projects accessible to a user or job at a given permission level. Ordering of results is: * Descending by last modified time stamp, then * Ascending by ID #### Inputs * `name` **string or mapping** (optional) If a string, the exact case-sensitive name that the results must have. If a mapping, then it can have a subset of the following fields: * `regexp` **string** (mutually exclusive with `glob`, required if `glob` is not present) A PCRE ([external link](https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions)) regular expression that the name of all results must match. * `flags` **string** (optional, can only be present if `regexp` is present) This field can only have value "i", which denotes that case-insensitive matching should be performed with the regular expression. * `glob` **string** (mutually exclusive with `regexp`, required if `regexp` is not present) A wildcard pattern that the name of all results must match. The valid wildcard characters are `"*"` (0 or more characters) and `"?"` (1 character). * `id` **array of strings** (optional) If provided, results must have project IDs among the provided list of IDs. The array may have no more than 1000 elements. * `billTo` **string or array of strings** (optional) If a string, then the result set contains only projects whose `billTo` matches the string. If an array, then the result set contains only projects whose `billTo` is one of the specified strings. * `cloudAccount` **string** (optional) If specified, the result set contains only projects that are associated with the provided cloud account ID. * `provider` **string** (optional) If specified, the result set contains only projects that are associated with the provider ID. * `region` **string or array of strings** (optional) If a string, then the result set contains only projects whose `region` matches the string. If an array, then the result set contains only projects whose `region` is one of the specified strings. * `tags` **string or mapping** (optional) Specifies the tags that matching results must have. Can be provided in the following ways: * A string to match a single tag exactly, for example, `"production"`. * An AND condition requiring all specified tags to match, for example, `{"$and": ["production", "validated"]}`. * An OR condition requiring at least one specified tag to match, for example, `{"$or": ["production", "development"]}`. * Complex nested conditions: `{"$or": ["production", {"$and": ["validated", "reviewed"]}]}`. * `properties` **mapping** (optional) Specifies the properties that matching results must have. Can be provided in the following ways: * A mapping of key-value pairs where each key is a property name and each value can be: * A string: The property must have exactly this value, for example, `{"department": "genomics"}`. * A boolean `true`: The property must exist with any value, for example, `{"confidential": true}`. * An AND condition requiring all specified property constraints to match, for example, `{"$and": [{"department": "genomics"}, {"confidential": true}]}`. * An OR condition requiring at least one specified property constraint to match, for example, `{"$or": [{"department": "genomics"}, {"department": "proteomics"}]}`. * Complex nested conditions: `{"$or": [{"department": "genomics"}, {"$and": [{"confidential": true}, {"status": "active"}]}]}`. * `level` **string** (optional) The minimum permissions level of the project results to be returned. Defaults to `"CONTRIBUTE"`. * Must be one of `"VIEW"`, `"UPLOAD"`, `"CONTRIBUTE"`, or `"ADMINISTER"`. * `explicitPermission` **boolean** (optional) If a value of true is provided, then the results are restricted to projects for which there is at least one explicit or implicit permission. If false, then the results are restricted to public projects for which the user has neither explicit nor implicit permissions. * `public` **boolean** (optional) If set to true, then only public projects are included in result. If false, then *no* public project is included in result. * `created` **mapping** (optional) If at least one of the following keys is specified, the resulting projects must have been created in the indicated time period. If not specified, there is no constraint on project creation time. If a `created` hash does not contain at least one of the following keys, an error is thrown. * `after` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) (optional) If specified, only return results created at or after this time. * `before` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) (optional) If specified, only return results created at or before this time. * `describe` **boolean or mapping** (optional) Controls whether extra metadata is retrieved with the results. Defaults to `false`. * If a **mapping**, represents the input for calling [`/project-xxxx/describe`](https://documentation.dnanexus.com/developer/data-containers/projects#api-method-project-xxxx-describe) on each of the returned results. * `starting` **string** (optional) Continue a previous query that had reached its limit. The value that was returned as `next` in the query's output should be provided here. * `containsPHI` **boolean** (optional) If set to true, only projects that contain PHI data are retrieved. If set to false, only projects that do not contain PHI data are retrieved. * `externalUploadRestricted` **boolean** (optional) If provided, only projects with the specified `externalUploadRestricted` setting are retrieved. * `limit` **integer** (optional) Maximum number of results that may be returned. Defaults to `1000`. Must be between 1 and 1000 (inclusive). * `sharedWith` **string** (optional) If specified, the results are restricted to projects that are explicitly shared with the specified user ID, organization ID, or the string "PUBLIC" for public projects. #### Outputs * `results` **array of mappings** List of results, each with the following fields: * `id` **string** ID of the result. * `level` **string** Maximal permission level (one of `"VIEW"`, `"UPLOAD"`, `"CONTRIBUTE"`, `"ADMINISTER"`) held by the requesting user/job (either directly or through an organization). * `permissionSources` **array of strings** IDs of the sources that were granted the maximal permission level `level` through which the requesting user has access. Possible values are the user's ID, organization IDs, or the string "PUBLIC" for public projects. * Only present when an unrestricted login token is used to make this API call. * `public` **boolean** Whether the project is public. * `describe` **mapping** The output of the result's corresponding describe method. * Only present when `describe` was set as an input. * `next` **string** (nullable) Pagination cursor, or `null` if all results were reported in `results`. If a string, pass this value directly to `starting` in a subsequent query if more results are desired. #### Errors See [Errors (Protocols)](https://documentation.dnanexus.com/developer/api/protocols) ### API method: `/system/findProjectMembers` #### Specification Returns a list of all the members (user, team, or organization) of a project. {% hint style="info" %} "PUBLIC" is never included in the list of project members. Instead, the output hash contains a boolean value `public` to indicate whether the project is public {% endhint %} Ordering of results is: * Ascending by member ID. #### Inputs * `project` **string** (required) ID of the project. * `level` **string** (optional) The minimum permissions level that the members must have (granted directly to them). Defaults to `"VIEW"`. * Must be one of `"VIEW"`, `"UPLOAD"`, `"CONTRIBUTE"`, or `"ADMINISTER"`. * `describe` **boolean** (optional) Whether describe should be called for all results. Defaults to `false`. * `starting` **string** (optional) Continue a previous query that had reached its limit. The value that was returned as `next` in the query's output should be provided here. * `limit` **integer** (optional) Maximum number of results that may be returned. Defaults to `1000`. Must be between 1 and 1000 (inclusive). #### Outputs * `results` **array of mappings** List of results, each with the following fields: * `id` **string** ID of the project member. * `level` **string** Permission level for the given project granted directly to the member. * `describe` **mapping** Metadata about the project member containing the following fields: * Only present when the `describe` input was set. * `id` **string** ID of the member. * `class` **string** Either "user" or "org". * `permittedRegions` **array of strings** The regions this member can operate in. The following keys are present if `class` is "user": * `first` **string** The user's first name. * `last` **string** The user's last name. * `middle` **string** The user's middle name. * `handle` **string** The user's username or handle. The following key is present if `class` is "org": * `name` **string** Organization name. * `public` **boolean** Whether the project is public. * `next` **string** (nullable) Pagination cursor, or `null` if all results were reported in `results`. If a string, pass this value directly to `starting` in a subsequent query if more results are desired. #### Errors * InvalidInput * The input is not a hash * `level`, if provided, is not a recognized permissions level * PermissionDenied * VIEW access to the project is required ### API method: `/system/findOrgs` #### Specification Lists orgs in which the requesting user has at least the specified membership level, subject to additional query constraints. **Ordering of results**: Orgs are returned in ascending order by their IDs. #### Inputs * `id` **array of strings** (optional) If provided, results are limited to the org IDs included in the array. The array may have no more than 1000 elements. * `level` **string** (required) The results contain only orgs in which the requesting user has **at least** the specified membership level. * Must be one of `"ADMIN"` or `"MEMBER"`. * `allowBillableActivities` **boolean** (optional) If a boolean, then the results contain only orgs in which the requesting user either has (true) or does not have (false) the `allowBillableActivities` membership permission. * `describe` **boolean or mapping** (optional) Controls whether extra metadata is retrieved with the results. Defaults to `false`. * If a **mapping**, represents the input for describing each result. * `starting` **mapping** (optional) Mapping used to continue a previous query that had reached its limit. The non-null value that was returned as `next` in the output of that query should be specified here. * `limit` **integer** (optional) Maximum number of results that may be returned. Defaults to `1000`. Must be between 1 and 1000 (inclusive). #### Outputs * `results` **array of mappings** List of results, each with the following fields: * `id` **string** Org ID. * `describe` **mapping** The output of describing the corresponding org. * Only present when `describe` is set as an input. * `next` **mapping** (nullable) Pagination cursor, or `null` if all results were returned in `results`. If a mapping, specify this value as the `starting` input in a subsequent query if more results are desired. #### Errors * PermissionDenied * The requesting user does not have a full scope token See [Errors (Protocols)](https://documentation.dnanexus.com/developer/api/protocols)