uncountable.core.client.Client

class uncountable.core.client.Client(*, base_url, auth_details, config=None, app_base_url=None)

Helper class that provides a standard way to create an ABC using inheritance.

Parameters:
add_file_to_folder(*, file_id, folder_key, _request_options=None)

Add a previously uploaded file to a folder in the Files repository. This is the second step of a two-step upload workflow: first upload the file via file_upload/external_create_file_record to obtain a file_id, then call this endpoint to place it in a target folder. Returns the created document’s ID in result_id.

Parameters:

  • file_id (ObjectId) – ID of the file upload returned by file_upload/external_create_file_record

  • folder_key (IdentifierKey) – Target folder to place the file in. Use type ‘id’ with a folder ID, or type ‘ref_name’ with ‘root’ for the top-level folder.

  • _request_options (RequestOptions | None)

Return type:

Data

add_notebook_content(*, notebook_key, location, contents, _request_options=None)

Appends content cells to an existing notebook. Resolves the notebook by identifier key and requires SET_FIELD_VALUE permission on the notebook entity. Supports multiple content types: markdown text, HTML text, tables with styled cells, chemical structures (SMILES, Ketcher, MOL 2000/3000, RXN, SDF), equations, file attachments, images, and reaction tables with reactants/products/catalysts/solvents. Currently only supports appending to the first page of the notebook.

Parameters:

  • notebook_key (IdentifierKey) – Key of the notebook to add the content to

  • location (Location) – The location to add the content to in the notebook

  • contents (list[InputContent]) – List of input content to add to the notebook

  • _request_options (RequestOptions | None)

Return type:

Data

add_recipe_to_project(*, recipe_key, project_key, _request_options=None)

Adds an existing recipe to a project. The project may be in a different material family than the recipe.

Parameters:

  • recipe_key (IdentifierKey) – The identifier key of the recipe to add to the project

  • project_key (IdentifierKey) – The identifier key of the project to add the recipe to

  • _request_options (RequestOptions | None)

Return type:

Data

archive_recipes(*, recipes, reason=None, _request_options=None)

Archives the provided recipes and their child recipes. Fails if any of the recipes are locked. An optional reason can be provided for the archive.

Parameters:

  • recipes (list[IdentifierKey]) – Identifier for the recipe

  • reason (str | None) – This reason will be written to the audit log archive entry

  • _request_options (RequestOptions | None)

Return type:

Data

associate_equipment_input(*, equipment_key, material_family_ids, _request_options=None)

Create or return an input association for a piece of equipment within specified material families. The equipment is resolved via identifier key. Supports both direct invocation and async batch execution. Returns modification_made and result_id of the association.

Parameters:

  • equipment_key (IdentifierKey) – Identifier of the equipment to associate

  • material_family_ids (list[ObjectId]) – The list of material families to add the input to. This must be non-empty

  • _request_options (RequestOptions | None)

Return type:

Data

associate_recipe_as_input(*, recipe_key, input_key=None, show_in_listings=None, _request_options=None)

Associates a recipe as an input (ingredient). When no existing input is specified, creates a new input or returns the existing association if one already exists. When an existing input is specified, associates it with the recipe; fails if that input is already associated with a different recipe. Use disassociate_recipe_as_input to remove an existing association first. Returns the input ID and whether a modification was made.

Parameters:

  • recipe_key (IdentifierKey) – Identifier for the recipe

  • input_key (IdentifierKey | None) – Identifier for an input to use for the association. Optionally supplied. If not supplied, one is created

  • show_in_listings (bool | None) – After associating the input should it be present in listings

  • _request_options (RequestOptions | None)

Return type:

Data

associate_recipe_as_lot(*, recipe_key, ingredient_key, _request_options=None)

Creates a lot association between a recipe and an ingredient. The recipe becomes a lot for the specified ingredient. Returns whether a modification was made.

Parameters:
Return type:

Data

clear_recipe_outputs(*, recipe_key, _request_options=None)

Clears all output values and output metadata for a given recipe identified by key. Returns whether a modification was made.

Parameters:
Return type:

Data

complete_async_parse(*, async_job_key, upload_destination, parsed_file_data=None, file_id=None, _request_options=None)

Completes the asynchronous parsing step of a file upload workflow. Accepts either inline parsed_file_data or a file_id referencing a JSON file containing the parsed data (exactly one must be provided). Resolves the async job by its identifier key and applies the parsed data to the upload destination. Updates the async job status to COMPLETED upon success. Supports async batch execution.

Parameters:
Return type:

Data

complete_async_upload(*, async_job_id, file_id, _request_options=None)

Completes an asynchronous runsheet export by processing an uploaded file and placing it in the job owner’s export downloads folder. Sends an export-complete notification to the job owner on completion. Supports async batch execution.

Parameters:
Return type:

Data

convert_chemical_formats(*, source_chemical_structures, _request_options=None)

Convert chemical structure strings (MOL v2000, MOL v3000, or SMILES formats) into the Uncountable internal format for use with other APIs such as set_input_attribute_values.

Parameters:
Return type:

Data

create_entities(*, entity_type, entities_to_create, definition_id=None, definition_key=None, _request_options=None)

Batch creates new entities of a specified type within a definition. Returns the list of created entity IDs and types.

Parameters:

  • definition_id (ObjectId | None) – Definition id for the entities to create

  • definition_key (IdentifierKey | None) – Key for the definition of the entities to create

  • entity_type (LimitedEntityType) – The type of the entities to create

  • entities_to_create (list[EntityToCreate]) – A list of the entities to create

  • _request_options (RequestOptions | None)

Return type:

Data

create_entity(*, entity_type, definition_id=None, definition_key=None, field_values=None, parent_entity=None, _request_options=None)

Creates a single new entity of a specified type within a definition. Returns the created entity’s ID and type.

Parameters:

  • definition_id (ObjectId | None) – Definition id of the entity to create

  • definition_key (IdentifierKey | None) – Key for the definition of the entity to create

  • entity_type (LimitedEntityType) – The type of the entities requested

  • parent_entity (Entity | None) – The parent entity associated for this new entity. This only applies if there is a pre-defined relationship.

  • field_values (list[FieldRefNameValue] | None)

  • _request_options (RequestOptions | None)

Return type:

