# Predictions

# Structure And Binding

## Start

`predictions.structure_and_binding.start(StructureAndBindingStartParams**kwargs)  -> StructureAndBindingStartResponse`

**post** `/compute/v1/predictions/structure-and-binding`

Submit a prediction job that produces 3D structure coordinates and confidence scores for the input molecular complex, with optional binding metrics.

### Parameters

- `input: Input`

  - `entities: Iterable[InputEntity]`

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

    - `class InputEntityProteinEntity: …`

      - `chain_ids: SequenceNotStr[str]`

        Chain IDs for this entity

      - `type: Literal["protein"]`

        - `"protein"`

      - `value: str`

        Amino acid sequence (one-letter codes)

      - `cyclic: Optional[bool]`

        Whether the sequence is cyclic

      - `modifications: Optional[Iterable[InputEntityProteinEntityModification]]`

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

        - `class InputEntityProteinEntityModificationCcdModification: …`

          - `residue_index: int`

            0-based index of the residue to modify

          - `type: Literal["ccd"]`

            - `"ccd"`

          - `value: str`

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

        - `class InputEntityProteinEntityModificationSmilesModification: …`

          - `residue_index: int`

            0-based index of the residue to modify

          - `type: Literal["smiles"]`

            - `"smiles"`

          - `value: str`

            SMILES string for the modification

    - `class InputEntityRnaEntity: …`

      - `chain_ids: SequenceNotStr[str]`

        Chain IDs for this entity

      - `type: Literal["rna"]`

        - `"rna"`

      - `value: str`

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

      - `cyclic: Optional[bool]`

        Whether the sequence is cyclic

      - `modifications: Optional[Iterable[InputEntityRnaEntityModification]]`

        Chemical modifications. Optional; defaults to an empty list when omitted.

        - `class InputEntityRnaEntityModificationCcdModification: …`

          - `residue_index: int`

            0-based index of the residue to modify

          - `type: Literal["ccd"]`

            - `"ccd"`

          - `value: str`

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

        - `class InputEntityRnaEntityModificationSmilesModification: …`

          - `residue_index: int`

            0-based index of the residue to modify

          - `type: Literal["smiles"]`

            - `"smiles"`

          - `value: str`

            SMILES string for the modification

    - `class InputEntityDnaEntity: …`

      - `chain_ids: SequenceNotStr[str]`

        Chain IDs for this entity

      - `type: Literal["dna"]`

        - `"dna"`

      - `value: str`

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

      - `cyclic: Optional[bool]`

        Whether the sequence is cyclic

      - `modifications: Optional[Iterable[InputEntityDnaEntityModification]]`

        Chemical modifications. Optional; defaults to an empty list when omitted.

        - `class InputEntityDnaEntityModificationCcdModification: …`

          - `residue_index: int`

            0-based index of the residue to modify

          - `type: Literal["ccd"]`

            - `"ccd"`

          - `value: str`

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

        - `class InputEntityDnaEntityModificationSmilesModification: …`

          - `residue_index: int`

            0-based index of the residue to modify

          - `type: Literal["smiles"]`

            - `"smiles"`

          - `value: str`

            SMILES string for the modification

    - `class InputEntityLigandCcdEntity: …`

      - `chain_ids: SequenceNotStr[str]`

        Chain IDs for this ligand

      - `type: Literal["ligand_ccd"]`

        - `"ligand_ccd"`

      - `value: str`

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

    - `class InputEntityLigandSmilesEntity: …`

      - `chain_ids: SequenceNotStr[str]`

        Chain IDs for this ligand

      - `type: Literal["ligand_smiles"]`

        - `"ligand_smiles"`

      - `value: str`

        SMILES string representing the ligand

  - `binding: Optional[InputBinding]`

    - `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"]`

        - `"ligand_protein_binding"`

    - `class InputBindingProteinProteinBinding: …`

      - `binder_chain_ids: SequenceNotStr[str]`

        Chain IDs of the protein binders

      - `type: Literal["protein_protein_binding"]`

        - `"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.

      - `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"]`

          - `"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

        - `type: Literal["polymer_atom"]`

          - `"polymer_atom"`

    - `atom2: InputBondAtom2`

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

      - `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"]`

          - `"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

        - `type: Literal["polymer_atom"]`

          - `"polymer_atom"`

  - `constraints: Optional[Iterable[InputConstraint]]`

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

    - `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"]`

        - `"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.

        - `class InputConstraintContactConstraintToken1PolymerContactToken: …`

          - `chain_id: str`

            Chain ID

          - `residue_index: int`

            0-based residue index

          - `type: Literal["polymer_contact"]`

            - `"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"]`

            - `"ligand_contact"`

      - `token2: InputConstraintContactConstraintToken2`

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

        - `class InputConstraintContactConstraintToken2PolymerContactToken: …`

          - `chain_id: str`

            Chain ID

          - `residue_index: int`

            0-based residue index

          - `type: Literal["polymer_contact"]`

            - `"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"]`

            - `"ligand_contact"`

      - `type: Literal["contact"]`

        - `"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.

    - `sampling_steps: Optional[int]`

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

    - `step_scale: Optional[float]`

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

  - `num_samples: Optional[int]`

    Number of structure samples to generate

