Skip to content
Boltz Boltz Boltz API Docs
Go to Boltz API
API Reference
Small Molecule
Design

Estimate cost for a small molecule design run

small_molecule.design.estimate_cost(DesignEstimateCostParams**kwargs) -> DesignEstimateCostResponse
POST/compute/v1/small-molecule/design/estimate-cost

Estimate the billed cost of a small molecule design run without creating any resource or consuming GPU. Includes generation charges implied by the scheduler iteration cap plus structure-scoring charges for each requested molecule.

ParametersExpand Collapse
num_molecules: int

Number of molecules to generate. Must be between 10 and 1,000,000.

minimum10
maximum1000000
target: Target

Target protein sequences for small molecule design or screening.

entities: Iterable[TargetEntity]

Protein entities defining the target structure. Each entity represents a protein chain.

chain_ids: Sequence[str]

Chain IDs for this entity

type: Literal["protein"]
value: str

Amino acid sequence (one-letter codes)

cyclic: Optional[bool]

Whether the sequence is cyclic

modifications: Optional[Iterable[TargetEntityModification]]

CCD post-translational modifications. Optional; defaults to an empty list when omitted. SMILES modifications are not supported.

residue_index: int

0-based index of the residue to modify

minimum0
type: Literal["ccd"]

Modification format. Only CCD polymer modifications are supported.

value: str

CCD code from RCSB PDB (e.g. ‘MSE’ for selenomethionine, ‘SEP’ for phosphoserine)

bonds: Optional[Iterable[TargetBond]]

Covalent bond constraints between atoms in the target complex. Atom-level ligand references currently support ligand_ccd only; ligand_smiles is unsupported.

atom1: TargetBondAtom1

Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

One of the following:
class TargetBondAtom1LigandAtom: …

Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

atom_name: str

Standardized atom name (verifiable in CIF file on RCSB). Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

chain_id: str

Chain ID containing the atom

type: Literal["ligand_atom"]
class TargetBondAtom1PolymerAtom: …
atom_name: str

Standardized atom name (verifiable in CIF file on RCSB)

chain_id: str

Chain ID containing the atom

residue_index: int

0-based residue index

minimum0
type: Literal["polymer_atom"]
atom2: TargetBondAtom2

Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

One of the following:
class TargetBondAtom2LigandAtom: …

Ligand atom reference. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

atom_name: str

Standardized atom name (verifiable in CIF file on RCSB). Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

chain_id: str

Chain ID containing the atom

type: Literal["ligand_atom"]
class TargetBondAtom2PolymerAtom: …
atom_name: str

Standardized atom name (verifiable in CIF file on RCSB)

chain_id: str

Chain ID containing the atom

residue_index: int

0-based residue index

minimum0
type: Literal["polymer_atom"]
constraints: Optional[Iterable[TargetConstraint]]

Structural constraints (pocket and contact). Atom-level ligand references currently support ligand_ccd only; ligand_smiles is unsupported.

One of the following:
class TargetConstraintPocketConstraint: …

Constrains the binder to interact with specific pocket residues on the target.

binder_chain_id: str

Chain ID of the binder molecule

contact_residues: Dict[str, Iterable[int]]

Binding pocket residues keyed by chain ID. Each key is a chain ID (e.g. “A”) and the value is an array of 0-indexed residue indices that define the pocket on that chain.

max_distance_angstrom: float

Maximum allowed distance in Angstroms between binder and pocket residues. Typical range: 4-8 A.

type: Literal["pocket"]
force: Optional[bool]

Whether to force the constraint

class TargetConstraintContactConstraint: …

Contact constraint between two tokens. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

max_distance_angstrom: float

Maximum distance in Angstroms

token1: TargetConstraintContactConstraintToken1

Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

One of the following:
class TargetConstraintContactConstraintToken1PolymerContactToken: …
chain_id: str

Chain ID

residue_index: int

0-based residue index

minimum0
type: Literal["polymer_contact"]
class TargetConstraintContactConstraintToken1LigandContactToken: …

Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

atom_name: str

Atom name. Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

chain_id: str

Chain ID

type: Literal["ligand_contact"]
token2: TargetConstraintContactConstraintToken2

Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

One of the following:
class TargetConstraintContactConstraintToken2PolymerContactToken: …
chain_id: str

Chain ID

residue_index: int

0-based residue index

minimum0
type: Literal["polymer_contact"]
class TargetConstraintContactConstraintToken2LigandContactToken: …

Ligand contact token. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

atom_name: str

Atom name. Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

chain_id: str

Chain ID

type: Literal["ligand_contact"]
type: Literal["contact"]
force: Optional[bool]

Whether to force the constraint

pocket_residues: Optional[Dict[str, Iterable[int]]]

