Skip to content
Boltz Boltz Boltz API Docs
Go to Boltz API
Guides
Screen small molecule libraries

Screen small molecule libraries

Score your own small molecules against a protein target, fetch results as they arrive, and stop early if needed.

A small molecule library screen scores molecules you provide against a protein target. Each molecule is evaluated for binding confidence, optimization score, and structure confidence. Results stream in as molecules are scored — you can fetch them before the screen finishes and stop early.

Results and artifacts

Section titled “Results and artifacts”

Library screens generate molecule results over time. As soon as a molecule is scored, you can read and download the result without waiting for the full screen to finish.

Each screened molecule result includes scoring metrics such as binding confidence, optimization score, and structure confidence. Each result also includes downloadable artifacts for the predicted bound structure and PAE.

Define a target

Section titled “Define a target”

Targets are protein-only entities. The engine automatically identifies the binding pocket to use during the run. You can provide hints to help it find the right one:

  • pocket_residues — If you already know the pocket residues, pass them directly as a map of chain ID to an array of 0-indexed residue indices.
  • reference_ligands — If you have known binders, pass them as an array of SMILES strings. The engine uses these to locate the pocket region.

You can provide one or both. Either will help the engine use the correct binding pocket, and providing both gives it the strongest signal.

{
  "target": {
    "entities": [
      { "type": "protein", "value": "MKTIIALSYIFCLVFA...", "chain_ids": ["A"] }
    ],
    "pocket_residues": {
      "A": [10, 11, 12, 35, 36, 37]
    }
  }
}

Provide molecules

Section titled “Provide molecules”

Pass molecules inline as an array of objects, each with a smiles field and an optional id:

{
  "molecules": [
    { "smiles": "CC(=O)OC1=CC=CC=C1C(=O)O", "id": "aspirin" },
    { "smiles": "C1=CC=C(C=C1)O", "id": "phenol" },
    { "smiles": "CC1=CC=CC=C1" }
  ]
}

When you provide an id, it’s returned as external_id on the corresponding result — use this to correlate results back to your input library.

Molecular filters

Section titled “Molecular filters”

Filters control which generated molecules pass through to results. All custom filters use AND logic — a molecule must pass every filter.

Built-in filter

The boltz_smarts_catalog_filter_level parameter controls Boltz’s built-in structural alert filtering. Our medicinal chemistry team has curated these filters from extensive drug discovery experience, encoding patterns known to cause toxicity, reactivity, or poor pharmacokinetics.

LevelDescription
recommended (default)Balanced filtering that catches the most common problematic substructures.
extraStricter filtering with additional alerts.
aggressiveMost conservative — rejects anything with a known structural concern.
disabledNo built-in filtering.

Custom filters

Add any combination of these to the custom_filters array:

Filter typeWhat it does
lipinski_filterLipinski’s Rule of Five — set max_mw, max_logp, max_hbd, max_hba. Optional allow_single_violation.
rdkit_descriptor_filterRDKit descriptor ranges — mol_wt, mol_logp, tpsa, num_h_donors, num_h_acceptors, num_rotatable_bonds, num_heteroatoms, num_aromatic_rings, num_rings, fraction_csp3. Each accepts {min, max}.
smarts_custom_filterReject molecules matching any of the provided SMARTS patterns.
smarts_catalog_filterReject molecules matching a named catalog: PAINS, PAINS_A, PAINS_B, PAINS_C, BRENK, CHEMBL, CHEMBL_BMS, CHEMBL_Dundee, CHEMBL_Glaxo, CHEMBL_Inpharmatica, CHEMBL_LINT, CHEMBL_MLSMR, CHEMBL_SureChEMBL, NIH.
smiles_regex_filterReject molecules whose SMILES matches any of the provided regex patterns.

Molecules that don’t pass the filters are skipped and won’t appear in results.

Run a screen and download results

Section titled “Run a screen and download results”

run_small_molecule_library_screen() submits the screen, waits while molecules are scored, downloads result archives, and returns a local run directory.

import os
from boltz_api import Boltz


client = Boltz(api_key=os.environ["BOLTZ_API_KEY"])


run_dir = client.experiments.run_small_molecule_library_screen(
    target={
        "entities": [
            {"type": "protein", "value": "MKTIIALSYIFCLVFA", "chain_ids": ["A"]},
        ],
    },
    molecules=[
        {"smiles": "CC(=O)OC1=CC=CC=C1C(=O)O", "id": "aspirin"},
        {"smiles": "C1=CC=C(C=C1)O", "id": "phenol"},
        {"smiles": "CC1=CC=CC=C1"},
    ],
    name="small-molecule-library-screen",
)
print(run_dir)

The run directory contains the sanitized run record, resumable download state, a result manifest, and downloaded files for each screened molecule:

boltz-experiments/small-molecule-library-screen/
  .boltz-run.json
  run.json
  results/
    index.jsonl
    sm_scr_result_.../
      metadata.json
      archive.tar.gz
      files/
        result/
          metrics.json
          predicted_structure.cif
          pae.npz

Start now, download later

Section titled “Start now, download later”

The main run_small_molecule_library_screen() example already waits and downloads. To submit now and download later, use start_small_molecule_library_screen() and resume with wait_and_download().

run_dir = client.experiments.start_small_molecule_library_screen(
    target={
        "entities": [
            {"type": "protein", "value": "MKTIIALSYIFCLVFA", "chain_ids": ["A"]},
        ],
    },
    molecules=[
        {"smiles": "CC(=O)OC1=CC=CC=C1C(=O)O", "id": "aspirin"},
        {"smiles": "C1=CC=C(C=C1)O", "id": "phenol"},
    ],
    name="submit-now-finish-later",
)


client.experiments.wait_and_download(run_dir=run_dir)

Inspect downloaded results

Section titled “Inspect downloaded results”

Result pages and artifact archives are already downloaded into the run directory.

print(run_dir)
for result_dir in (run_dir / "results").iterdir():
    print(result_dir)

Stop early

Section titled “Stop early”
client.experiments.stop(run_dir=run_dir)

Metrics

Section titled “Metrics”
MetricRangeWhat it measures
binding_confidence0–1Likelihood of binding. Primary metric for hit discovery.
optimization_score—Binding strength ranking. Use for lead optimization.
structure_confidence0–1Overall confidence in the predicted structure.
iptm0–1Interface predicted TM-score.
ptm0–1Global predicted TM-score.
plddt0–1Per-residue structure confidence.
complex_plddt0–1pLDDT across the full complex.
complex_iplddt0–1Interface pLDDT for the complex.

Status values

Section titled “Status values”
StatusMeaning
pendingThe screen is queued and has not started yet.
runningThe screen is actively scoring molecules. Results may already be available.
succeededAll molecules have been screened.
failedThe screen encountered an error. Check the error field.
stoppedThe screen was stopped early. Partial results are available.