APIDownloadsIndex of dx CommandsLegal

Search

Search

The platform provides system methods to search and filter results by their metadata. For example, /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.

Regular Expressions and Globbing

In some of these routes, you can restrict your search to names matching a particular regular expression or a glob (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 "\", escape them with a backslash, for example, "\_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", "workflow".

  • state string (optional, default "any") One of the values: "open", "closing", "closed", or "any".

  • visibility string (optional, default "visible") One of the values: "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) 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 ID of the project in which all results must reside

    • folder string (optional, default "/") Folder path in project in which all results must reside

    • recurse boolean (optional, default true) Whether the search should be performed recursively on subfolders as well

  • sortBy mapping (optional) Changes the ordering that the result set is returned in. Must be specified with the scope field.

    • field string The field that determines the sort order of the result set. Acceptable values: created

    • ordering string The arrangement of the result set based on the field. One of ascending or descending

  • level string (optional, default "VIEW") One of: "VIEW", "UPLOAD", "CONTRIBUTE", or "ADMINISTER", representing the minimum permissions level by which to restrict the list of projects searched

  • 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 (optional) If specified, only return results that were last modified at or after this time

    • before timestamp (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 (optional) If specified, only return results created at or after this time

    • before timestamp (optional) If specified, only return results created at or before this time

  • describe boolean or mapping (optional, default false) Either false to indicate that no extra metadata should be retrieved with the results, or a mapping representing the input that would be used for calling "describe" on each of the returned results.

  • 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 int (optional, default 1000) Maximum number of results that may be returned. Must be between 1 and 1000 (inclusive).

  • archivalState string (optional, default "any") One of the values: "archived", "live", "archival", "unarchiving", or "any". Requires the additional input class having the value "file". scope.project and scope.folder must also be set.

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 if described was supplied as an input.

  • next mapping or null If null, all results were reported in results. If a mapping, represents the next result that could not be returned because limit results have already been returned. This value should be passed 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 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) 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) 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, default "visible") One of the values: "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 ID of the project in which all results must reside

    • folder string (optional, default "/") Folder path in project in which all results must reside

    • recurse boolean (optional, default true) Whether the search should be performed recursively on subfolders as well

  • level string (optional, default "VIEW") One of: "VIEW", "UPLOAD", "CONTRIBUTE", or "ADMINISTER", representing the minimum permissions level by which to restrict the list of projects searched

  • public boolean (optional, default false) Whether the search should be performed also on PUBLIC projects

  • 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 (optional) If specified, only return results that were last modified at or after this time

    • before timestamp (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 (optional) If specified, only return results created at or after this time

    • before timestamp (optional) If specified, only return results created at or before this time

  • describe boolean or mapping (optional, default false) Either false to indicate that no extra metadata should be retrieved with the results, or a mapping representing the input that would be used for calling "describe" on each of the returned results.

  • 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 int (optional, default 1000) Maximum number of results that may be returned. 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 if describe was supplied as an input

  • next mapping or null If null, all results were reported in results. If a mapping, represents the next result that could not be returned because limit results have already been returned. This value should be passed 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 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 either "job" or "analysis"

  • includeSubjobs boolean (optional, default true) If set to false, only non-subjob executions are returned, which includes master jobs, origin jobs, or analyses

  • includeRestarted boolean (optional, default false) 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.

  • 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) 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 or null (optional) 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 or null (optional) 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 (optional) If specified, only return results created at or after this time

    • before timestamp (optional) If specified, only return results created at or before this time

  • describe boolean or mapping (optional, default false) False indicates that no extra metadata should be retrieved with the results. A mapping represents the input that would be used for calling the corresponding "describe" API method on each of the returned results. A value of true is equivalent to the empty hash input. 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 int (optional, default 1000) Maximum number of results that may be returned. 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 if describe was set as an input

  • next string or null If null, all results were reported in results. If a string, represents the next result that could not be returned because limit results have already been returned. This value should be passed 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) for additional information.

API method: /system/findAnalyses

This method is the same as /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 route 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) 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, default false) Whether to remove the restriction that only app versions tagged with "default" are returned

  • 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 (optional) If specified, only return results that were last modified at or after this time

    • before timestamp (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 (optional) If specified, only return results created at or after this time

    • before timestamp (optional) If specified, only return results created at or before this time

  • describe boolean or mapping (optional, default false) False indicates that no extra metadata should be retrieved with the results. A mapping represents the input that would be used for calling /app-xxxx/describe on each of the returned results. a value of true is equivalent to the empty hash input.

  • 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 int (optional, default 1000) Maximum number of results that may be returned. 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 if the describe method was set as an input

  • next string or null If null, all results were reported in results. If a string, represents the next result that could not be returned because limit results have already been returned. This value should be passed directly to starting in a subsequent query if more results are desired.

Errors

See Errors (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) 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, default "CONTRIBUTE") Must be one of "VIEW", "UPLOAD", "CONTRIBUTE", or "ADMINISTER" to represent the minimum permissions level of the project results to be returned

  • 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 (optional) If specified, only return results created at or after this time

    • before timestamp (optional) If specified, only return results created at or before this time

  • describe boolean or mapping (optional, default false) False indicates that no extra metadata should be retrieved with the results. A mapping represents the input that would be used for calling /project-xxxx/describe on each of the returned results. a value of true is equivalent to the empty hash input.

  • 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 int (optional, default 1000) Maximum number of results that may be returned. 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 (present only if an unrestricted login token is used to make this API call) 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

    • public boolean Whether the project is public

    • describe mapping The output of the result's corresponding describe method if describe was set as an input

  • next string or null If null, all results were reported in results. If a string, represents the next result that could not be returned because limit results have already been returned. This value should be passed directly to starting in a subsequent query if more results are desired.

Errors

See Errors (Protocols)

API method: /system/findProjectMembers

Specification

Returns a list of all the members (user, team, or organization) of a project.

"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

Ordering of results is:

  • Ascending by member ID.

Inputs

  • project string ID of the project

  • level string (optional, default "VIEW") Must be one of "VIEW", "UPLOAD", "CONTRIBUTE", or "ADMINISTER", to represent the minimum permissions level that the members must have (granted directly to them)

  • describe boolean (optional, default false) Whether describe should be called for all 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 int (optional, default 1000) Maximum number of results that may be returned. 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 if the describe input was set containing the following fields:

      • 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 or null If null, all results were reported in results. If a string, represents the next result that could not be returned because limit results have already been returned. This value should be passed 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 one of "ADMIN" or "MEMBER". The results contain only orgs in which the requesting user has at least the specified membership level.

  • 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, default false) if a mapping, then it represents the input that is used to describe each of the results. true indicates that the empty mapping is used. A value of false indicates that no extra metadata be retrieved with the results.

  • 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 int (optional, default 1000) maximum number of results that may be returned. 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 if describe is set as an input

  • next mapping or null if null, then all results were returned in results. Otherwise, represents the next result that could not be returned because limit results have already been returned. If a mapping, then this value should be specified 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)

Last updated

Was this helpful?