Binding pocket residues, keyed by chain ID. Each key is a chain ID (e.g. “A”) and the value is an array of 0-indexed residue indices that define the binding pocket on that chain. When provided, these residues guide pocket extraction and add a derived pocket constraint during affinity predictions. That derived constraint remains separate from any explicit pocket constraints in target.constraints. When omitted, the model auto-detects the pocket.

reference_ligands: Optional[Sequence[str]]

Reference ligands as SMILES strings that help the model identify the binding pocket. When omitted, a set of drug-like default ligands is used for pocket detection.

type: Optional[Literal["no_template"]]

Target is defined directly by protein sequences rather than a structure template.

chemical_space: Optional[Literal["enamine_real"]]

Chemical space to constrain generated molecules. Currently only ‘enamine_real’ (Enamine REAL chemical space) is supported. Additional options may be added in the future.

idempotency_key: Optional[str]

Client-provided key to prevent duplicate submissions on retries

maxLength255
molecule_filters: Optional[MoleculeFilters]

Molecule filtering configuration. Controls both Boltz built-in SMARTS filtering and custom filters.

boltz_smarts_catalog_filter_level: Optional[Literal["recommended", "extra", "aggressive", "disabled"]]

Controls the stringency of Boltz’s built-in SMARTS structural alert filtering, which removes molecules matching known problematic substructures. ‘recommended’ (default): applies a curated set of alerts balancing safety and hit rate. ‘extra’: adds additional alerts beyond the recommended set for stricter filtering. ‘aggressive’: applies the most comprehensive alert set — may reject viable molecules. ‘disabled’: turns off Boltz SMARTS filtering entirely; only custom_filters will be applied.

One of the following:
"recommended"
"extra"
"aggressive"
"disabled"
custom_filters: Optional[Iterable[MoleculeFiltersCustomFilter]]

Custom filters to apply. Molecules must pass all filters (AND logic).

One of the following:
class MoleculeFiltersCustomFilterLipinskiFilter: …

Lipinski’s Rule of Five filter. Rejects molecules that violate drug-likeness criteria based on molecular weight, LogP, hydrogen bond donors, and hydrogen bond acceptors.

max_hba: float

Maximum number of hydrogen bond acceptors. Lipinski threshold: 10

max_hbd: float

Maximum number of hydrogen bond donors. Lipinski threshold: 5

max_logp: float

Maximum LogP. Lipinski threshold: 5

max_mw: float

Maximum molecular weight (Da). Lipinski threshold: 500

type: Literal["lipinski_filter"]
allow_single_violation: Optional[bool]

If true, one rule violation is allowed (classic Rule of Five). Defaults to false (all rules must pass).

class MoleculeFiltersCustomFilterRdkitDescriptorFilter: …

Filter molecules by RDKit molecular descriptors. Each descriptor is constrained to a min/max range. Only descriptors you provide are checked — omitted descriptors are unconstrained.

type: Literal["rdkit_descriptor_filter"]
fraction_csp3: Optional[MoleculeFiltersCustomFilterRdkitDescriptorFilterFractionCsp3]

Min/max range constraint for an RDKit molecular descriptor

max: Optional[float]

Maximum allowed value (inclusive)

min: Optional[float]

Minimum allowed value (inclusive)

mol_logp: Optional[MoleculeFiltersCustomFilterRdkitDescriptorFilterMolLogp]

Min/max range constraint for an RDKit molecular descriptor

max: Optional[float]

Maximum allowed value (inclusive)

min: Optional[float]

Minimum allowed value (inclusive)

mol_wt: Optional[MoleculeFiltersCustomFilterRdkitDescriptorFilterMolWt]

Min/max range constraint for an RDKit molecular descriptor

max: Optional[float]

Maximum allowed value (inclusive)

min: Optional[float]

Minimum allowed value (inclusive)

num_aromatic_rings: Optional[MoleculeFiltersCustomFilterRdkitDescriptorFilterNumAromaticRings]

Min/max range constraint for an RDKit molecular descriptor

max: Optional[float]

Maximum allowed value (inclusive)

min: Optional[float]

Minimum allowed value (inclusive)

num_h_acceptors: Optional[MoleculeFiltersCustomFilterRdkitDescriptorFilterNumHAcceptors]

Min/max range constraint for an RDKit molecular descriptor

max: Optional[float]

Maximum allowed value (inclusive)

min: Optional[float]

Minimum allowed value (inclusive)

num_h_donors: Optional[MoleculeFiltersCustomFilterRdkitDescriptorFilterNumHDonors]

Min/max range constraint for an RDKit molecular descriptor

max: Optional[float]

Maximum allowed value (inclusive)

min: Optional[float]

Minimum allowed value (inclusive)

num_heteroatoms: Optional[MoleculeFiltersCustomFilterRdkitDescriptorFilterNumHeteroatoms]

