API Reference

Small Molecule

Library Screen

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Estimate cost for a small molecule library screen

POST/compute/v1/small-molecule/library-screen/estimate-cost

Estimate the cost of a small molecule library screen without creating any resource or consuming GPU.

Body ParametersExpand Collapse

molecules: array of object { smiles, id }

List of small molecules to screen.

smiles: string

SMILES string of the molecule

id: optional string

Optional identifier for this molecule

target: object { entities, bonds, constraints, 2 more }

Target protein with binding pocket for small molecule design or screening

entities: array of object { chain_ids, type, value, 2 more }

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

chain_ids: array of string

Chain IDs for this entity

type: "protein"

value: string

Amino acid sequence (one-letter codes)

cyclic: optional boolean

Whether the sequence is cyclic

modifications: optional array of object { residue_index, type, value } or object { residue_index, type, value }

Post-translational modifications. Optional; defaults to an empty list when omitted.

Accepts one of the following:

CcdModification = object { residue_index, type, value }

residue_index: number

0-based index of the residue to modify

minimum0

type: "ccd"

value: string

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

SmilesModification = object { residue_index, type, value }

residue_index: number

0-based index of the residue to modify

minimum0

type: "smiles"

value: string

SMILES string for the modification

bonds: optional array of object { atom1, atom2 }

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

atom1: object { atom_name, chain_id, type } or object { atom_name, chain_id, residue_index, type }

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

Accepts one of the following:

LigandAtom = object { atom_name, chain_id, type }

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

atom_name: string

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: string

Chain ID containing the atom

type: "ligand_atom"

PolymerAtom = object { atom_name, chain_id, residue_index, type }

atom_name: string

Standardized atom name (verifiable in CIF file on RCSB)

chain_id: string

Chain ID containing the atom

residue_index: number

0-based residue index

minimum0

type: "polymer_atom"

atom2: object { atom_name, chain_id, type } or object { atom_name, chain_id, residue_index, type }

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

Accepts one of the following:

LigandAtom = object { atom_name, chain_id, type }

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

atom_name: string

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: string

Chain ID containing the atom

type: "ligand_atom"

PolymerAtom = object { atom_name, chain_id, residue_index, type }

atom_name: string

Standardized atom name (verifiable in CIF file on RCSB)

chain_id: string

Chain ID containing the atom

residue_index: number

0-based residue index

minimum0

type: "polymer_atom"

constraints: optional array of object { binder_chain_id, contact_residues, max_distance_angstrom, 2 more } or object { max_distance_angstrom, token1, token2, 2 more }

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

Accepts one of the following:

PocketConstraint = object { binder_chain_id, contact_residues, max_distance_angstrom, 2 more }

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

binder_chain_id: string

Chain ID of the binder molecule

contact_residues: map[array of number]

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: number

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

type: "pocket"

force: optional boolean

Whether to force the constraint

ContactConstraint = object { max_distance_angstrom, token1, token2, 2 more }

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

max_distance_angstrom: number

Maximum distance in Angstroms

token1: object { chain_id, residue_index, type } or object { atom_name, chain_id, type }

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

Accepts one of the following:

PolymerContactToken = object { chain_id, residue_index, type }

chain_id: string

Chain ID

residue_index: number

0-based residue index

minimum0

type: "polymer_contact"

LigandContactToken = object { atom_name, chain_id, type }

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

atom_name: string

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

chain_id: string

Chain ID

type: "ligand_contact"

token2: object { chain_id, residue_index, type } or object { atom_name, chain_id, type }

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

Accepts one of the following:

PolymerContactToken = object { chain_id, residue_index, type }

chain_id: string

Chain ID

residue_index: number

0-based residue index

minimum0

type: "polymer_contact"

LigandContactToken = object { atom_name, chain_id, type }

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

atom_name: string

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

chain_id: string

Chain ID

type: "ligand_contact"

type: "contact"

force: optional boolean

Whether to force the constraint

pocket_residues: optional map[array of number]

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 array of string

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.

idempotency_key: optional string

Client-provided key to prevent duplicate submissions on retries

maxLength255

molecule_filters: optional object { boltz_smarts_catalog_filter_level, custom_filters }

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

boltz_smarts_catalog_filter_level: optional "recommended" or "extra" or "aggressive" or "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.

Accepts one of the following:

"recommended"

"extra"

"aggressive"

"disabled"

custom_filters: optional array of object { max_hba, max_hbd, max_logp, 3 more } or object { type, fraction_csp3, mol_logp, 8 more } or object { patterns, type } or 2 more

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

Accepts one of the following:

