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

Get small molecule design run status

small_molecule.design.retrieve(strid, DesignRetrieveParams**kwargs) -> DesignRetrieveResponse
GET/compute/v1/small-molecule/design/{id}

Retrieve a design run by ID, including progress and status

ParametersExpand Collapse
id: str
workspace_id: Optional[str]

Workspace ID. Only used with admin API keys. Ignored (or validated) for workspace-scoped keys.

ReturnsExpand Collapse
class DesignRetrieveResponse: …

A small molecule design engine run that generates novel molecules

id: str

Unique SmDesignRun identifier

completed_at: Optional[datetime]
formatdate-time
created_at: datetime
formatdate-time
data_deleted_at: Optional[datetime]

When the input, output, and result data was permanently deleted. Null if data has not been deleted.

formatdate-time
engine: Literal["boltz-sm-design"]

Engine used for small molecule design

engine_version: str

Engine version used for small molecule design

error: Optional[Error]
code: str

Machine-readable error code

message: str

Human-readable error message

details: Optional[object]

Additional field-level error details keyed by input path, when available.

input: Optional[Input]

Pipeline input (null if data deleted)

num_molecules: int

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

minimum10
maximum1000000
target: InputTarget

Target protein with binding pocket for small molecule design or screening

entities: List[InputTargetEntity]

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