Data

create_mix_order(*, recipe_key, recipe_workflow_step_identifier, _request_options=None)

Creates a mix order on a recipe workflow step. The recipe and workflow step are identified by their respective keys. Returns whether a modification was made.

Parameters:
Return type:

Data

create_or_update_entities(*, entity_type, definition_key, operations, _request_options=None)

Bulk variant of create_or_update_entity scoped to a single (entity_type, definition_key) — accepts up to 100 operations sharing that scope and applies them via batched primitive calls (one permission check + one set_field_values across updates, one create_entities across creates). Returns one AsyncBatchActionReturn per input, in the same order. Cross-operation batch_reference dependencies are not supported.

Parameters:
Return type:

Data

create_or_update_entity(*, entity_type, definition_key, field_values, entity_key=None, on_create_init_field_values=None, _request_options=None)

Creates a new entity or updates an existing one. If the entity already exists, updates its field values. Otherwise, creates a new entity under the specified definition. Returns the entity ID and whether a modification was made.

Parameters:
Return type:

Data

create_recipe(*, material_family_id, workflow_id, name=None, project_id=None, workflow_variant_id=None, recipe_metadata=None, identifiers=None, definition_key=None, recipe_key=None, _request_options=None)

Creates a single recipe in the specified material family and workflow. If a matching recipe already exists, no new recipe is created and the existing recipe ID is returned. Returns the recipe ID.

Parameters:

  • name (str | None) – The name for the recipe

  • material_family_id (ObjectId) – The material family for the recipe

  • project_id (ObjectId | None) – The identifier of the project to create the recipe in

  • workflow_id (ObjectId) – The identifier of the workflow to create the recipe with

  • workflow_variant_id (ObjectId | None) – The identifier of the workflow variant to create the recipe with

  • recipe_metadata (list[MetadataValue] | None) – Metadata values to populate the recipe with

  • identifiers (RecipeIdentifiers | None) – [DEPRECATED] - use recipeKey. A recipe won’t be created if it matches the identifier. An identifier must be unique in the schema. An error will be raised if an argument is provided to both recipeKey and identifiers properties.

  • definition_key (IdentifierKey | None) – The entity definition identifier, default is used if not supplied

  • recipe_key (IdentifierKey | None) – If this identifier matches an existing recipe, the id of the existing recipe will be returned and no update will occur. Use the lookup_entity endpoint to match an existing recipe based on a set of field values.

  • _request_options (RequestOptions | None)

Return type:

Data

Creates a directional link between two recipes of the specified type (child, control, user_link, or previous_experiment). Skips without error if the link already exists. A name is required for child and user_link types; control and previous_experiment links do not accept a name. Returns whether a modification was made.

Parameters:

  • recipe_from_key (IdentifierKey) – Identifier for the recipe the link comes from

  • recipe_to_key (IdentifierKey) – Identifier for the recipe the link goes to

  • link_type (Literal[uncountable.types.recipe_links_t.RecipeLinkType.CHILD] | Literal[uncountable.types.recipe_links_t.RecipeLinkType.CONTROL] | Literal[uncountable.types.recipe_links_t.RecipeLinkType.USER_LINK] | Literal[uncountable.types.recipe_links_t.RecipeLinkType.PREVIOUS_EXPERIMENT]) – The type of link being created

  • name (str | None) – The name used for the link

  • _request_options (RequestOptions | None)

Return type:

Data

create_recipes(*, material_family_id, recipe_definitions, project_id=None, _request_options=None)

Creates multiple recipes in a material family, optionally with metadata values. Returns the created recipe IDs in corresponding order.

Parameters:

  • material_family_id (ObjectId) – The identifier of the material family to create the recipes in

  • project_id (ObjectId | None) – The identifier of the project to create the recipes in

  • recipe_definitions (list[CreateRecipeDefinition])

  • _request_options (RequestOptions | None)

Return type:

Data

disassociate_recipe_as_input(*, recipe_key, _request_options=None)

Removes the input (ingredient) association from a recipe. If the recipe is not currently associated as an input, this is a no-op. Returns whether a modification was made.

Parameters:
Return type:

Data

do_request(*, api_request, return_type)
Parameters:
Return type:

DT

download_files(*, file_query)

Download a file from uncountable.

Parameters:

file_query (FileDownloadQuery)

Return type:

DownloadedFiles

edit_recipe_inputs(*, recipe_key, recipe_workflow_step_identifier, edits, _request_options=None)

Applies a list of edits to inputs on a specific recipe workflow step. Supported edit types include clearing all inputs, upserting or adding inputs, updating annotations, setting lots, setting propagated percentages, changing basis, adding instructions, setting roles, and managing placeholders.

Parameters:
Return type:

Data

execute_batch(*, requests, _request_options=None)

Execute multiple API calls in a single synchronous request. Each sub-request is validated upfront (endpoint must exist, have no URL parameters, and not be the batch endpoint itself), then executed sequentially. If one sub-request fails, subsequent requests in the same batch will not be executed. Maximum of 10 requests per batch. Returns the status code and response body for each sub-request.

Parameters:
Return type:

Data

execute_batch_load_async(*, requests, _request_options=None)

Queue multiple API calls for asynchronous execution. Requests are executed in topological order based on dependsOn relationships — only this ordering is guaranteed. Do not assume any ordering for requests without dependsOn. Detects cycles and unknown dependency references. Returns a job_id for tracking the async job status.

Parameters:
Return type:

Data

export_default_runsheet(*, entities, entity_type=entity_t.EntityType.RECIPE, runsheet_key, _request_options=None)

Generates a default runsheet document for the specified entities using a runsheet definition. Resolves entities and the runsheet definition by their identifier keys. Does not support async (webhook-based) runsheets. Returns the created text document ID for file download and metadata about the generated runsheet columns and formatting. Defaults to Recipe entity type if not specified.

Parameters:

  • entities (list[IdentifierKey]) – List of identifiers for entities to include in the runsheet export

  • entity_type (EntityType) – Type of entities to include in the runsheet export. Defaults to Recipe if not provided.

  • runsheet_key (IdentifierKey) – Identifier key for the runsheet definition to use for export

  • _request_options (RequestOptions | None)

Return type:

Data

