Estimate cost for a structure and binding prediction

predictions.structure_and_binding.estimate_cost() -> StructureAndBindingEstimateCostResponse

POST/compute/v1/predictions/structure-and-binding/estimate-cost

Estimate the cost of a prediction without creating any resource or consuming GPU.

ParametersExpand Collapse

input: Input

entities: Iterable[InputEntity]

Entities (proteins, RNA, DNA, ligands) forming the complex to predict. Order determines chain assignment.

One of the following:

class InputEntityBoltz2ProteinEntity: …

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

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)

msa: Optional[InputEntityBoltz2ProteinEntityMsa]

Optional protein MSA control. Omit msa on all protein entities to use automatic MSA generation. Use custom for user-provided A3M/CSV files, or empty for single-sequence mode. Custom MSA and automatic MSA cannot be mixed in one request.

One of the following:

class InputEntityBoltz2ProteinEntityMsaBoltz2CustomMsa: …

Use a user-provided MSA for this protein entity. If any protein entity uses a custom MSA, every other protein entity must use either custom or empty MSA; automatic MSA generation cannot be mixed with custom MSAs in the same request.

format: Literal["a3m", "csv"]

Custom MSA file format. Base64 uploads must use media_type text/x-a3m for A3M or text/csv for CSV.

One of the following:

"a3m"

"csv"

source: InputEntityBoltz2ProteinEntityMsaBoltz2CustomMsaSource

How to provide a file to the API

One of the following:

class InputEntityBoltz2ProteinEntityMsaBoltz2CustomMsaSourceURLSource: …

type: Literal["url"]

url: str

formaturi

class InputEntityBoltz2ProteinEntityMsaBoltz2CustomMsaSourceBase64Source: …

data: str

Base64-encoded file contents

media_type: str

MIME type (e.g., text/csv)

type: Literal["base64"]

type: Literal["custom"]

class InputEntityBoltz2ProteinEntityMsaBoltz2EmptyMsa: …

Run this protein entity in single-sequence mode without an MSA. Use this for chains that should not use automatic MSA generation, including non-homologous chains in a request that also includes custom MSAs.

type: Literal["empty"]

class InputEntityRnaEntity: …

chain_ids: Sequence[str]

Chain IDs for this entity

type: Literal["rna"]

value: str

RNA nucleotide sequence (A, C, G, U, N)

cyclic: Optional[bool]

Whether the sequence is cyclic

modifications: Optional[Iterable[InputEntityRnaEntityModification]]

CCD chemical 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)

class InputEntityDnaEntity: …

chain_ids: Sequence[str]

Chain IDs for this entity

type: Literal["dna"]

value: str

DNA nucleotide sequence (A, C, G, T, N)

cyclic: Optional[bool]

Whether the sequence is cyclic

modifications: Optional[Iterable[InputEntityDnaEntityModification]]

CCD chemical 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)

class InputEntityLigandCcdEntity: …

chain_ids: Sequence[str]

Chain IDs for this ligand

type: Literal["ligand_ccd"]

value: str

CCD code (e.g., ATP, ADP)

class InputEntityLigandSmilesEntity: …

chain_ids: Sequence[str]

Chain IDs for this ligand

type: Literal["ligand_smiles"]

value: str

SMILES string representing the ligand

binding: Optional[InputBinding]

One of the following:

class InputBindingLigandProteinBinding: …

binder_chain_id: str

Chain ID of the ligand binder (must have exactly 1 copy, <50 atoms, and only ligands+proteins in entities)

type: Literal["ligand_protein_binding"]

class InputBindingProteinProteinBinding: …

binder_chain_ids: Sequence[str]

Chain IDs of the protein binders

type: Literal["protein_protein_binding"]

bonds: Optional[Iterable[InputBond]]

Bond constraints between atoms. Atom-level ligand references currently support ligand_ccd only; ligand_smiles is unsupported.

atom1: InputBondAtom1

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

One of the following:

class InputBondAtom1LigandAtom: …

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

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

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

One of the following:

class InputBondAtom2LigandAtom: …

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

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

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

One of the following:

class InputConstraintPocketConstraint: …

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

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

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

One of the following:

class InputConstraintContactConstraintToken1PolymerContactToken: …

chain_id: str

Chain ID

residue_index: int

0-based residue index

minimum0

type: Literal["polymer_contact"]

class InputConstraintContactConstraintToken1LigandContactToken: …

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

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

One of the following:

class InputConstraintContactConstraintToken2PolymerContactToken: …

chain_id: str

Chain ID

residue_index: int

0-based residue index

minimum0

type: Literal["polymer_contact"]

class InputConstraintContactConstraintToken2LigandContactToken: …

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

model_options: Optional[InputModelOptions]

recycling_steps: Optional[int]

The number of recycling steps to use for prediction. Default is 3.

minimum1

sampling_steps: Optional[int]

The number of sampling steps to use for prediction. Default is 200.

minimum50

step_scale: Optional[float]

Diffusion step scale (temperature). Controls sampling diversity — higher values produce more varied structures. Default is 1.638.

minimum1.3

maximum2

num_samples: Optional[int]

Number of structure samples to generate (1-10)

minimum1

maximum10

templates: Optional[Iterable[InputTemplate]]

Template structure files to guide protein-chain prediction. Supports up to 4 CIF or PDB templates from HTTPS URLs or base64 uploads. Use template_chains to map request chains to template-file chains.

template_chains: Iterable[InputTemplateTemplateChain]

Request-to-template chain mappings. Each input_chain_id and template_chain_id must be unique within this template.

input_chain_id: str

Chain ID in this prediction request

template_chain_id: str

Corresponding chain ID in the template structure file

template_structure: InputTemplateTemplateStructure

How to provide a template structure file. URLs must point to a CIF or PDB file; base64 uploads must use chemical/x-cif or chemical/x-pdb.

One of the following:

class InputTemplateTemplateStructureURLSource: …

type: Literal["url"]

url: str

formaturi

class InputTemplateTemplateStructureTemplateStructureBase64Source: …

data: str

Base64-encoded template structure file contents

media_type: Literal["chemical/x-cif", "chemical/x-pdb"]

Template structure MIME type

One of the following:

"chemical/x-cif"

CIF template structure

"chemical/x-pdb"

PDB template structure

type: Literal["base64"]

force_threshold_angstroms: Optional[float]

Force the template reference potential with this distance threshold in angstroms. Omit to use the template without force.

minimum0

model: Literal["boltz-2.1"]

Model to use for prediction

idempotency_key: Optional[str]

Client-provided key to prevent duplicate submissions on retries

maxLength255

workspace_id: Optional[str]

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

ReturnsExpand Collapse

class StructureAndBindingEstimateCostResponse: …

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 structure and binding prediction

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.predictions.structure_and_binding.estimate_cost(
    input={
        "entities": [{
            "chain_ids": ["string"],
            "type": "protein",
            "value": "value",
        }]
    },
    model="boltz-2.1",
)
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"
}