- `model: Literal["boltz-2.1"]`

  Model to use for prediction

  - `"boltz-2.1"`

- `idempotency_key: Optional[str]`

  Client-provided key to prevent duplicate submissions on retries

- `workspace_id: Optional[str]`

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

### Returns

- `class StructureAndBindingStartResponse: …`

  - `id: str`

    Unique prediction identifier

  - `completed_at: Optional[datetime]`

  - `created_at: datetime`

  - `data_deleted_at: Optional[datetime]`

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

  - `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.

  - `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.

      - `class InputEntityProteinEntityResponse: …`

        - `chain_ids: List[str]`

          Chain IDs for this entity

        - `type: Literal["protein"]`

          - `"protein"`

        - `value: str`

          Amino acid sequence (one-letter codes)

        - `cyclic: Optional[bool]`

          Whether the sequence is cyclic

        - `modifications: Optional[List[InputEntityProteinEntityResponseModification]]`

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

          - `class InputEntityProteinEntityResponseModificationCcdModificationResponse: …`

            - `residue_index: int`

              0-based index of the residue to modify

            - `type: Literal["ccd"]`

              - `"ccd"`

            - `value: str`

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

          - `class InputEntityProteinEntityResponseModificationSmilesModificationResponse: …`

            - `residue_index: int`

              0-based index of the residue to modify

            - `type: Literal["smiles"]`

              - `"smiles"`

            - `value: str`

              SMILES string for the modification

      - `class InputEntityRnaEntityResponse: …`

        - `chain_ids: List[str]`

          Chain IDs for this entity

        - `type: Literal["rna"]`

          - `"rna"`

        - `value: str`

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

        - `cyclic: Optional[bool]`

          Whether the sequence is cyclic

        - `modifications: Optional[List[InputEntityRnaEntityResponseModification]]`

          Chemical modifications. Optional; defaults to an empty list when omitted.

          - `class InputEntityRnaEntityResponseModificationCcdModificationResponse: …`

            - `residue_index: int`

              0-based index of the residue to modify

            - `type: Literal["ccd"]`

              - `"ccd"`

            - `value: str`

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

          - `class InputEntityRnaEntityResponseModificationSmilesModificationResponse: …`

            - `residue_index: int`

              0-based index of the residue to modify

            - `type: Literal["smiles"]`

              - `"smiles"`

            - `value: str`

              SMILES string for the modification

      - `class InputEntityDnaEntityResponse: …`

        - `chain_ids: List[str]`

          Chain IDs for this entity

        - `type: Literal["dna"]`

          - `"dna"`

        - `value: str`

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

        - `cyclic: Optional[bool]`

          Whether the sequence is cyclic

        - `modifications: Optional[List[InputEntityDnaEntityResponseModification]]`

          Chemical modifications. Optional; defaults to an empty list when omitted.

          - `class InputEntityDnaEntityResponseModificationCcdModificationResponse: …`

            - `residue_index: int`

              0-based index of the residue to modify

            - `type: Literal["ccd"]`

              - `"ccd"`

            - `value: str`

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

          - `class InputEntityDnaEntityResponseModificationSmilesModificationResponse: …`

            - `residue_index: int`

              0-based index of the residue to modify

            - `type: Literal["smiles"]`

              - `"smiles"`

            - `value: str`

              SMILES string for the modification

      - `class InputEntityLigandCcdEntityResponse: …`

        - `chain_ids: List[str]`

          Chain IDs for this ligand

        - `type: Literal["ligand_ccd"]`

          - `"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"]`

          - `"ligand_smiles"`

        - `value: str`

          SMILES string representing the ligand

    - `binding: Optional[InputBinding]`

      - `class InputBindingLigandProteinBindingResponse: …`

        - `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"]`

          - `"ligand_protein_binding"`

      - `class InputBindingProteinProteinBindingResponse: …`

        - `binder_chain_ids: List[str]`

          Chain IDs of the protein binders

        - `type: Literal["protein_protein_binding"]`

          - `"protein_protein_binding"`

    - `bonds: Optional[List[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.

        - `class InputBondAtom1LigandAtomResponse: …`

          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"]`

            - `"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

          - `type: Literal["polymer_atom"]`

            - `"polymer_atom"`

      - `atom2: InputBondAtom2`

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

        - `class InputBondAtom2LigandAtomResponse: …`

          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"]`

            - `"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

          - `type: Literal["polymer_atom"]`

            - `"polymer_atom"`

    - `constraints: Optional[List[InputConstraint]]`

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

      - `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"]`

          - `"pocket"`

        - `force: Optional[bool]`

          Whether to force the constraint

      - `class InputConstraintContactConstraintResponse: …`

        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: InputConstraintContactConstraintResponseToken1`

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

          - `class InputConstraintContactConstraintResponseToken1PolymerContactTokenResponse: …`

            - `chain_id: str`

              Chain ID

            - `residue_index: int`

              0-based residue index

            - `type: Literal["polymer_contact"]`

              - `"polymer_contact"`

          - `class InputConstraintContactConstraintResponseToken1LigandContactTokenResponse: …`

            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"]`

              - `"ligand_contact"`

        - `token2: InputConstraintContactConstraintResponseToken2`

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

          - `class InputConstraintContactConstraintResponseToken2PolymerContactTokenResponse: …`

            - `chain_id: str`

              Chain ID

            - `residue_index: int`

              0-based residue index

            - `type: Literal["polymer_contact"]`

              - `"polymer_contact"`

          - `class InputConstraintContactConstraintResponseToken2LigandContactTokenResponse: …`

            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"]`

              - `"ligand_contact"`

        - `type: Literal["contact"]`

          - `"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.

      - `sampling_steps: Optional[int]`

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

      - `step_scale: Optional[float]`

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

    - `num_samples: Optional[int]`

      Number of structure samples to generate

  - `livemode: bool`

    Whether this resource was created with a live API key.

  - `model: Literal["boltz-2.1"]`

    Model used for prediction

    - `"boltz-2.1"`

  - `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

        - `url_expires_at: datetime`

          When the presigned URL expires

    - `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

        - `url_expires_at: datetime`

          When the presigned URL expires

    - `archive: Optional[OutputArchive]`

      - `url: str`

        URL to download the file

      - `url_expires_at: datetime`

        When the presigned URL expires

    - `binding_metrics: Optional[OutputBindingMetrics]`

      - `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"]`

          - `"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"]`

          - `"protein_protein_binding_metrics"`

  - `started_at: Optional[datetime]`

  - `status: Literal["pending", "running", "succeeded", "failed"]`

    - `"pending"`

    - `"running"`

    - `"succeeded"`

    - `"failed"`

  - `version: str`

    Model version used for prediction

  - `workspace_id: str`

    Workspace ID

  - `idempotency_key: Optional[str]`

    Client-provided idempotency key