export_entities(*, config_key, type=exports_t.ExportType.EXCEL, client_timezone=None, limit=None, attributes=None, _request_options=None)

Queues an asynchronous export of entities using a structured loading configuration. Fails if the export would return more than 1 million rows. Returns an async job ID that can be used to poll for export completion.

Parameters:
Return type:

Data

export_listing(*, entity_type, columns, filters=None, _request_options=None)

Queues an asynchronous listing export for the given entity type with structured columns and filters. Returns an async job entity that can be polled for completion. Columns are limited to a maximum transitive depth of 3. Filters are limited to a maximum array length of 100. Exports in JSON format.

Parameters:

  • entity_type (EntityType) – The entity type to fetch listing entries for

  • columns (list[ColumnIdentifier]) – The columns to include in the results

  • filters (FilterNode | None) – Structured filters to apply to the listing, represented by a FilterNode object

  • _request_options (RequestOptions | None)

Return type:

Data

external_add_time_series_data(*, time_series_segment_key, time_series_data, on_conflict=add_time_series_data_t.OnTimepointConflict.ERROR, _request_options=None)

Adds timestamp-value data points to a time series segment identified by key. Supports configurable conflict resolution when a data point already exists at the same timestamp: either overwrite the existing value or raise an error. Returns whether a modification was made.

Parameters:

  • time_series_segment_key (IdentifierKey) – The time series segment to add data to

  • time_series_data (list[TimeSeriesDatum]) – The data to add to the time series segment

  • on_conflict (OnTimepointConflict) – What to do if a TimeSeriesDatum already exists at the same timestamp

  • _request_options (RequestOptions | None)

Return type:

Data

external_create_inputs(*, inputs_to_create, _request_options=None)

Creates new inputs (ingredients or process parameters) in the specified material families. Each input must belong to at least one material family. Optionally sets attribute values, a category, and field values on creation.

Parameters:
Return type:

Data

external_lock_entity(*, entity_key, entity_type, globally_removable=None, _request_options=None)

Locks an entity to prevent modifications. Recipe entity types are not supported and must use the dedicated lock_recipes endpoint instead. Attempting to lock an already locked entity is a no-op.

Parameters:

  • entity_key (IdentifierKey) – Identifier for the entity

  • globally_removable (bool | None) – Should the lock be removable by any user or just admins

  • entity_type (EntityType)

  • _request_options (RequestOptions | None)

Return type:

Data

external_set_input_category(*, input_key, category_id, material_family_ids=None, _request_options=None)

Sets or unsets the global category for an input within its material families. Pass a category_id to assign a category, or null to remove the current category. Optionally scope the update to specific material families via material_family_ids; if omitted, updates across all material families the input belongs to. Validates that the category exists. Requires SET_FIELD_VALUE access on the input entity.

Parameters:

  • input_key (IdentifierKey) – Identifier for the input

  • category_id (int | None) – The category identifier to set. Null unsets the current category.

  • material_family_ids (list[int] | None) – The material families to perform the update in

  • _request_options (RequestOptions | None)

Return type:

Data

external_set_input_subcategories(*, input_key, subcategory_ids, update_type, _request_options=None)

Modifies the subcategory (tag) assignments for an input. Supports three update types: ‘append’ adds the specified subcategories without removing existing ones, ‘override’ replaces all subcategories with the specified set (archiving any not in the list), and ‘remove’ archives only the specified subcategories. Requires SET_FIELD_VALUE access on the input entity.

Parameters:

  • input_key (IdentifierKey) – Identifier for the input

  • subcategory_ids (list[int]) – The subcategory identifiers to set

  • update_type (UpdateType) – The type of update to perform

  • _request_options (RequestOptions | None)

Return type:

Data

external_unlock_entity(*, entity_key, entity_type, _request_options=None)

Removes the lock from an entity, allowing modifications again. Recipe entity types are not supported and must use the dedicated unlock_recipes endpoint instead. Attempting to unlock an already unlocked entity is a no-op.

Parameters:
Return type:

Data

fetch_listing(*, entity_type, columns, filters=None, limit=None, offset=None, _request_options=None)

Fetches listing rows for the given entity type with structured columns and filters, returned synchronously. Supports pagination via limit/offset. Columns are limited to a maximum transitive depth of 3. Filters are limited to a maximum array length of 50. At least one column must be specified. Results are returned with column values in the same order as the requested columns.

Parameters:

  • entity_type (EntityType) – The entity type to fetch listing entries for

  • columns (list[ColumnIdentifier]) – The columns to include in the results

  • filters (FilterNode | None) – Structured filters to apply to the listing, represented by a FilterNode object

  • limit (int | None) – The number of entries to return. If not provided, defaults to 100. Note a maximum of 100 entries can be returned.

  • offset (int | None) – The number of entries to skip for pagination

  • _request_options (RequestOptions | None)

Return type:

Data

get_column_calculation_values(*, recipe_keys, calculation_key, _request_options=None)

Retrieves the computed values for a single column calculation across multiple recipes. Returns the calculation quantity for each recipe, along with the associated recipe step, recipe input, and ingredient IDs.

Parameters:

  • recipe_keys (list[IdentifierKey]) – Required: The recipe keys to load values for

  • calculation_key (IdentifierKey) – Required: The calculation key to get the values for

  • _request_options (RequestOptions | None)

Return type:

Data

get_current_user_info(*, _request_options=None)

Returns the user ID of the currently authenticated user. Requires a valid authenticated session. Takes no arguments.

Parameters:

_request_options (RequestOptions | None)

Return type:

Data

get_curve(*, recipe_output_id=None, recipe_input_id=None, _request_options=None)

Returns the x and y curve data for a recipe output or recipe input. Exactly one target (output or input) must be specified. Returns the curve values sorted by index.

Parameters:

  • recipe_output_id (ObjectId | None) – The recipe output ID to fetch the curve for. This must be a curve recipe output. Recipe Outputs can be found from external_get_recipes_data

  • recipe_input_id (ObjectId | None) – The recipe input ID to fetch the curve for. This must be a curve recipe input. Recipe Inputs can be found from external_get_recipes_data

  • _request_options (RequestOptions | None)

Return type:

Data

get_entities_data(*, entity_ids, entity_type, _request_options=None)

