Retrieve a structure and binding prediction

predictions.structure_and_binding.retrieve(, ) -> StructureAndBindingRetrieveResponse

GET/compute/v1/predictions/structure-and-binding/{id}

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

ParametersExpand Collapse

id: str

workspace_id: Optional[str]

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

ReturnsExpand Collapse

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

Accepts one of the following:

class InputEntityProteinEntityResponse: …

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

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

Accepts one of the following:

class InputEntityProteinEntityResponseModificationCcdModificationResponse: …

residue_index: int

0-based index of the residue to modify

minimum0

type: Literal["ccd"]

value: str

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

class InputEntityProteinEntityResponseModificationSmilesModificationResponse: …

residue_index: int

0-based index of the residue to modify

minimum0

type: Literal["smiles"]

value: str

SMILES string for the modification

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

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

Accepts one of the following:

class InputEntityRnaEntityResponseModificationCcdModificationResponse: …

residue_index: int

0-based index of the residue to modify

minimum0

type: Literal["ccd"]

value: str

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

class InputEntityRnaEntityResponseModificationSmilesModificationResponse: …

residue_index: int

0-based index of the residue to modify

minimum0

type: Literal["smiles"]

value: str

SMILES string for the modification

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

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

Accepts one of the following:

class InputEntityDnaEntityResponseModificationCcdModificationResponse: …

residue_index: int

0-based index of the residue to modify

minimum0

type: Literal["ccd"]

value: str

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

class InputEntityDnaEntityResponseModificationSmilesModificationResponse: …

residue_index: int

0-based index of the residue to modify

minimum0

type: Literal["smiles"]

value: str

SMILES string for the modification

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]

Accepts one of the following:

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

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

Accepts one of the following:

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

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. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

Accepts one of the following:

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

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). Atom-level ligand references currently support ligand_ccd only; ligand_smiles is unsupported.

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

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.

Accepts 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. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

atom_name: str

Atom name. Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

chain_id: str

Chain ID

type: Literal["ligand_contact"]

token2: InputConstraintContactConstraintResponseToken2

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

Accepts 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. Atom-level ligand references currently support ligand_ccd entities only; ligand_smiles is unsupported.

atom_name: str

Atom name. Atom-level references to ligand_smiles entities are currently unsupported; use ligand_ccd instead.

chain_id: str

Chain ID

type: Literal["ligand_contact"]

type: Literal["contact"]

force: Optional[bool]

Whether to force the constraint

model_options: Optional[InputModelOptions]

recycling_steps: Optional[int]

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

minimum1

sampling_steps: Optional[int]

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

minimum1

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

minimum1

maximum10

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

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

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]

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

Accepts 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

Retrieve a structure and binding prediction

import os
from boltz_api import Boltz

client = Boltz(
    api_key=os.environ.get("BOLTZ_API_KEY"),  # This is the default and can be omitted
)
structure_and_binding = client.predictions.structure_and_binding.retrieve(
    id="sab_pred_2X7Ab9Cd3Ef6Gh1JkLmN",
)
print(structure_and_binding.id)

{
  "id": "sab_pred_2X7Ab9Cd3Ef6Gh1JkLmN",
  "completed_at": "2019-12-27T18:11:19.117Z",
  "created_at": "2019-12-27T18:11:19.117Z",
  "data_deleted_at": "2019-12-27T18:11:19.117Z",
  "error": {
    "code": "code",
    "message": "message",
    "details": {}
  },
  "expires_at": "2019-12-27T18:11:19.117Z",
  "input": {
    "entities": [
      {
        "chain_ids": [
          "string"
        ],
        "type": "protein",
        "value": "value",
        "cyclic": true,
        "modifications": [
          {
            "residue_index": 0,
            "type": "ccd",
            "value": "value"
          }
        ]
      }
    ],
    "binding": {
      "binder_chain_id": "binder_chain_id",
      "type": "ligand_protein_binding"
    },
    "bonds": [
      {
        "atom1": {
          "atom_name": "atom_name",
          "chain_id": "chain_id",
          "type": "ligand_atom"
        },
        "atom2": {
          "atom_name": "atom_name",
          "chain_id": "chain_id",
          "type": "ligand_atom"
        }
      }
    ],
    "constraints": [
      {
        "binder_chain_id": "binder_chain_id",
        "contact_residues": {
          "A": [
            42,
            43,
            44,
            67,
            68,
            69
          ]
        },
        "max_distance_angstrom": 0,
        "type": "pocket",
        "force": true
      }
    ],
    "model_options": {
      "recycling_steps": 1,
      "sampling_steps": 1,
      "step_scale": 1.3
    },
    "num_samples": 1
  },
  "livemode": true,
  "model": "boltz-2.1",
  "output": {
    "all_sample_results": [
      {
        "metrics": {
          "complex_ipde": 0,
          "complex_iplddt": 0,
          "complex_pde": 0,
          "complex_plddt": 0,
          "iptm": 0,
          "ligand_iptm": 0,
          "protein_iptm": 0,
          "ptm": 0,
          "structure_confidence": 0
        },
        "structure": {
          "url": "https://example.com",
          "url_expires_at": "2019-12-27T18:11:19.117Z"
        }
      }
    ],
    "best_sample": {
      "metrics": {
        "complex_ipde": 0,
        "complex_iplddt": 0,
        "complex_pde": 0,
        "complex_plddt": 0,
        "iptm": 0,
        "ligand_iptm": 0,
        "protein_iptm": 0,
        "ptm": 0,
        "structure_confidence": 0
      },
      "structure": {
        "url": "https://example.com",
        "url_expires_at": "2019-12-27T18:11:19.117Z"
      }
    },
    "archive": {
      "url": "https://example.com",
      "url_expires_at": "2019-12-27T18:11:19.117Z"
    },
    "binding_metrics": {
      "binding_confidence": 0,
      "optimization_score": 0,
      "type": "ligand_protein_binding_metrics"
    }
  },
  "started_at": "2019-12-27T18:11:19.117Z",
  "status": "pending",
  "version": "version",
  "workspace_id": "workspace_id",
  "idempotency_key": "idempotency_key"
}