### Example

```python
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.start(
    input={
        "entities": [{
            "chain_ids": ["string"],
            "type": "protein",
            "value": "value",
        }]
    },
    model="boltz-2.1",
)
print(response.id)
```

## List

`predictions.structure_and_binding.list(StructureAndBindingListParams**kwargs)  -> SyncCursorPage[StructureAndBindingListResponse]`

**get** `/compute/v1/predictions/structure-and-binding`

List structure and binding predictions, optionally filtered by workspace

### Parameters

- `after_id: Optional[str]`

  Return results after this ID

- `before_id: Optional[str]`

  Return results before this ID

- `limit: Optional[int]`

  Max items to return. Defaults to 100.

- `workspace_id: Optional[str]`

  Filter by workspace ID. Only used with admin API keys. If not provided, defaults to the workspace associated with the API key, or the default workspace for admin keys.

### Returns

- `class StructureAndBindingListResponse: …`

  - `id: str`

    Unique prediction identifier

  - `completed_at: Optional[datetime]`

  - `created_at: datetime`

  - `data_deleted_at: Optional[datetime]`

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

  - `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.

  - `livemode: bool`

    Whether this resource was created with a live API key.

  - `model: Literal["boltz-2.1"]`

    Model used for prediction

    - `"boltz-2.1"`

  - `started_at: Optional[datetime]`

  - `status: Literal["pending", "running", "succeeded", "failed"]`

    - `"pending"`

    - `"running"`

    - `"succeeded"`

    - `"failed"`

  - `version: str`

    Model version used for prediction

  - `workspace_id: str`

    Workspace ID

  - `idempotency_key: Optional[str]`

    Client-provided idempotency key

### Example

```python
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
)
page = client.predictions.structure_and_binding.list()
page = page.data[0]
print(page.id)
```

## Retrieve

`predictions.structure_and_binding.retrieve(strid, StructureAndBindingRetrieveParams**kwargs)  -> StructureAndBindingRetrieveResponse`

**get** `/compute/v1/predictions/structure-and-binding/{id}`

Retrieve a prediction by ID, including its status and results.

### Parameters

- `id: str`

- `workspace_id: Optional[str]`

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

### Returns

- `class StructureAndBindingRetrieveResponse: …`

  - `id: str`

    Unique prediction identifier

  - `completed_at: Optional[datetime]`

  - `created_at: datetime`

  - `data_deleted_at: Optional[datetime]`

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

  - `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.

  - `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.

      - `class InputEntityProteinEntityResponse: …`

        - `chain_ids: List[str]`

          Chain IDs for this entity

        - `type: Literal["protein"]`

          - `"protein"`

        - `value: str`

          Amino acid sequence (one-letter codes)

        - `cyclic: Optional[bool]`

          Whether the sequence is cyclic

        - `modifications: Optional[List[InputEntityProteinEntityResponseModification]]`

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

          - `class InputEntityProteinEntityResponseModificationCcdModificationResponse: …`

            - `residue_index: int`

              0-based index of the residue to modify

            - `type: Literal["ccd"]`

              - `"ccd"`

            - `value: str`

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

          - `class InputEntityProteinEntityResponseModificationSmilesModificationResponse: …`

            - `residue_index: int`

              0-based index of the residue to modify

            - `type: Literal["smiles"]`

              - `"smiles"`

            - `value: str`

              SMILES string for the modification

      - `class InputEntityRnaEntityResponse: …`

        - `chain_ids: List[str]`

          Chain IDs for this entity

        - `type: Literal["rna"]`

          - `"rna"`

        - `value: str`

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

        - `cyclic: Optional[bool]`

          Whether the sequence is cyclic

        - `modifications: Optional[List[InputEntityRnaEntityResponseModification]]`

          Chemical modifications. Optional; defaults to an empty list when omitted.

          - `class InputEntityRnaEntityResponseModificationCcdModificationResponse: …`

            - `residue_index: int`

              0-based index of the residue to modify

            - `type: Literal["ccd"]`

              - `"ccd"`

            - `value: str`

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

          - `class InputEntityRnaEntityResponseModificationSmilesModificationResponse: …`

            - `residue_index: int`

              0-based index of the residue to modify

            - `type: Literal["smiles"]`

              - `"smiles"`

            - `value: str`

              SMILES string for the modification

      - `class InputEntityDnaEntityResponse: …`

        - `chain_ids: List[str]`

          Chain IDs for this entity

        - `type: Literal["dna"]`

          - `"dna"`

        - `value: str`

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

        - `cyclic: Optional[bool]`

          Whether the sequence is cyclic

        - `modifications: Optional[List[InputEntityDnaEntityResponseModification]]`

          Chemical modifications. Optional; defaults to an empty list when omitted.

          - `class InputEntityDnaEntityResponseModificationCcdModificationResponse: …`

            - `residue_index: int`

              0-based index of the residue to modify

            - `type: Literal["ccd"]`

              - `"ccd"`

            - `value: str`

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

          - `class InputEntityDnaEntityResponseModificationSmilesModificationResponse: …`

            - `residue_index: int`

              0-based index of the residue to modify

            - `type: Literal["smiles"]`

              - `"smiles"`

            - `value: str`

              SMILES string for the modification

      - `class InputEntityLigandCcdEntityResponse: …`

        - `chain_ids: List[str]`

          Chain IDs for this ligand

        - `type: Literal["ligand_ccd"]`

          - `"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"]`

          - `"ligand_smiles"`

        - `value: str`

          SMILES string representing the ligand

    - `binding: Optional[InputBinding]`

      - `class InputBindingLigandProteinBindingResponse: …`

        - `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"]`

          - `"ligand_protein_binding"`

      - `class InputBindingProteinProteinBindingResponse: …`

        - `binder_chain_ids: List[str]`

          Chain IDs of the protein binders

        - `type: Literal["protein_protein_binding"]`

          - `"protein_protein_binding"`

    - `bonds: Optional[List[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.

        - `class InputBondAtom1LigandAtomResponse: …`

          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"]`

            - `"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

          - `type: Literal["polymer_atom"]`

            - `"polymer_atom"`

      - `atom2: InputBondAtom2`

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

        - `class InputBondAtom2LigandAtomResponse: …`

          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"]`

            - `"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

          - `type: Literal["polymer_atom"]`

            - `"polymer_atom"`

    - `constraints: Optional[List[InputConstraint]]`

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

      - `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"]`

          - `"pocket"`

        - `force: Optional[bool]`

          Whether to force the constraint

      - `class InputConstraintContactConstraintResponse: …`

        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: InputConstraintContactConstraintResponseToken1`

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

          - `class InputConstraintContactConstraintResponseToken1PolymerContactTokenResponse: …`

            - `chain_id: str`

              Chain ID

            - `residue_index: int`

              0-based residue index

            - `type: Literal["polymer_contact"]`

              - `"polymer_contact"`

          - `class InputConstraintContactConstraintResponseToken1LigandContactTokenResponse: …`

            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"]`

              - `"ligand_contact"`

        - `token2: InputConstraintContactConstraintResponseToken2`

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

          - `class InputConstraintContactConstraintResponseToken2PolymerContactTokenResponse: …`

            - `chain_id: str`

              Chain ID

            - `residue_index: int`

              0-based residue index

            - `type: Literal["polymer_contact"]`

              - `"polymer_contact"`

          - `class InputConstraintContactConstraintResponseToken2LigandContactTokenResponse: …`

            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"]`

              - `"ligand_contact"`

        - `type: Literal["contact"]`

          - `"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.

      - `sampling_steps: Optional[int]`

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

      - `step_scale: Optional[float]`

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

    - `num_samples: Optional[int]`

      Number of structure samples to generate

  - `livemode: bool`

    Whether this resource was created with a live API key.

  - `model: Literal["boltz-2.1"]`

    Model used for prediction

    - `"boltz-2.1"`

  - `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

        - `url_expires_at: datetime`

          When the presigned URL expires

    - `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

        - `url_expires_at: datetime`

          When the presigned URL expires

    - `archive: Optional[OutputArchive]`

      - `url: str`

        URL to download the file

      - `url_expires_at: datetime`

        When the presigned URL expires

    - `binding_metrics: Optional[OutputBindingMetrics]`

      - `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"]`

          - `"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"]`

          - `"protein_protein_binding_metrics"`

  - `started_at: Optional[datetime]`

  - `status: Literal["pending", "running", "succeeded", "failed"]`

    - `"pending"`

    - `"running"`

    - `"succeeded"`

    - `"failed"`

  - `version: str`

    Model version used for prediction

  - `workspace_id: str`

    Workspace ID

  - `idempotency_key: Optional[str]`

    Client-provided idempotency key

