Estimate cost for a structure and binding prediction

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

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

Body ParametersJSONExpand Collapse

input: object { entities, binding, bonds, 4 more }

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

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

One of the following:

Boltz2ProteinEntity object { chain_ids, type, value, 3 more }

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 }

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

residue_index: number

0-based index of the residue to modify

minimum0

type: "ccd"

Modification format. Only CCD polymer modifications are supported.

value: string

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

msa: optional object { format, source, type } or object { type }

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:

Boltz2CustomMsa object { format, source, type }

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: "a3m" or "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: object { type, url } or object { data, media_type, type }

How to provide a file to the API

One of the following:

URLSource object { type, url }

type: "url"

url: string

formaturi

Base64Source object { data, media_type, type }

data: string

Base64-encoded file contents

media_type: string

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

type: "base64"

type: "custom"

Boltz2EmptyMsa object { type }

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

RnaEntity object { chain_ids, type, value, 2 more }

chain_ids: array of string

Chain IDs for this entity

type: "rna"

value: string

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

cyclic: optional boolean

Whether the sequence is cyclic

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

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

residue_index: number

0-based index of the residue to modify

minimum0

type: "ccd"

Modification format. Only CCD polymer modifications are supported.

value: string

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

DnaEntity object { chain_ids, type, value, 2 more }

chain_ids: array of string

Chain IDs for this entity

type: "dna"

value: string

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

cyclic: optional boolean

Whether the sequence is cyclic

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

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

residue_index: number

0-based index of the residue to modify

minimum0

type: "ccd"

Modification format. Only CCD polymer modifications are supported.

value: string

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

LigandCcdEntity object { chain_ids, type, value }

chain_ids: array of string

Chain IDs for this ligand

type: "ligand_ccd"

value: string

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

LigandSmilesEntity object { chain_ids, type, value }

chain_ids: array of string

Chain IDs for this ligand

type: "ligand_smiles"

value: string

SMILES string representing the ligand

binding: optional object { binder_chain_id, type } or object { binder_chain_ids, type }

One of the following:

LigandProteinBinding object { binder_chain_id, type }

binder_chain_id: string

Chain ID of the ligand binder (must have exactly 1 copy, at most 2048 heavy atoms, and only ligands+proteins in entities)

type: "ligand_protein_binding"

ProteinProteinBinding object { binder_chain_ids, type }

binder_chain_ids: array of string

Chain IDs of the protein binders

type: "protein_protein_binding"

bonds: optional array of object { atom1, atom2 }

Bond constraints between atoms. Ligand atom references support CCD atom names and explicitly atom-mapped SMILES atoms.

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

Ligand atom reference for a CCD atom or an explicitly atom-mapped SMILES atom.

One of the following:

LigandAtom object { atom_name, chain_id, type }

Ligand atom reference for a CCD atom or an explicitly atom-mapped SMILES atom.

atom_name: string

Atom name. For ligand_ccd, use the standardized CIF atom name. For ligand_smiles, explicitly label the atom with numeric atom-map notation: [C:1] is referenced as C1 and [O:2] as O2. The resulting name must be unique within the molecule and at most four characters.

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 for a CCD atom or an explicitly atom-mapped SMILES atom.

One of the following:

LigandAtom object { atom_name, chain_id, type }

Ligand atom reference for a CCD atom or an explicitly atom-mapped SMILES atom.

atom_name: string

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). Ligand atom references support CCD atom names and explicitly atom-mapped SMILES atoms.

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 }

Maximum-distance contact constraint between two polymer residues or ligand atoms.

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 for a CCD atom or an explicitly atom-mapped SMILES atom.

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 for a CCD atom or an explicitly atom-mapped SMILES atom.

atom_name: string

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 for a CCD atom or an explicitly atom-mapped SMILES atom.

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 for a CCD atom or an explicitly atom-mapped SMILES atom.

atom_name: string

chain_id: string

Chain ID

type: "ligand_contact"

type: "contact"

force: optional boolean

Whether to force the constraint

model_options: optional object { recycling_steps, sampling_steps, step_scale }

recycling_steps: optional number

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

minimum1

sampling_steps: optional number

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

minimum50

step_scale: optional number

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

minimum1.3

maximum2

num_samples: optional number

Number of structure samples to generate (1-10)

minimum1

maximum10

templates: optional array of object { template_chains, template_structure, force_threshold_angstroms }

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: array of object { input_chain_id, template_chain_id }

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

input_chain_id: string

Chain ID in this prediction request

template_chain_id: string

Corresponding chain ID in the template structure file

template_structure: object { type, url } or object { data, media_type, type }

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:

URLSource object { type, url }

type: "url"

url: string

formaturi

TemplateStructureBase64Source object { data, media_type, type }

data: string

Base64-encoded template structure file contents

media_type: "chemical/x-cif" or "chemical/x-pdb"

Template structure MIME type

One of the following:

"chemical/x-cif"

CIF template structure

"chemical/x-pdb"

PDB template structure

type: "base64"

force_threshold_angstroms: optional number

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

minimum0

model: "boltz-2.1"

Model to use for prediction

idempotency_key: optional string

Client-provided key to prevent duplicate submissions on retries

maxLength255

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

estimated_cost_usd: string

Estimated total cost as a decimal string

Estimate cost for a structure and binding prediction

curl https://api.boltz.bio/compute/v1/predictions/structure-and-binding/estimate-cost \
    -H 'Content-Type: application/json' \
    -H "x-api-key: $BOLTZ_API_KEY" \
    -d '{
          "input": {
            "entities": [
              {
                "chain_ids": [
                  "string"
                ],
                "type": "protein",
                "value": "value"
              }
            ]
          },
          "model": "boltz-2.1"
        }'

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