LipinskiFilter = object { max_hba, max_hbd, max_logp, 3 more }

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: number

Maximum number of hydrogen bond acceptors. Lipinski threshold: 10

max_hbd: number

Maximum number of hydrogen bond donors. Lipinski threshold: 5

max_logp: number

Maximum LogP. Lipinski threshold: 5

max_mw: number

Maximum molecular weight (Da). Lipinski threshold: 500

type: "lipinski_filter"

allow_single_violation: optional boolean

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

RdkitDescriptorFilter = object { type, fraction_csp3, mol_logp, 8 more }

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: "rdkit_descriptor_filter"

fraction_csp3: optional object { max, min }

Min/max range constraint for an RDKit molecular descriptor

max: optional number

Maximum allowed value (inclusive)

min: optional number

Minimum allowed value (inclusive)

mol_logp: optional object { max, min }

Min/max range constraint for an RDKit molecular descriptor

max: optional number

Maximum allowed value (inclusive)

min: optional number

Minimum allowed value (inclusive)

mol_wt: optional object { max, min }

Min/max range constraint for an RDKit molecular descriptor

max: optional number

Maximum allowed value (inclusive)

min: optional number

Minimum allowed value (inclusive)

num_aromatic_rings: optional object { max, min }

Min/max range constraint for an RDKit molecular descriptor

max: optional number

Maximum allowed value (inclusive)

min: optional number

Minimum allowed value (inclusive)

num_h_acceptors: optional object { max, min }

Min/max range constraint for an RDKit molecular descriptor

max: optional number

Maximum allowed value (inclusive)

min: optional number

Minimum allowed value (inclusive)

num_h_donors: optional object { max, min }

Min/max range constraint for an RDKit molecular descriptor

max: optional number

Maximum allowed value (inclusive)

min: optional number

Minimum allowed value (inclusive)

num_heteroatoms: optional object { max, min }

Min/max range constraint for an RDKit molecular descriptor

max: optional number

Maximum allowed value (inclusive)

min: optional number

Minimum allowed value (inclusive)

num_rings: optional object { max, min }

Min/max range constraint for an RDKit molecular descriptor

max: optional number

Maximum allowed value (inclusive)

min: optional number

Minimum allowed value (inclusive)

num_rotatable_bonds: optional object { max, min }

Min/max range constraint for an RDKit molecular descriptor

max: optional number

Maximum allowed value (inclusive)

min: optional number

Minimum allowed value (inclusive)

tpsa: optional object { max, min }

Min/max range constraint for an RDKit molecular descriptor

max: optional number

Maximum allowed value (inclusive)

min: optional number

Minimum allowed value (inclusive)

SmartsCustomFilter = object { patterns, type }

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

patterns: array of string

SMARTS patterns. Molecules matching any pattern are rejected.

type: "smarts_custom_filter"

SmartsCatalogFilter = object { catalog, type }

Filter molecules using a predefined SMARTS catalog of structural alerts.

catalog: "PAINS" or "PAINS_A" or "PAINS_B" or 11 more

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

Accepts 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: "smarts_catalog_filter"

SmilesRegexFilter = object { patterns, type }

Filter molecules by regex patterns on their SMILES representation.

patterns: array of string

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

type: "smiles_regex_filter"

workspace_id: optional string

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

ReturnsExpand Collapse

breakdown: object { application, cost_per_unit_usd, num_units }

Cost breakdown for the billed application.

application: "structure_and_binding" or "small_molecule_design" or "small_molecule_library_screen" or 3 more

Accepts one of the following:

"structure_and_binding"

"small_molecule_design"

"small_molecule_library_screen"

"protein_design"

"protein_library_screen"

"adme"

cost_per_unit_usd: string

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: number

Number of units shown for the estimate. For structure-and-binding, this is the requested number of samples. For protein and small-molecule design/screen endpoints, this is the requested number of proteins or molecules.

disclaimer: string

estimated_cost_usd: string

Estimated total cost as a decimal string

Estimate cost for a small molecule library screen

HTTP

HTTP

TypeScript

Python

Go

CLI Tool

curl https://api.boltz.bio/compute/v1/small-molecule/library-screen/estimate-cost \
    -H 'Content-Type: application/json' \
    -H "x-api-key: $BOLTZ_API_KEY" \
    -d '{
          "molecules": [
            {
              "smiles": "smiles"
            }
          ],
          "target": {
            "entities": [
              {
                "chain_ids": [
                  "string"
                ],
                "type": "protein",
                "value": "value"
              }
            ]
          }
        }'

200 example

{
  "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

200 example

{
  "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"
}