### Example

```python
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
)
structure_and_binding = client.predictions.structure_and_binding.retrieve(
    id="sab_pred_2X7Ab9Cd3Ef6Gh1JkLmN",
)
print(structure_and_binding.id)
```

## Delete Data

`predictions.structure_and_binding.delete_data(strid)  -> StructureAndBindingDeleteDataResponse`

**post** `/compute/v1/predictions/structure-and-binding/{id}/delete-data`

Permanently delete the input, output, and result data associated with this prediction. The prediction record itself is retained with a `data_deleted_at` timestamp. This action is irreversible.

### Parameters

- `id: str`

### Returns

- `class StructureAndBindingDeleteDataResponse: …`

  - `id: str`

    ID of the resource whose data was deleted

  - `data_deleted: Literal[true]`

    - `true`

  - `data_deleted_at: datetime`

    When the data was deleted

### Example

```python
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.delete_data(
    "sab_pred_2X7Ab9Cd3Ef6Gh1JkLmN",
)
print(response.id)
```

## Estimate Cost

`predictions.structure_and_binding.estimate_cost(StructureAndBindingEstimateCostParams**kwargs)  -> StructureAndBindingEstimateCostResponse`

**post** `/compute/v1/predictions/structure-and-binding/estimate-cost`

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

### Parameters