chain_ids: List[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[List[InputTargetEntityModification]]

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

Accepts one of the following:
class InputTargetEntityModificationCcdModificationResponse: …
residue_index: int

0-based index of the residue to modify

minimum0
type: Literal["ccd"]
value: str

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

class InputTargetEntityModificationSmilesModificationResponse: …
residue_index: int

0-based index of the residue to modify

minimum0
type: Literal["smiles"]
value: str

SMILES string for the modification

bonds: Optional[List[InputTargetBond]]

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

atom1: InputTargetBondAtom1

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

Accepts one of the following:
class InputTargetBondAtom1LigandAtomResponse: …

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 InputTargetBondAtom1PolymerAtomResponse: …
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: InputTargetBondAtom2

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

Accepts one of the following:
class InputTargetBondAtom2LigandAtomResponse: …

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 InputTargetBondAtom2PolymerAtomResponse: …
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[List[InputTargetConstraint]]

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

Accepts one of the following:
class InputTargetConstraintPocketConstraintResponse: …

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, List[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 InputTargetConstraintContactConstraintResponse: …

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

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

Accepts one of the following:
class InputTargetConstraintContactConstraintResponseToken1PolymerContactTokenResponse: …
chain_id: str

Chain ID

residue_index: int

0-based residue index

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

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

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

Accepts one of the following:
class InputTargetConstraintContactConstraintResponseToken2PolymerContactTokenResponse: …
chain_id: str

Chain ID

residue_index: int

0-based residue index

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

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, List[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[List[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.

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[InputMoleculeFilters]

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.

Accepts one of the following:
"recommended"
"extra"
"aggressive"
"disabled"
custom_filters: Optional[List[InputMoleculeFiltersCustomFilter]]

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

Accepts one of the following:
class InputMoleculeFiltersCustomFilterLipinskiFilterResponse: …

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 InputMoleculeFiltersCustomFilterRdkitDescriptorFilterResponse: …

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[InputMoleculeFiltersCustomFilterRdkitDescriptorFilterResponseFractionCsp3]

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[InputMoleculeFiltersCustomFilterRdkitDescriptorFilterResponseMolLogp]

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[InputMoleculeFiltersCustomFilterRdkitDescriptorFilterResponseMolWt]

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[InputMoleculeFiltersCustomFilterRdkitDescriptorFilterResponseNumAromaticRings]

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[InputMoleculeFiltersCustomFilterRdkitDescriptorFilterResponseNumHAcceptors]

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[InputMoleculeFiltersCustomFilterRdkitDescriptorFilterResponseNumHDonors]

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[InputMoleculeFiltersCustomFilterRdkitDescriptorFilterResponseNumHeteroatoms]

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[InputMoleculeFiltersCustomFilterRdkitDescriptorFilterResponseNumRings]

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[InputMoleculeFiltersCustomFilterRdkitDescriptorFilterResponseNumRotatableBonds]

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[InputMoleculeFiltersCustomFilterRdkitDescriptorFilterResponseTpsa]

Min/max range constraint for an RDKit molecular descriptor

max: Optional[float]

Maximum allowed value (inclusive)

min: Optional[float]

Minimum allowed value (inclusive)

class InputMoleculeFiltersCustomFilterSmartsCustomFilterResponse: …

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

patterns: List[str]

SMARTS patterns. Molecules matching any pattern are rejected.

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

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.

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: Literal["smarts_catalog_filter"]
class InputMoleculeFiltersCustomFilterSmilesRegexFilterResponse: …

Filter molecules by regex patterns on their SMILES representation.

patterns: List[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)

livemode: bool

Whether this resource was created with a live API key.

progress: Optional[Progress]
num_molecules_generated: int

Number of molecules generated so far

minimum0
total_molecules_to_generate: int

Total number of molecules requested

minimum1
latest_result_id: Optional[str]

ID of the most recently generated result

started_at: Optional[datetime]
formatdate-time
status: Literal["pending", "running", "succeeded", 2 more]
Accepts one of the following:
"pending"
"running"
"succeeded"
"failed"
"stopped"
stopped_at: Optional[datetime]
formatdate-time
workspace_id: str

Workspace ID

idempotency_key: Optional[str]

Client-provided idempotency key

Get small molecule design run status

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
)
design = client.small_molecule.design.retrieve(
    id="id",
)
print(design.id)
{
  "id": "id",
  "completed_at": "2019-12-27T18:11:19.117Z",
  "created_at": "2019-12-27T18:11:19.117Z",
  "data_deleted_at": "2019-12-27T18:11:19.117Z",
  "engine": "boltz-sm-design",
  "engine_version": "engine_version",
  "error": {
    "code": "code",
    "message": "message",
    "details": {}
  },
  "input": {
    "num_molecules": 10,
    "target": {
      "entities": [
        {
          "chain_ids": [
            "string"
          ],
          "type": "protein",
          "value": "value",
          "cyclic": true,
          "modifications": [
            {
              "residue_index": 0,
              "type": "ccd",
              "value": "value"
            }
          ]
        }
      ],
      "bonds": [
        {
          "atom1": {
            "atom_name": "atom_name",
            "chain_id": "chain_id",
            "type": "ligand_atom"
          },
          "atom2": {
            "atom_name": "atom_name",
            "chain_id": "chain_id",
            "type": "ligand_atom"
          }
        }
      ],
      "constraints": [
        {
          "binder_chain_id": "binder_chain_id",
          "contact_residues": {
            "A": [
              42,
              43,
              44,
              67,
              68,
              69
            ]
          },
          "max_distance_angstrom": 0,
          "type": "pocket",
          "force": true
        }
      ],
      "pocket_residues": {
        "A": [
          42,
          43,
          44,
          67,
          68,
          69
        ]
      },
      "reference_ligands": [
        "string"
      ]
    },
    "chemical_space": "enamine_real",
    "idempotency_key": "idempotency_key",
    "molecule_filters": {
      "boltz_smarts_catalog_filter_level": "recommended",
      "custom_filters": [
        {
          "max_hba": 0,
          "max_hbd": 0,
          "max_logp": 0,
          "max_mw": 0,
          "type": "lipinski_filter",
          "allow_single_violation": true
        }
      ]
    },
    "workspace_id": "workspace_id"
  },
  "livemode": true,
  "progress": {
    "num_molecules_generated": 0,
    "total_molecules_to_generate": 1,
    "latest_result_id": "latest_result_id"
  },
  "started_at": "2019-12-27T18:11:19.117Z",
  "status": "pending",
  "stopped_at": "2019-12-27T18:11:19.117Z",
  "workspace_id": "workspace_id",
  "idempotency_key": "idempotency_key"
}
Returns Examples
{
  "id": "id",
  "completed_at": "2019-12-27T18:11:19.117Z",
  "created_at": "2019-12-27T18:11:19.117Z",
  "data_deleted_at": "2019-12-27T18:11:19.117Z",
  "engine": "boltz-sm-design",
  "engine_version": "engine_version",
  "error": {
    "code": "code",
    "message": "message",
    "details": {}
  },
  "input": {
    "num_molecules": 10,
    "target": {
      "entities": [
        {
          "chain_ids": [
            "string"
          ],
          "type": "protein",
          "value": "value",
          "cyclic": true,
          "modifications": [
            {
              "residue_index": 0,
              "type": "ccd",
              "value": "value"
            }
          ]
        }
      ],
      "bonds": [
        {
          "atom1": {
            "atom_name": "atom_name",
            "chain_id": "chain_id",
            "type": "ligand_atom"
          },
          "atom2": {
            "atom_name": "atom_name",
            "chain_id": "chain_id",
            "type": "ligand_atom"
          }
        }
      ],
      "constraints": [
        {
          "binder_chain_id": "binder_chain_id",
          "contact_residues": {
            "A": [
              42,
              43,
              44,
              67,
              68,
              69
            ]
          },
          "max_distance_angstrom": 0,
          "type": "pocket",
          "force": true
        }
      ],
      "pocket_residues": {
        "A": [
          42,
          43,
          44,
          67,
          68,
          69
        ]
      },
      "reference_ligands": [
        "string"
      ]
    },
    "chemical_space": "enamine_real",
    "idempotency_key": "idempotency_key",
    "molecule_filters": {
      "boltz_smarts_catalog_filter_level": "recommended",
      "custom_filters": [
        {
          "max_hba": 0,
          "max_hbd": 0,
          "max_logp": 0,
          "max_mw": 0,
          "type": "lipinski_filter",
          "allow_single_violation": true
        }
      ]
    },
    "workspace_id": "workspace_id"
  },
  "livemode": true,
  "progress": {
    "num_molecules_generated": 0,
    "total_molecules_to_generate": 1,
    "latest_result_id": "latest_result_id"
  },
  "started_at": "2019-12-27T18:11:19.117Z",
  "status": "pending",
  "stopped_at": "2019-12-27T18:11:19.117Z",
  "workspace_id": "workspace_id",
  "idempotency_key": "idempotency_key"
}