Returns Examples

{
  "id": "sab_pred_2X7Ab9Cd3Ef6Gh1JkLmN",
  "completed_at": "2019-12-27T18:11:19.117Z",
  "created_at": "2019-12-27T18:11:19.117Z",
  "data_deleted_at": "2019-12-27T18:11:19.117Z",
  "error": {
    "code": "code",
    "message": "message",
    "details": {}
  },
  "expires_at": "2019-12-27T18:11:19.117Z",
  "input": {
    "entities": [
      {
        "chain_ids": [
          "string"
        ],
        "type": "protein",
        "value": "value",
        "cyclic": true,
        "modifications": [
          {
            "residue_index": 0,
            "type": "ccd",
            "value": "value"
          }
        ]
      }
    ],
    "binding": {
      "binder_chain_id": "binder_chain_id",
      "type": "ligand_protein_binding"
    },
    "bonds": [
      {
        "atom1": {
          "atom_name": "atom_name",
          "chain_id": "chain_id",
          "type": "ligand_atom"
        },
        "atom2": {
          "atom_name": "atom_name",
          "chain_id": "chain_id",
          "type": "ligand_atom"
        }
      }
    ],
    "constraints": [
      {
        "binder_chain_id": "binder_chain_id",
        "contact_residues": {
          "A": [
            42,
            43,
            44,
            67,
            68,
            69
          ]
        },
        "max_distance_angstrom": 0,
        "type": "pocket",
        "force": true
      }
    ],
    "model_options": {
      "recycling_steps": 1,
      "sampling_steps": 1,
      "step_scale": 1.3
    },
    "num_samples": 1
  },
  "livemode": true,
  "model": "boltz-2.1",
  "output": {
    "all_sample_results": [
      {
        "metrics": {
          "complex_ipde": 0,
          "complex_iplddt": 0,
          "complex_pde": 0,
          "complex_plddt": 0,
          "iptm": 0,
          "ligand_iptm": 0,
          "protein_iptm": 0,
          "ptm": 0,
          "structure_confidence": 0
        },
        "structure": {
          "url": "https://example.com",
          "url_expires_at": "2019-12-27T18:11:19.117Z"
        }
      }
    ],
    "best_sample": {
      "metrics": {
        "complex_ipde": 0,
        "complex_iplddt": 0,
        "complex_pde": 0,
        "complex_plddt": 0,
        "iptm": 0,
        "ligand_iptm": 0,
        "protein_iptm": 0,
        "ptm": 0,
        "structure_confidence": 0
      },
      "structure": {
        "url": "https://example.com",
        "url_expires_at": "2019-12-27T18:11:19.117Z"
      }
    },
    "archive": {
      "url": "https://example.com",
      "url_expires_at": "2019-12-27T18:11:19.117Z"
    },
    "binding_metrics": {
      "binding_confidence": 0,
      "optimization_score": 0,
      "type": "ligand_protein_binding_metrics"
    }
  },
  "started_at": "2019-12-27T18:11:19.117Z",
  "status": "pending",
  "version": "version",
  "workspace_id": "workspace_id",
  "idempotency_key": "idempotency_key"
}