Min/max range constraint for an RDKit molecular descriptor

max: Optional[float]

Maximum allowed value (inclusive)

min: Optional[float]

Minimum allowed value (inclusive)

num_rings: Optional[MoleculeFiltersCustomFilterRdkitDescriptorFilterNumRings]

Min/max range constraint for an RDKit molecular descriptor

max: Optional[float]

Maximum allowed value (inclusive)

min: Optional[float]

Minimum allowed value (inclusive)

num_rotatable_bonds: Optional[MoleculeFiltersCustomFilterRdkitDescriptorFilterNumRotatableBonds]

Min/max range constraint for an RDKit molecular descriptor

max: Optional[float]

Maximum allowed value (inclusive)

min: Optional[float]

Minimum allowed value (inclusive)

tpsa: Optional[MoleculeFiltersCustomFilterRdkitDescriptorFilterTpsa]

Min/max range constraint for an RDKit molecular descriptor

max: Optional[float]

Maximum allowed value (inclusive)

min: Optional[float]

Minimum allowed value (inclusive)

class MoleculeFiltersCustomFilterSmartsCustomFilter: …

Filter molecules by custom SMARTS patterns. Molecules matching any pattern are rejected.

patterns: Sequence[str]

SMARTS patterns. Molecules matching any pattern are rejected.

type: Literal["smarts_custom_filter"]
class MoleculeFiltersCustomFilterSmartsCatalogFilter: …

Filter molecules using a predefined SMARTS catalog of structural alerts.

catalog: Literal["PAINS", "PAINS_A", "PAINS_B", 11 more]

Predefined SMARTS catalog to apply. PAINS, BRENK, ChEMBL, and NIH catalogs reject known problematic substructures.

One of the following:
"PAINS"
"PAINS_A"
"PAINS_B"
"PAINS_C"
"BRENK"
"CHEMBL"
"CHEMBL_BMS"
"CHEMBL_Dundee"
"CHEMBL_Glaxo"
"CHEMBL_Inpharmatica"
"CHEMBL_LINT"
"CHEMBL_MLSMR"
"CHEMBL_SureChEMBL"
"NIH"
type: Literal["smarts_catalog_filter"]
class MoleculeFiltersCustomFilterSmilesRegexFilter: …

Filter molecules by regex patterns on their SMILES representation.

patterns: Sequence[str]

Regex patterns applied to SMILES strings. Molecules matching any pattern are rejected.

type: Literal["smiles_regex_filter"]
workspace_id: Optional[str]

Target workspace ID (admin keys only; ignored for workspace keys)

ReturnsExpand Collapse
class DesignEstimateCostResponse: …

Estimate response with monetary values encoded as decimal strings to preserve precision.

breakdown: Breakdown

Cost breakdown for the billed application.

application: Literal["structure_and_binding", "small_molecule_design", "small_molecule_library_screen", 4 more]
One of the following:
"structure_and_binding"
"small_molecule_design"
"small_molecule_library_screen"
"protein_design"
"protein_redesign"
"protein_library_screen"
"adme"
cost_per_unit_usd: str

Estimated cost per displayed unit as a decimal string, rounded up to 4 decimal places. This may include token-size multipliers or generation overhead; estimated_cost_usd is the authoritative total.

num_units: int

Number of billable units in the estimate. The unit depends on the endpoint: samples for structure-and-binding, molecules for ADME, and requested proteins or molecules for design/screen endpoints.

disclaimer: str
estimated_cost_usd: str

Estimated total cost as a decimal string

Estimate cost for a small molecule design run

import os
from boltz_api import Boltz

client = Boltz(
    api_key=os.environ.get("BOLTZ_API_KEY"),  # This is the default and can be omitted
)
response = client.small_molecule.design.estimate_cost(
    num_molecules=10,
    target={
        "entities": [{
            "chain_ids": ["string"],
            "type": "protein",
            "value": "value",
        }]
    },
)
print(response.breakdown)
{
  "breakdown": {
    "application": "structure_and_binding",
    "cost_per_unit_usd": "0.0500",
    "num_units": 1
  },
  "disclaimer": "This is an estimate only and may differ from your actual charges. Final billing is based on exact token counts computed at run time. For large library screens, the estimate is extrapolated from a sample and may be less accurate for highly variable inputs.",
  "estimated_cost_usd": "0.0500"
}
Returns Examples
{
  "breakdown": {
    "application": "structure_and_binding",
    "cost_per_unit_usd": "0.0500",
    "num_units": 1
  },
  "disclaimer": "This is an estimate only and may differ from your actual charges. Final billing is based on exact token counts computed at run time. For large library screens, the estimate is extrapolated from a sample and may be less accurate for highly variable inputs.",
  "estimated_cost_usd": "0.0500"
}