- `input: Input`

  - `entities: Iterable[InputEntity]`

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

    - `class InputEntityProteinEntity: …`

      - `chain_ids: SequenceNotStr[str]`

        Chain IDs for this entity

      - `type: Literal["protein"]`

        - `"protein"`

      - `value: str`

        Amino acid sequence (one-letter codes)

      - `cyclic: Optional[bool]`

        Whether the sequence is cyclic

      - `modifications: Optional[Iterable[InputEntityProteinEntityModification]]`

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

        - `class InputEntityProteinEntityModificationCcdModification: …`

          - `residue_index: int`

            0-based index of the residue to modify

          - `type: Literal["ccd"]`

            - `"ccd"`

          - `value: str`

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

        - `class InputEntityProteinEntityModificationSmilesModification: …`

          - `residue_index: int`

            0-based index of the residue to modify

          - `type: Literal["smiles"]`

            - `"smiles"`

          - `value: str`

            SMILES string for the modification

    - `class InputEntityRnaEntity: …`

      - `chain_ids: SequenceNotStr[str]`

        Chain IDs for this entity

      - `type: Literal["rna"]`

        - `"rna"`

      - `value: str`

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

      - `cyclic: Optional[bool]`

        Whether the sequence is cyclic

      - `modifications: Optional[Iterable[InputEntityRnaEntityModification]]`

        Chemical modifications. Optional; defaults to an empty list when omitted.

        - `class InputEntityRnaEntityModificationCcdModification: …`

          - `residue_index: int`

            0-based index of the residue to modify

          - `type: Literal["ccd"]`

            - `"ccd"`

          - `value: str`

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

        - `class InputEntityRnaEntityModificationSmilesModification: …`

          - `residue_index: int`

            0-based index of the residue to modify

          - `type: Literal["smiles"]`

            - `"smiles"`

          - `value: str`

            SMILES string for the modification

    - `class InputEntityDnaEntity: …`

      - `chain_ids: SequenceNotStr[str]`

        Chain IDs for this entity

      - `type: Literal["dna"]`

        - `"dna"`

      - `value: str`

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

      - `cyclic: Optional[bool]`

        Whether the sequence is cyclic

      - `modifications: Optional[Iterable[InputEntityDnaEntityModification]]`

        Chemical modifications. Optional; defaults to an empty list when omitted.

        - `class InputEntityDnaEntityModificationCcdModification: …`

          - `residue_index: int`

            0-based index of the residue to modify

          - `type: Literal["ccd"]`

            - `"ccd"`

          - `value: str`

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

        - `class InputEntityDnaEntityModificationSmilesModification: …`

          - `residue_index: int`

            0-based index of the residue to modify

          - `type: Literal["smiles"]`

            - `"smiles"`

          - `value: str`

            SMILES string for the modification

    - `class InputEntityLigandCcdEntity: …`

      - `chain_ids: SequenceNotStr[str]`

        Chain IDs for this ligand

      - `type: Literal["ligand_ccd"]`

        - `"ligand_ccd"`

      - `value: str`

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

    - `class InputEntityLigandSmilesEntity: …`

      - `chain_ids: SequenceNotStr[str]`

        Chain IDs for this ligand

      - `type: Literal["ligand_smiles"]`

        - `"ligand_smiles"`

      - `value: str`

        SMILES string representing the ligand

  - `binding: Optional[InputBinding]`

    - `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"]`

        - `"ligand_protein_binding"`

    - `class InputBindingProteinProteinBinding: …`

      - `binder_chain_ids: SequenceNotStr[str]`

        Chain IDs of the protein binders

      - `type: Literal["protein_protein_binding"]`

        - `"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.

      - `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"]`

          - `"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

        - `type: Literal["polymer_atom"]`

          - `"polymer_atom"`

    - `atom2: InputBondAtom2`

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

      - `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"]`

          - `"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

        - `type: Literal["polymer_atom"]`

          - `"polymer_atom"`

  - `constraints: Optional[Iterable[InputConstraint]]`

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

    - `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"]`

        - `"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.

        - `class InputConstraintContactConstraintToken1PolymerContactToken: …`

          - `chain_id: str`

            Chain ID

          - `residue_index: int`

            0-based residue index

          - `type: Literal["polymer_contact"]`

            - `"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"]`

            - `"ligand_contact"`

      - `token2: InputConstraintContactConstraintToken2`

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

        - `class InputConstraintContactConstraintToken2PolymerContactToken: …`

          - `chain_id: str`

            Chain ID

          - `residue_index: int`

            0-based residue index

          - `type: Literal["polymer_contact"]`

            - `"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"]`

            - `"ligand_contact"`

      - `type: Literal["contact"]`

        - `"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.

    - `sampling_steps: Optional[int]`

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

    - `step_scale: Optional[float]`

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

  - `num_samples: Optional[int]`

    Number of structure samples to generate

- `model: Literal["boltz-2.1"]`

  Model to use for prediction

  - `"boltz-2.1"`

- `idempotency_key: Optional[str]`

  Client-provided key to prevent duplicate submissions on retries

- `workspace_id: Optional[str]`

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

### Returns

- `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", 3 more]`

      - `"structure_and_binding"`

      - `"small_molecule_design"`

      - `"small_molecule_library_screen"`

      - `"protein_design"`

      - `"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 units shown for the estimate. For structure-and-binding, this is the requested number of samples. For protein and small-molecule design/screen endpoints, this is the requested number of proteins or molecules.

  - `disclaimer: str`

  - `estimated_cost_usd: str`

    Estimated total cost as a decimal string

### Example

```python
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)
```