Retrieves field values for entities of the same type. All requested entities must share the same entity type.

Parameters:

  • entity_ids (list[ObjectId]) – Ids of the entity to retrieve

  • entity_type (EntityType) – The type of the entities requested, e.g. lab_request or approval

  • _request_options (RequestOptions | None)

Return type:

Data

get_input_data(*, material_family_id, input_ids, is_parameter, offset=None, limit=None, _request_options=None)

Returns detailed metadata for inputs (ingredients and/or process parameters) in a material family, including attribute values, global category assignments, and subcategory (tag) assignments. Can filter by specific input IDs or by type (ingredient vs parameter). Excludes archived inputs. Paginated with a default and maximum limit of 1,000 results, ordered by input ID.

Parameters:

  • material_family_id (ObjectId) – The material family ID to get the input values from.

  • input_ids (list[ObjectId] | None) – The input IDs to get the data from. If this is not filled in, all inputs from a material family will be returned (in paginated form).

  • offset (int | None) – Used for pagination, where the number of results returned exceeds the limit. Results are always ordered by the input ID. [Pagination More Info](#pagination)

  • is_parameter (bool | None) – Whether to get parameters or ingredients. By default both are returned. When set to true, only parameters are returned, and when set to false, only ingredients are returned

  • limit (int | None) – The maximum number of results to return. By default this is set to 1,000 and it cannot be set higher than 1,000. [Pagination More Info](#pagination)

  • _request_options (RequestOptions | None)

Return type:

Data

get_input_group_names(*, material_family_id, _request_options=None)

Returns the ID and name of all input groups in a material family that are either owned by the requesting user or shared globally (no owner). Results are ordered by input group ID.

Parameters:

  • material_family_id (ObjectId) – Required: The Material Family ID to get the input groups from.

  • _request_options (RequestOptions | None)

Return type:

Data

get_input_names(*, material_family_id, is_parameter, offset=None, limit=None, _request_options=None)

Returns the ID and name of all non-archived inputs (ingredients and/or process parameters) in a material family. Can filter by type (ingredient vs parameter) using is_parameter. Paginated with a default and maximum limit of 20,000 results, ordered by input ID.

Parameters:

  • material_family_id (ObjectId) – The material family ID to get the input values from

  • offset (int | None) – Used for pagination, where the number of results returned exceeds the limit. Results are always ordered by the input ID. [Pagination More Info](#pagination)

  • is_parameter (bool | None) – Whether to get parameters or ingredients. By default both are returned. When set to true, only parameters are returned, and when set to false, only ingredients are returned

  • limit (int | None) – The maximum number of results to return. By default this is set to 20,000 and it cannot be set higher than 20,000. [Pagination More Info](#pagination)

  • _request_options (RequestOptions | None)

Return type:

Data

get_inputs_data(*, input_ids, _request_options=None)

Returns detailed metadata for a list of inputs by their IDs, including attribute values, categories per material family, and subcategory tags. Also returns attribute definitions (name and quantity type) for all referenced attributes.

Parameters:
Return type:

Data

get_notebook_content(*, notebook_key, _request_options=None)

Retrieves the structured content of a notebook by identifier key. Only exportable cell types are included: HTML text, tables (with text or image cells and optional styling), chemical structures (MOL 3000 or RXN 3000 format), equations, files, images, and reaction tables. Non-exportable cell types (charts, graphs, dashboards) and cells marked as excluded from export are omitted. Chemical structures that fail to convert are returned as chemical_structure_error entries with an error message.

Parameters:
Return type:

Data

get_output_data(*, material_family_id, output_ids=None, offset=None, limit=None, _request_options=None)

Returns detailed metadata for outputs in a material family, including quantity type, global category assignments, and associated units. Can filter by specific output IDs. Excludes archived outputs. Paginated with a default and maximum limit of 1,000 results, ordered by output ID. Also returns referenced global category and unit definitions.

Parameters:

  • material_family_id (ObjectId) – The material family ID to get the output values from.

  • output_ids (list[ObjectId] | None) – The output IDs to get the data from. If this is not filled in, all outputs from a material family will be returned (in paginated form).

  • offset (int | None) – Used for pagination, where the number of results returned exceeds the limit. Results are always ordered by the output ID. [Pagination More Info](#pagination)

  • limit (int | None) – The maximum number of results to return. By default this is set to 1,000 and it cannot be set higher than 1,000. [Pagination More Info](#pagination)

  • _request_options (RequestOptions | None)

Return type:

Data

get_output_names(*, material_family_id, offset=None, limit=None, _request_options=None)

Returns the ID and name of all non-archived outputs in a material family. Outputs represent measurement values of any type (numeric, text, curve, calculation, etc.). Paginated with a default and maximum limit of 20,000 results, ordered by output ID.

Parameters:

  • material_family_id (ObjectId) – The material family ID to get the output values from

  • offset (int | None) – Used for pagination, where the number of results returned exceeds the limit. Results are always ordered by the output ID. [Pagination More Info](#pagination)

  • limit (int | None) – The maximum number of results to return. By default this is set to 20,000 and it cannot be set higher than 20,000. [Pagination More Info](#pagination)

  • _request_options (RequestOptions | None)

Return type:

Data

get_output_organization(*, request, _request_options=None)

Returns the output organization configuration (column and table definitions) for a given scope: material family, project, or user. Organization parameters define how outputs are grouped and sorted, and can be based on category, recipe input, or condition parameter.

Parameters:
Return type:

Data

get_projects(*, all_material_families, material_family_id, _request_options=None)

Lists non-archived projects the user has permission to access, optionally filtered by material family ID. Requires either allMaterialFamilies=true or a specific materialFamilyId; returns 400 if neither is set. Returns projects ordered by ID along with their associated phase definitions. Projects represent groupings of experiments, similar to folders in a directory structure.

Parameters:

  • all_material_families (bool) – Whether to get projects from all material families. Material families are high level groupings of data, usually separated by functional area

  • material_family_id (ObjectId | None) – The specific material family ID to get projects from. Only fill this in if all_material_families is set to false

  • _request_options (RequestOptions | None)

Return type:

Data

get_projects_data(*, project_ids, offset=None, limit=None, _request_options=None)

Retrieves detailed data for a set of projects, including field values, phase definitions, and field metadata. Paginated to limit response size.

Parameters:

  • project_ids (list[ObjectId]) – The projects to get the data from

  • offset (int | None) – Used for pagination. All pagination is done in order of Project ID. [Pagination More Info](#pagination)

  • limit (int | None) – The number of data points to return. If not filled in, it will be set to 100, and cannot be set higher than 100. [Pagination More Info](#pagination)

  • _request_options (RequestOptions | None)

Return type:

Data

get_recipe_calculations(*, recipe_ids, calculation_ids=None, _request_options=None)

Retrieves calculation values for the specified recipes. When specific calculations are requested, they are computed on-the-fly. Otherwise, not all calculations may be returned. Returns both the per-recipe calculation values and the calculation definitions.

Parameters:

  • recipe_ids (list[ObjectId]) – Ids of the Recipes to retrieve calculations for

  • calculation_ids (list[ObjectId] | None) – Optional list of calculation IDs to compute and retrieve. When omitted, not all calculations may be returned.

  • _request_options (RequestOptions | None)

Return type:

Data

Retrieves links between recipes, traversing up to the specified depth with a maximum depth of 20. Only returns immediate links at each traversal level. Optionally filters by link type. Results are limited to 500 links total; fails if this limit is exceeded.

Parameters:

  • recipe_ids (list[ObjectId]) – Ids of the Recipes to retrieve links for

  • depth (int) – How many layers deep to look for links

  • link_types (list[RecipeLinkType] | None) – Optional filter to only desired link types

  • _request_options (RequestOptions | None)

Return type:

Data

get_recipe_metadata_data(*, material_family_id, recipe_metadata_ids, offset=None, limit=None, _request_options=None)

Retrieves recipe metadata field definitions for a material family. Recipe metadata represents data associated with experiments that is not an input, output, or calculation (e.g. sample ID, location). Results are paginated with a default and maximum limit of 1000, ordered by metadata field ID. Optionally filters to specific metadata IDs.

Parameters:

  • material_family_id (ObjectId) – The material family ID to get the recipe metadata values from.

  • recipe_metadata_ids (list[ObjectId] | None) – The recipe metadata IDs to get the data from. If this is not filled in, all metadata from a material family will be returned (in paginated form).

  • offset (int | None) – Used for pagination, where the number of results returned exceeds the limit. Results are always ordered by the metadata ID. [Pagination More Info](#pagination)

  • limit (int | None) – The maximum number of results to return. By default this is set to 1,000 and it cannot be set higher than 1,000. [Pagination More Info](#pagination)

  • _request_options (RequestOptions | None)

Return type:

Data

get_recipe_names(*, project_id, _request_options=None)

Returns the ID and name of all non-archived recipes in the specified project, ordered by recipe ID. Archived recipes are excluded from the results.

Parameters:

  • project_id (ObjectId) – Required: The project ID to get the recipes/experiments from.

  • _request_options (RequestOptions | None)

Return type:

Data

get_recipe_output_metadata(*, recipe_output_ids, _request_options=None)

Retrieves metadata values and their field definitions for the specified recipe outputs. Accepts at most 500 recipe output IDs. Returns metadata values (numeric or JSON) along with the non-archived metadata field definitions.

Parameters:

  • recipe_output_ids (list[ObjectId]) – Ids of the Recipe Outputs to retrieve metadata for

  • _request_options (RequestOptions | None)

Return type:

Data

get_recipes_data(*, recipe_ids=None, project_id=None, offset=None, limit=None, empty_output_behavior=None, _request_options=None)

Retrieves all data associated with a set of recipes, including inputs, outputs, metadata, workflow steps, step relationships, tags, experiment groups, and lock status. Recipes can be specified individually or by project. Paginated by recipe ID.

Parameters:

  • recipe_ids (list[ObjectId] | None) – The recipes to get the data from. Either these or project_id must be filled in

  • project_id (ObjectId | None) – The projects to get the data from. Either these or recipe_ids must be filled in

  • offset (int | None) – Used for pagination. All pagination is done in order of Recipe ID. [Pagination More Info](#pagination)

  • limit (int | None) – The number of data points to return. If not filled in, it will be set to 100, and cannot be set higher than 100. [Pagination More Info](#pagination)

  • empty_output_behavior (RecipeOutputInclusion | None) – Recipe output inclusion behavior for empty outputs. Empty recipe outputs are outputs added to the experiment that do not have a value associated with them.

  • _request_options (RequestOptions | None)

Return type:

Data

grant_entity_permissions(*, entity_type, entity_key, permission_types, user_keys=None, user_group_keys=None, all_users=None, _request_options=None)

Grants permissions on an entity. Only permissions that do not already exist are added. Returns whether any new permissions were granted.

Parameters:
Return type:

Data

invoke_uploader(*, uploader_key, destination, file_id=None, file_ids=None, _request_options=None)

Processes one or more uploaded files through a configured uploader, parsing and writing the extracted data to a recipe destination. Resolves the uploader by its identifier key and requires READ_ALL permission on the uploader entity. The file_ids parameter is preferred; file_id is deprecated. Non-SDK users should use file_upload/external_create_file_record to upload files first. SDK users can use the client.upload_files() helper method. Supports async batch execution.

Parameters:
Return type:

Data

list_aggregate(*, config_reference, attribute_values=None, offset=None, limit=None, _request_options=None)

Queries aggregated data using a structured loading configuration. The referenced configuration must be an aggregation listing. Returns column metadata and aggregated row results.

Parameters:

  • config_reference (str) – The configuration reference name for the listing config

  • attribute_values (list[AttributeValue] | None) – Attributes to pass to the configuration for parameterizing filters

  • offset (int | None) – Used for pagination. Pagination is done based on the sorting of the config. [Pagination More Info](#pagination)

  • limit (int | None) – The number of data points to return. If not filled in, it will be set to 100, and cannot be set higher than 100. [Pagination More Info](#pagination)

  • _request_options (RequestOptions | None)

Return type:

Data

list_entities(*, config_reference, entity_type=None, attributes=None, offset=None, limit=None, additional_filter_configs=None, _request_options=None)

Lists entities using a structured loading configuration. Returns column metadata and entity results with their column values.

Parameters:

  • entity_type (EntityType | None) – DEPRECATED: The type of the entities requested, e.g. lab_request, recipe

  • config_reference (str) – The configuration reference name for the listing config

  • attributes (dict[pkgs.serialization.OpaqueKey, JsonValue] | None) – Attributes to pass to the configuration for parameterizing filters

  • offset (int | None) – Used for pagination. Pagination is done based on the sorting of the config. [Pagination More Info](#pagination)

  • limit (int | None) – The number of data points to return. If not filled in, it will be set to 100, and cannot be set higher than 100. [Pagination More Info](#pagination)

  • additional_filter_configs (list[AdditionalFilterConfig] | None) – Advanced property: Additional filter configurations to apply to the listing. A maximum of 10 additional filter configs are supported.

  • _request_options (RequestOptions | None)

Return type:

Data

list_id_source(*, spec, search_label, offset=None, limit=None, _request_options=None)

List id and label pairs for a given id source spec. Supports pagination via offset and limit and text search filtering via search_label.

Parameters:

  • spec (IdSourceSpec) – The id source spec to use

  • search_label (str) – Text to search within the labels to search matches

  • offset (int | None) – Used for pagination. Pagination is done based on the sorting of the config. [Pagination More Info](#pagination)

  • limit (int | None) – The number of data points to return. If not filled in, it will be set to 100, and cannot be set higher than 100. [Pagination More Info](#pagination)

  • _request_options (RequestOptions | None)

Return type:

Data

lock_recipes(*, type=lock_recipes_t.RecipeLockType.ALL, recipes, globally_removable, lock_samples=None, comments=None, _request_options=None)

Locks experiments to prevent editing. Supports locking all data (inputs and measurements) or inputs only. Returns whether a modification was made.

param type:

The type of lock to set.

All = both inputs and measurements are locked. Inputs Only = only inputs are locked from editing.

param recipes:

The recipes to lock, a maximum of 100 can be sent

param globally_removable:

If true any user can unlock the experiment. If false the locking user is the only user that can unlock.

param lock_samples:

Should associated experiment test samples also be locked.

param comments:

Optional comment describing the purpose of locking

Parameters:
Return type:

Data

lookup_entity(*, entity_type, query, _request_options=None)

Looks up an entity by matching field values. Only text and ID field types are supported for matching. Returns the matched entity ID, or null if no match is found. Fails if multiple entities match. Excludes archived entities from results.

Parameters:
Return type:

Data

match_id_source(*, spec, names, _request_options=None)

Match names to IDs using a given id source spec. Performs a reverse lookup, returning all matching IDs for each provided name. Accepts at most 10 names per request.

Parameters:

  • spec (IdSourceSpec) – The id source spec to use

  • names (list[str]) – The names to match with the id source. At most 10 are allowed at a time

  • _request_options (RequestOptions | None)

Return type:

Data

modify_file_system(*, operation, _request_options=None)

Perform file system operations on folders. Currently supports upsert_folder which creates a new folder or updates an existing one (name, type, and parent folder). When updating, the folder can be reparented by specifying a different parent_folder_key.

Parameters:
Return type:

Data

publish_realtime_data(*, data_package, _request_options=None)

Publish a numeric reading for a realtime instrument integration. Currently only supports equipment entities. Resolves the target equipment via identifier key. Returns the integration session details and status. API is in beta — contact Uncountable for realtime integration guidance.

Parameters:
Return type:

Data

push_notification(*, notification_targets, subject, message, display_notice=False, entity=None, notice_configuration=None, _request_options=None)

Send a notification to one or more users or user groups. Supports specifying a subject, message body, and optional entity link. Can optionally display as an in-app notice with custom configuration. Supports both direct invocation and async batch execution.

Parameters:
Return type:

Data

register_sockets_token(*, socket_request, _request_options=None)

Register a connection token for an integration session. Currently supports instrument integration sessions targeting equipment entities. Enforces a per-user token limit. Returns a token UUID and room key for connecting to the realtime server.

Parameters:
Return type:

Data

remove_recipe_from_project(*, recipe_key, project_key, _request_options=None)

Removes a recipe from a project.

Parameters:

  • recipe_key (IdentifierKey) – The identifier key of the recipe to remove from the project

  • project_key (IdentifierKey) – The identifier key of the project to remove the recipe from

  • _request_options (RequestOptions | None)

Return type:

Data

Removes a directional link between two recipes of the specified type (child, control, user_link, or previous_experiment). If the link does not exist, the action is a no-op. Returns whether a modification was made.

Parameters:

  • recipe_from_key (IdentifierKey) – Identifier for the recipe the link comes from

  • recipe_to_key (IdentifierKey) – Identifier for the recipe the link goes to

  • link_type (Literal[uncountable.types.recipe_links_t.RecipeLinkType.CHILD] | Literal[uncountable.types.recipe_links_t.RecipeLinkType.CONTROL] | Literal[uncountable.types.recipe_links_t.RecipeLinkType.USER_LINK] | Literal[uncountable.types.recipe_links_t.RecipeLinkType.PREVIOUS_EXPERIMENT]) – The type of link being removed

  • _request_options (RequestOptions | None)

Return type:

Data

resolve_entity_ids(*, entity_ids, entity_type, _request_options=None)

Resolves entity IDs to their display names. All requested entities must share the same entity type.

Parameters:

  • entity_ids (list[str | ObjectId]) – Ids of the entity to retrieve

  • entity_type (EntityType) – The type of the entities requested

  • _request_options (RequestOptions | None)

Return type:

Data

resolve_output_conditions(*, requested_conditions, _request_options=None)

Resolves sets of condition parameter values to output condition IDs, creating new output conditions if they do not already exist. Each condition request contains a list of condition parameter ID and value pairs. Validates that all condition parameter IDs exist, that each value matches the parameter’s quantity type (numeric vs string), and that exactly one of value_numeric or value_string is provided per parameter. Requires READ_ALL access on all referenced condition parameter entities. Returns resolved output condition IDs in the same order as the request.

Parameters:
Return type:

Data

run_trigger(*, trigger_ref_name, entity_identifier=None, entity=None, _request_options=None)

Executes a trigger script identified by ref name, optionally on a specific entity, and returns only after the trigger has fully completed. Requires admin user access; non-admin users receive a 403 error. Accepts either entity_identifier (preferred) or entity (deprecated) to specify the target entity, but not both. Returns whether any entities were modified by the trigger execution.

Parameters:

  • entity_identifier (EntityIdentifier | None) – Identifier of the entity to run the trigger on.

  • entity (Entity | None) – [Deprecated: use entity_identifier] Entity to run the trigger on.

  • trigger_ref_name (str)

  • _request_options (RequestOptions | None)

Return type:

Data

set_barcode(*, entity_key, barcode_value, _request_options=None)

Sets the barcode value for an entity. Returns whether the new barcode value was set.

Parameters:
Return type:

Data

set_core_permissions(*, scope, permissions_types, update_type, user_group_ids=None, user_ids=None, _request_options=None)

Grants, removes, or replaces core permissions for users or user groups at a specified scope. Scopes include: all_material_families, material_family, project, or recipe. Project and recipe scopes only support recipe-related permission types (read/write recipe, add recipe). Material family scopes do not accept individual user permissions (only user groups). Requires at least one user_id or user_group_id. Update types: ‘append’ grants the specified permissions (with implied permissions), ‘remove’ revokes them (including dependent permissions), ‘override’ replaces all permissions at the scope with the specified set.

Parameters:

  • scope (PermissionsScope) – Scope of permissions to change

  • user_group_ids (list[int] | None) – User group ids to grant permission to

  • user_ids (list[int] | None) – User ids to grant permission to

  • update_type (UpdateType) – The type of update to perform

  • permissions_types (list[CorePermissionType])

  • _request_options (RequestOptions | None)

Return type:

Data

set_entities_field_values(*, entity_type, operations, _request_options=None)

Bulk variant of set_entity_field_values scoped to a single entity_type — accepts up to 100 (identifier_key, field_values) operations sharing that scope and applies them via batched primitive calls (one entity-resolution round-trip, one check_entity_list_permitted, one set_field_values across the aggregate). Returns one AsyncBatchActionReturn per input, in the same order. Cross-operation batch_reference dependencies are not supported.

Parameters:
Return type:

Data

set_entity_field_values(*, entity_identifier, field_values, _request_options=None)

Sets field values on an entity. Returns whether the field values were modified.

Parameters:
Return type:

Data

set_entity_permission(*, entity_type, entity_key, update_type, permission_updates, _request_options=None)

Sets entity-level permissions (read, write, admin) on a specific entity for users or user groups. Currently supports file_folder_membership entities. Update types: ‘append’ grants the requested level if higher than existing, ‘remove’ revokes the specified level and downgrades to the level below (e.g., removing write leaves read), ‘override’ replaces all permissions with the specified set. Each user or user group may only appear once in the request. The caller cannot modify their own permissions. Requires SET_FIELD_VALUE access on the target entity. Returns whether any modification was made.

Parameters:

  • entity_type (PermissionEntityType) – The type of entity to set permissions on

  • entity_key (IdentifierKey) – The identifier of the entity to set permissions on

  • update_type (UpdateType) – Append - grants permission if higher than existing. Remove - revokes specified level, keeping lower levels (e.g., ‘write’ → ‘read’). Specified level must be at or below existing. Override - replaces all permissions.

  • permission_updates (list[PermissionUpdate]) – List of permission updates

  • _request_options (RequestOptions | None)

Return type:

Data

set_input_attribute_values(*, attribute_values, _request_options=None)

Sets attribute values on one or more inputs. Supports numeric, categorical/text, and PDF file attributes. For PDF attributes, provide exactly one file_id referencing a previously uploaded file; use create_file_record to obtain a file_id. Each (input_id, attribute_id) pair may only appear once in the request. Validates that each attribute ID exists and that the provided value type matches the attribute’s quantity type.

Parameters:
Return type:

Data

set_intermediate_type(*, input_key, intermediate_type, _request_options=None)

Sets whether an intermediate ingredient is treated as a final product or as a compound-as-intermediate. Setting to ‘compound_as_intermediate’ enables compound-as-intermediate behavior; setting to ‘final_product’ disables it. Requires SET_FIELD_VALUE access on the input entity.

Parameters:
Return type:

Data

set_recipe_inputs(*, input_data, _request_options=None)

Sets input values for experiments. Supports numeric, text, and categorical types. Validates that the recipe step belongs to the correct recipe. Supports setting actual values, associating lots (creating them if needed), and removing inputs. Writes all values to the first workflow step when no step is specified. Fails if both a numeric and string value are provided.

Parameters:
Return type:

Data

set_recipe_metadata(*, recipe_key, recipe_metadata, _request_options=None)

Sets metadata values on a recipe identified by key. Accepts a list of metadata field-value pairs to populate on the recipe. Fails if any of the metadata fields are read-only.

Parameters:
Return type:

Data

set_recipe_output_annotations(*, updates, _request_options=None)

Updates annotations on experiment outputs. Supports two modes per update - merge (adds annotations alongside existing ones) or replace (clears existing annotations first).

Parameters:
Return type:

Data

set_recipe_output_file(*, output_file_data, _request_options=None)

Sets a file or image output value for an experiment. The file can be provided either as a single file in the multipart FormData or via a previously uploaded file ID. Use create_file_record to obtain a file ID. The output must be of type file or image. Fails if the output is not of file/image type or no file is provided.

Parameters:
Return type:

Data

set_recipe_outputs(*, output_data, _request_options=None)

Sets output measurement values for experiments. Supports numeric, text, categorical, curve, color, and recipe-as-output types. Fails if both a numeric and string value are provided. Experiment number must be 1 or greater. Use resolve_output_conditions to obtain a condition ID when setting conditioned outputs. Supports configurable null behavior (do nothing, ensure output exists, or remove the output row).

Parameters:
Return type:

Data

set_recipe_tags(*, recipe_key, recipe_tag_update, _request_options=None)

Modifies tags on a recipe identified by key. Supports three update modes - append (adds tags to existing ones), override (replaces all tags with the provided set), or remove (removes the specified tags).

Parameters:
Return type:

Data

set_recipe_total(*, recipe_key, value, recipe_workflow_step_identifier=None, calculation_key=None, _request_options=None)

Sets the total quantity value in a given quantity basis for a recipe or a specific workflow step within it. Optionally associates a linked basis calculation. Returns whether a modification was made.

Parameters:
Return type:

Data

set_values(*, entity, values, _request_options=None)

Sets field values on an entity. Returns an empty response on success.

Parameters:
Return type:

Data

swap_output_condition_parameters(*, scope, output_key, new_condition, old_condition_key=None, _request_options=None)

Swap output condition parameters on recipes. Either specify recipe keys for targeted swaps or set swap_all to swap across all recipes in the project.

Parameters:

  • scope (SwapScope) – Which recipes to apply the swap to. See SwapScope variants for options.

  • output_key (IdentifierKey) – Identifier for the output on which to swap conditions.

  • old_condition_key (IdentifierKey | None) – Identifier for the old condition to replace. If omitted, recipes without a condition on the output are targeted.

  • new_condition (NewOutputCondition) – The new output condition to swap to. See NewOutputCondition variants for options.

  • _request_options (RequestOptions | None)

Return type:

Data

transition_entity_phase(*, transition, entity=None, entity_identifier=None, _request_options=None)

Transitions an entity from one workflow phase to another. Fails if no valid transition exists between the specified phases, or if multiple transitions exist for the same phase pair.

Parameters:

  • entity (Entity | None) – Entity to transition. If entity_identifier is provided, this should be omitted.

  • entity_identifier (EntityIdentifier | None) – Identifier of the entity to transition. If entity is provided, this should be omitted.

  • transition (TransitionIdentifier) – Identifier of the transition to perform

  • _request_options (RequestOptions | None)

Return type:

Data

unarchive_recipes(*, recipes, _request_options=None)

Restores previously archived recipes, making them active again. Fails if any of the recipes are locked.

Parameters:
Return type:

Data

unlock_recipes(*, type=unlock_recipes_t.RecipeUnlockType.STANDARD, recipes, unlock_samples=None, _request_options=None)

Unlocks previously locked experiments, making them editable again. Returns whether a modification was made.

Parameters:

  • type (RecipeUnlockType) – The method to unlock recipes. Default is standard.

  • recipes (list[IdentifierKey]) – The recipes to unlock, a maximum of 100 can be sent

  • unlock_samples (bool | None) – Should associated experiment test samples also be unlocked.

  • _request_options (RequestOptions | None)

Return type:

Data

update_entity_material_families(*, entity_key, entity_type, material_family_ids, update_type, _request_options=None)

Update the material family assignments for an entity. Use update_type to append, override, or remove material family associations. Prevents removing all material families from an entity.

Parameters:

  • entity_key (IdentifierKey) – The identifier for the entity to update across material families

  • entity_type (Literal[uncountable.types.entity_t.EntityType.RECIPE_METADATA] | Literal[uncountable.types.entity_t.EntityType.INGREDIENT] | Literal[uncountable.types.entity_t.EntityType.OUTPUT] | Literal[uncountable.types.entity_t.EntityType.CONDITION_PARAMETER] | Literal[uncountable.types.entity_t.EntityType.INGREDIENT_ATTRIBUTE] | Literal[uncountable.types.entity_t.EntityType.INGREDIENT_CATEGORY_ALL]) – The type of the entities requested

  • material_family_ids (list[ObjectId]) – The material families to update

  • update_type (UpdateType) – The type of update to make

  • _request_options (RequestOptions | None)

Return type:

Data

update_output_condition_parameter(*, output_key, condition_parameter_key, update_type, requirement_type=None, material_family_key=None, analytical_method_keys=None, _request_options=None)

Adds, updates, or removes a condition parameter assignment on an output. Use update_type ‘append’ to add or update the requirement level (none, required, warning, prompt) for a condition parameter on the output; requirement_type is required for append. Use ‘remove’ to delete the condition parameter association. ‘override’ is not supported. Optionally scope to a specific material family; if omitted, creates a global setting. Resolves output, condition parameter, and material family via identifier keys.

Parameters:

  • output_key (IdentifierKey) – The output to update condition parameter settings for

  • condition_parameter_key (IdentifierKey) – The condition parameter to add, update, or remove

  • update_type (UpdateType) – Use “append” to add or update, “remove” to delete

  • requirement_type (ConditionParameterRequirementType | None) – The requirement level for the condition parameter. Required when update_type is “append”

  • material_family_key (IdentifierKey | None) – The material family context. If omitted, creates a global setting

  • analytical_method_keys (list[IdentifierKey] | None) – When update_type is “append”, sets the analytical methods for this condition parameter on the output. The provided list replaces the existing set of analytical methods.

  • _request_options (RequestOptions | None)

Return type:

Data

upload_files(*, file_uploads)

Upload files to uncountable, returning file ids that are usable with other SDK operations.

Parameters:

file_uploads (list[FileUpload])

Return type:

list[UploadedFile]

upsert_condition_match(*, explicit_name=False, name=None, condition_parameters=None, output_conditions=None, existing_condition_match=None, _request_options=None)

Creates or updates a condition match record. Condition matches are used to set goals on outputs. Each call creates a new condition match — there is no idempotent behavior, so the same inputs will produce a new condition match with each invocation. Returns modification_made and result_id of the created or updated condition match.

Parameters:
Return type:

Data

upsert_condition_matches(*, upserts, _request_options=None)

Bulk variant of upsert_condition_match. Accepts a list of upsert arguments and applies them via a single batched database round-trip per bulk operation (insert, update, delete) through the shared upsert_condition_matches helper. Returns one AsyncBatchActionReturn per input in the same order.

Parameters:
Return type:

Data

upsert_field_options(*, option_set_key, field_options, _request_options=None)

Create or update field options within an option set. The option_id field is what uniquely identifies each entry within the option set — provide the same option_id to update an existing option. Validates that no duplicate option_id values are provided within the request. Supports setting option labels, archived status, and subset assignments. Fields not provided on an existing option are left unchanged.

Parameters:
Return type:

Data

upsert_recipe_workflow_step(*, recipe_key, data_source, location, recipe_workflow_step_key=None, _request_options=None)

Create or update a recipe workflow step on a recipe

Parameters:
Return type:

Data

upsert_step_relationships(*, recipe_key, edits, _request_options=None)

Upsert step relationships on a recipe

Parameters:
Return type:

Data