Skip to content
Boltz Boltz Boltz API Docs
Go to Boltz API
API Reference
Predictions

Structure And Binding

Predict 3D structure coordinates, per-residue confidence scores, and binding metrics for a molecular complex. Supports optional template-guided folding and per-protein MSA control.

Start a structure and binding prediction
predictions.structure_and_binding.start(StructureAndBindingStartParams**kwargs) -> StructureAndBindingStartResponse
POST/compute/v1/predictions/structure-and-binding
List structure and binding predictions
predictions.structure_and_binding.list(StructureAndBindingListParams**kwargs) -> SyncCursorPage[StructureAndBindingListResponse]
GET/compute/v1/predictions/structure-and-binding
Retrieve a structure and binding prediction
predictions.structure_and_binding.retrieve(strid, StructureAndBindingRetrieveParams**kwargs) -> StructureAndBindingRetrieveResponse
GET/compute/v1/predictions/structure-and-binding/{id}
Delete prediction data
predictions.structure_and_binding.delete_data(strid) -> StructureAndBindingDeleteDataResponse
POST/compute/v1/predictions/structure-and-binding/{id}/delete-data
Estimate cost for a structure and binding prediction
predictions.structure_and_binding.estimate_cost(StructureAndBindingEstimateCostParams**kwargs) -> StructureAndBindingEstimateCostResponse
POST/compute/v1/predictions/structure-and-binding/estimate-cost
ModelsExpand Collapse
class StructureAndBindingStartResponse: …
id: str

Unique prediction identifier

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

When the input/output data was deleted, or null if still available

formatdate-time
error: Optional[Error]

Error details when failed

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.

expires_at: Optional[datetime]

When this resource and its associated data will be permanently deleted. Null while still in progress.

formatdate-time
input: Optional[Input]

Prediction input (null if data deleted)

entities: List[InputEntity]

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

One of the following:
class InputEntityBoltz2ProteinEntityResponse: …
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[InputEntityBoltz2ProteinEntityResponseModification]]

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

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

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: InputEntityBoltz2ProteinEntityResponseMsaBoltz2CustomMsaResponseSource
url: str

URL to download the file

formaturi
url_expires_at: datetime

When the presigned URL expires

formatdate-time
type: Literal["custom"]
class InputEntityBoltz2ProteinEntityResponseMsaBoltz2EmptyMsaResponse: …

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 InputEntityRnaEntityResponse: …
chain_ids: List[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[List[InputEntityRnaEntityResponseModification]]

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 InputEntityDnaEntityResponse: …
chain_ids: List[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[List[InputEntityDnaEntityResponseModification]]

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 InputEntityLigandCcdEntityResponse: …
chain_ids: List[str]

Chain IDs for this ligand

type: Literal["ligand_ccd"]
value: str

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

class InputEntityLigandSmilesEntityResponse: …
chain_ids: List[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 InputBindingLigandProteinBindingResponse: …
binder_chain_id: str

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

type: Literal["ligand_protein_binding"]
class InputBindingProteinProteinBindingResponse: …
binder_chain_ids: List[str]

Chain IDs of the protein binders

type: Literal["protein_protein_binding"]
bonds: Optional[List[InputBond]]

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

atom1: InputBondAtom1

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

One of the following:
class InputBondAtom1LigandAtomResponse: …

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

atom_name: str

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

Chain ID containing the atom

type: Literal["ligand_atom"]
class InputBondAtom1PolymerAtomResponse: …
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 for a CCD atom or an explicitly atom-mapped SMILES atom.

One of the following:
class InputBondAtom2LigandAtomResponse: …

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

atom_name: str

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

Chain ID containing the atom

type: Literal["ligand_atom"]
class InputBondAtom2PolymerAtomResponse: …
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[InputConstraint]]

Structural constraints (pocket and contact). Ligand atom references support CCD atom names and explicitly atom-mapped SMILES atoms.

One of the following:
class InputConstraintPocketConstraintResponse: …

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

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

max_distance_angstrom: float

Maximum distance in Angstroms

token1: InputConstraintContactConstraintResponseToken1

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

One of the following:
class InputConstraintContactConstraintResponseToken1PolymerContactTokenResponse: …
chain_id: str

Chain ID

residue_index: int

0-based residue index

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

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

atom_name: str

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

Chain ID

type: Literal["ligand_contact"]
token2: InputConstraintContactConstraintResponseToken2

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

One of the following:
class InputConstraintContactConstraintResponseToken2PolymerContactTokenResponse: …
chain_id: str

Chain ID

residue_index: int

0-based residue index

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

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

atom_name: str

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: 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[List[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: List[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
url: str

URL to download the file

formaturi
url_expires_at: datetime

When the presigned URL expires

formatdate-time
force_threshold_angstroms: Optional[float]

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

minimum0
livemode: bool

Whether this resource was created with a live API key.

model: Literal["boltz-2.1"]

Model used for prediction

output: Optional[Output]

Prediction output when succeeded

all_sample_results: List[OutputAllSampleResult]

Per-sample structure results

metrics: OutputAllSampleResultMetrics
complex_ipde: float

Complex interface predicted distance error. Lower is better.

complex_iplddt: float

Complex interface pLDDT (0-1 float). Confidence at inter-chain interfaces.

complex_pde: float

Complex predicted distance error. Lower is better.

complex_plddt: float

Complex pLDDT (0-1 float). Per-residue confidence averaged over the complex.

iptm: float

Interface predicted TM score (0-1). Confidence in domain interfaces.

ligand_iptm: float

Ligand interface pTM (0-1). Only present when ligands are included.

protein_iptm: float

Protein-protein interface pTM (0-1). Only present for multi-protein complexes.

ptm: float

Predicted TM score (0-1). Global structure quality.

structure_confidence: float

Overall structure confidence (0-1).

structure: OutputAllSampleResultStructure
url: str

URL to download the file

formaturi
url_expires_at: datetime

When the presigned URL expires

formatdate-time
ligand_structure: Optional[OutputAllSampleResultLigandStructure]
url: str

URL to download the file

formaturi
url_expires_at: datetime

When the presigned URL expires

formatdate-time
best_sample: OutputBestSample
metrics: OutputBestSampleMetrics
complex_ipde: float

Complex interface predicted distance error. Lower is better.

complex_iplddt: float

Complex interface pLDDT (0-1 float). Confidence at inter-chain interfaces.

complex_pde: float

Complex predicted distance error. Lower is better.

complex_plddt: float

Complex pLDDT (0-1 float). Per-residue confidence averaged over the complex.

iptm: float

Interface predicted TM score (0-1). Confidence in domain interfaces.

ligand_iptm: float

Ligand interface pTM (0-1). Only present when ligands are included.

protein_iptm: float

Protein-protein interface pTM (0-1). Only present for multi-protein complexes.

ptm: float

Predicted TM score (0-1). Global structure quality.

structure_confidence: float

Overall structure confidence (0-1).

structure: OutputBestSampleStructure
url: str

URL to download the file

formaturi
url_expires_at: datetime

When the presigned URL expires

formatdate-time
ligand_structure: Optional[OutputBestSampleLigandStructure]
url: str

URL to download the file

formaturi
url_expires_at: datetime

When the presigned URL expires

formatdate-time
archive: Optional[OutputArchive]
url: str

URL to download the file

formaturi
url_expires_at: datetime

When the presigned URL expires

formatdate-time
binding_metrics: Optional[OutputBindingMetrics]
One of the following:
class OutputBindingMetricsLigandProteinBindingMetrics: …
binding_confidence: float

Confidence that binding occurs (0-1). Primary metric for hit discovery.

optimization_score: float

Binding strength ranking score for lead optimization. Higher values indicate stronger predicted binding.

type: Literal["ligand_protein_binding_metrics"]
class OutputBindingMetricsProteinProteinBindingMetrics: …
binding_confidence: float

Confidence that binding occurs (0-1). Primary metric for hit discovery.

type: Literal["protein_protein_binding_metrics"]
started_at: Optional[datetime]
formatdate-time
status: Literal["pending", "running", "succeeded", "failed"]
One of the following:
"pending"
"running"
"succeeded"
"failed"
version: str

Model version used for prediction

workspace_id: str

Workspace ID

idempotency_key: Optional[str]

Client-provided idempotency key

class StructureAndBindingListResponse: …
id: str

Unique prediction identifier

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

When the input/output data was deleted, or null if still available

formatdate-time
error: Optional[Error]

Error details when failed

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.

expires_at: Optional[datetime]

When this resource and its associated data will be permanently deleted. Null while still in progress.

formatdate-time
livemode: bool

Whether this resource was created with a live API key.

model: Literal["boltz-2.1"]

Model used for prediction

started_at: Optional[datetime]
formatdate-time
status: Literal["pending", "running", "succeeded", "failed"]
One of the following:
"pending"
"running"
"succeeded"
"failed"
version: str

Model version used for prediction

workspace_id: str

Workspace ID

idempotency_key: Optional[str]

Client-provided idempotency key

class StructureAndBindingRetrieveResponse: …
id: str

Unique prediction identifier

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

When the input/output data was deleted, or null if still available

formatdate-time
error: Optional[Error]

Error details when failed

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.

expires_at: Optional[datetime]

When this resource and its associated data will be permanently deleted. Null while still in progress.

formatdate-time
input: Optional[Input]

Prediction input (null if data deleted)

entities: List[InputEntity]

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

One of the following:
class InputEntityBoltz2ProteinEntityResponse: …
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[InputEntityBoltz2ProteinEntityResponseModification]]

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

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

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: InputEntityBoltz2ProteinEntityResponseMsaBoltz2CustomMsaResponseSource
url: str

URL to download the file

formaturi
url_expires_at: datetime

When the presigned URL expires

formatdate-time
type: Literal["custom"]
class InputEntityBoltz2ProteinEntityResponseMsaBoltz2EmptyMsaResponse: …

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 InputEntityRnaEntityResponse: …
chain_ids: List[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[List[InputEntityRnaEntityResponseModification]]

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 InputEntityDnaEntityResponse: …
chain_ids: List[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[List[InputEntityDnaEntityResponseModification]]

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 InputEntityLigandCcdEntityResponse: …
chain_ids: List[str]

Chain IDs for this ligand

type: Literal["ligand_ccd"]
value: str

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

class InputEntityLigandSmilesEntityResponse: …
chain_ids: List[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 InputBindingLigandProteinBindingResponse: …
binder_chain_id: str

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

type: Literal["ligand_protein_binding"]
class InputBindingProteinProteinBindingResponse: …
binder_chain_ids: List[str]

Chain IDs of the protein binders

type: Literal["protein_protein_binding"]
bonds: Optional[List[InputBond]]

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

atom1: InputBondAtom1

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

One of the following:
class InputBondAtom1LigandAtomResponse: …

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

atom_name: str

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

Chain ID containing the atom

type: Literal["ligand_atom"]
class InputBondAtom1PolymerAtomResponse: …
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 for a CCD atom or an explicitly atom-mapped SMILES atom.

One of the following:
class InputBondAtom2LigandAtomResponse: …

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

atom_name: str

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

Chain ID containing the atom

type: Literal["ligand_atom"]
class InputBondAtom2PolymerAtomResponse: …
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[InputConstraint]]

Structural constraints (pocket and contact). Ligand atom references support CCD atom names and explicitly atom-mapped SMILES atoms.

One of the following:
class InputConstraintPocketConstraintResponse: …

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

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

max_distance_angstrom: float

Maximum distance in Angstroms

token1: InputConstraintContactConstraintResponseToken1

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

One of the following:
class InputConstraintContactConstraintResponseToken1PolymerContactTokenResponse: …
chain_id: str

Chain ID

residue_index: int

0-based residue index

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

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

atom_name: str

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

Chain ID

type: Literal["ligand_contact"]
token2: InputConstraintContactConstraintResponseToken2

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

One of the following:
class InputConstraintContactConstraintResponseToken2PolymerContactTokenResponse: …
chain_id: str

Chain ID

residue_index: int

0-based residue index

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

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

atom_name: str

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: 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[List[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: List[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
url: str

URL to download the file

formaturi
url_expires_at: datetime

When the presigned URL expires

formatdate-time
force_threshold_angstroms: Optional[float]

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

minimum0
livemode: bool

Whether this resource was created with a live API key.

model: Literal["boltz-2.1"]

Model used for prediction

output: Optional[Output]

Prediction output when succeeded

all_sample_results: List[OutputAllSampleResult]

Per-sample structure results

metrics: OutputAllSampleResultMetrics
complex_ipde: float

Complex interface predicted distance error. Lower is better.

complex_iplddt: float

Complex interface pLDDT (0-1 float). Confidence at inter-chain interfaces.

complex_pde: float

Complex predicted distance error. Lower is better.

complex_plddt: float

Complex pLDDT (0-1 float). Per-residue confidence averaged over the complex.

iptm: float

Interface predicted TM score (0-1). Confidence in domain interfaces.

ligand_iptm: float

Ligand interface pTM (0-1). Only present when ligands are included.

protein_iptm: float

Protein-protein interface pTM (0-1). Only present for multi-protein complexes.

ptm: float

Predicted TM score (0-1). Global structure quality.

structure_confidence: float

Overall structure confidence (0-1).

structure: OutputAllSampleResultStructure
url: str

URL to download the file

formaturi
url_expires_at: datetime

When the presigned URL expires

formatdate-time
ligand_structure: Optional[OutputAllSampleResultLigandStructure]
url: str

URL to download the file

formaturi
url_expires_at: datetime

When the presigned URL expires

formatdate-time
best_sample: OutputBestSample
metrics: OutputBestSampleMetrics
complex_ipde: float

Complex interface predicted distance error. Lower is better.

complex_iplddt: float

Complex interface pLDDT (0-1 float). Confidence at inter-chain interfaces.

complex_pde: float

Complex predicted distance error. Lower is better.

complex_plddt: float

Complex pLDDT (0-1 float). Per-residue confidence averaged over the complex.

iptm: float

Interface predicted TM score (0-1). Confidence in domain interfaces.

ligand_iptm: float

Ligand interface pTM (0-1). Only present when ligands are included.

protein_iptm: float

Protein-protein interface pTM (0-1). Only present for multi-protein complexes.

ptm: float

Predicted TM score (0-1). Global structure quality.

structure_confidence: float

Overall structure confidence (0-1).

structure: OutputBestSampleStructure
url: str

URL to download the file

formaturi
url_expires_at: datetime

When the presigned URL expires

formatdate-time
ligand_structure: Optional[OutputBestSampleLigandStructure]
url: str

URL to download the file

formaturi
url_expires_at: datetime

When the presigned URL expires

formatdate-time
archive: Optional[OutputArchive]
url: str

URL to download the file

formaturi
url_expires_at: datetime

When the presigned URL expires

formatdate-time
binding_metrics: Optional[OutputBindingMetrics]
One of the following:
class OutputBindingMetricsLigandProteinBindingMetrics: …
binding_confidence: float

Confidence that binding occurs (0-1). Primary metric for hit discovery.

optimization_score: float

Binding strength ranking score for lead optimization. Higher values indicate stronger predicted binding.

type: Literal["ligand_protein_binding_metrics"]
class OutputBindingMetricsProteinProteinBindingMetrics: …
binding_confidence: float

Confidence that binding occurs (0-1). Primary metric for hit discovery.

type: Literal["protein_protein_binding_metrics"]
started_at: Optional[datetime]
formatdate-time
status: Literal["pending", "running", "succeeded", "failed"]
One of the following:
"pending"
"running"
"succeeded"
"failed"
version: str

Model version used for prediction

workspace_id: str

Workspace ID

idempotency_key: Optional[str]

Client-provided idempotency key

class StructureAndBindingDeleteDataResponse: …
id: str

ID of the resource whose data was deleted

data_deleted: Literal[true]
data_deleted_at: datetime

When the data was deleted

formatdate-time
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

Run
client.predictions.structure_and_binding.run(*, input: structure_and_binding_start_params.Input, model: Literal['boltz-2.1'], root_dir: str | PathLike[str], name: str | None, workspace_id: str | Omit, quiet: bool, poll_interval_seconds: float) -> Path
FunctionSDK workflow