Skip to content
Boltz Boltz Boltz API Docs
Go to Boltz API
API Reference
Protein
Library Screen

Estimate cost for a protein library screen

protein.library_screen.estimate_cost(LibraryScreenEstimateCostParams**kwargs) -> LibraryScreenEstimateCostResponse
POST/compute/v1/protein/library-screen/estimate-cost

Estimate the cost of a protein library screen without creating any resource or consuming GPU.

ParametersExpand Collapse
proteins: Iterable[Protein]

List of protein entries to screen.

entities: Iterable[ProteinEntity]

Entities that make up this protein complex

One of the following:
class ProteinEntityProteinEntity: …
chain_ids: Sequence[str]

Chain IDs for this entity

type: Literal["protein"]
value: str

Amino acid sequence (one-letter codes)

cyclic: Optional[bool]

Whether the sequence is cyclic

modifications: Optional[Iterable[ProteinEntityProteinEntityModification]]

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)

class ProteinEntityRnaEntity: …
chain_ids: Sequence[str]

Chain IDs for this entity

type: Literal["rna"]
value: str

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

cyclic: Optional[bool]

Whether the sequence is cyclic

modifications: Optional[Iterable[ProteinEntityRnaEntityModification]]

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 ProteinEntityDnaEntity: …
chain_ids: Sequence[str]

Chain IDs for this entity

type: Literal["dna"]
value: str

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

cyclic: Optional[bool]

Whether the sequence is cyclic

modifications: Optional[Iterable[ProteinEntityDnaEntityModification]]

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 ProteinEntityLigandCcdEntity: …
chain_ids: Sequence[str]

Chain IDs for this ligand

type: Literal["ligand_ccd"]
value: str

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

class ProteinEntityLigandSmilesEntity: …
chain_ids: Sequence[str]

Chain IDs for this ligand

type: Literal["ligand_smiles"]
value: str

SMILES string representing the ligand

id: Optional[str]

Optional client-provided identifier for this entry

target: Target

Target specification (structure template or template-free)

One of the following:
class TargetStructureTemplateTarget: …

Target defined by an uploaded 3D structure (CIF or PDB file). Only chains included in chain_selection are used.

chain_selection: Dict[str, TargetStructureTemplateTargetChainSelection]

Chains selected from the uploaded structure, keyed by chain ID. Only chains listed here are included in the pipeline run — any chains omitted from this mapping are ignored. Each value defines which residues to keep, which are epitope residues, which are non-binding residues, and which are flexible.

One of the following:
class TargetStructureTemplateTargetChainSelectionStructureTemplateTargetPolymerChainSpec: …

Per-chain specification for a polymer (protein/RNA/DNA) chain in a structure template target.

chain_type: Literal["polymer"]
crop_residues: Union[Iterable[int], Literal["all"]]

0-indexed residue indices to retain from this chain, or ‘all’ to keep all residues. Residues not listed are excluded from the pipeline run.

One of the following:
Iterable[int]

0-indexed residue indices to keep

Literal["all"]
epitope_residues: Optional[Iterable[int]]

0-indexed residue indices where binder contact is desired (the epitope). All indices must be present in crop_residues and must not overlap non_binding_residues.

flexible_residues: Optional[Iterable[int]]

0-indexed residue indices allowed to move during design (e.g. flexible loop regions). All indices must be present in crop_residues.

non_binding_residues: Optional[Iterable[int]]

0-indexed residue indices where binder contact should be discouraged. All indices must be present in crop_residues and must not overlap epitope_residues.

class TargetStructureTemplateTargetChainSelectionStructureTemplateTargetLigandChainSpec: …

Per-chain specification for a ligand chain in a structure template target. The full ligand is always included.

chain_type: Literal["ligand"]
structure: TargetStructureTemplateTargetStructure

How to provide a CIF structure file. URLs are auto-detected; base64 uploads must use chemical/x-cif media type.

One of the following:
class TargetStructureTemplateTargetStructureURLSource: …
type: Literal["url"]
url: str
formaturi
class TargetStructureTemplateTargetStructureCifBase64Source: …
data: str

Base64-encoded CIF file contents

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

Must be chemical/x-cif for CIF files

type: Literal["base64"]
type: Literal["structure_template"]
class TargetNoTemplateTarget: …

Target defined by sequences only, without a 3D structure template

entities: Iterable[TargetNoTemplateTargetEntity]

Entities (proteins, RNA, DNA, ligands) defining the target complex.

One of the following:
class TargetNoTemplateTargetEntityProteinEntity: …
chain_ids: Sequence[str]

Chain IDs for this entity

type: Literal["protein"]
value: str

Amino acid sequence (one-letter codes)

cyclic: Optional[bool]

Whether the sequence is cyclic

modifications: Optional[Iterable[TargetNoTemplateTargetEntityProteinEntityModification]]

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)

class TargetNoTemplateTargetEntityRnaEntity: …
chain_ids: Sequence[str]

Chain IDs for this entity

type: Literal["rna"]
value: str

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

cyclic: Optional[bool]

Whether the sequence is cyclic

modifications: Optional[Iterable[TargetNoTemplateTargetEntityRnaEntityModification]]

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 TargetNoTemplateTargetEntityDnaEntity: …
chain_ids: Sequence[str]

Chain IDs for this entity

type: Literal["dna"]
value: str

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

cyclic: Optional[bool]

Whether the sequence is cyclic

modifications: Optional[Iterable[TargetNoTemplateTargetEntityDnaEntityModification]]

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 TargetNoTemplateTargetEntityLigandCcdEntity: …
chain_ids: Sequence[str]

Chain IDs for this ligand

type: Literal["ligand_ccd"]
value: str

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

class TargetNoTemplateTargetEntityLigandSmilesEntity: …
chain_ids: Sequence[str]

Chain IDs for this ligand

type: Literal["ligand_smiles"]
value: str

SMILES string representing the ligand

type: Literal["no_template"]
bonds: Optional[Iterable[TargetNoTemplateTargetBond]]

Covalent bond constraints between atoms in the target complex. Ligand atom references support CCD atom names and explicitly atom-mapped SMILES atoms.

atom1: TargetNoTemplateTargetBondAtom1

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

One of the following:
class TargetNoTemplateTargetBondAtom1LigandAtom: …

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 TargetNoTemplateTargetBondAtom1PolymerAtom: …
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: TargetNoTemplateTargetBondAtom2

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

One of the following:
class TargetNoTemplateTargetBondAtom2LigandAtom: …

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 TargetNoTemplateTargetBondAtom2PolymerAtom: …
atom_name: str

Standardized atom name (verifiable in CIF file on RCSB)

chain_id: str

Chain ID containing the atom

residue_index: int

0-based residue index

minimum0
type: Literal["polymer_atom"]
constraints: Optional[Iterable[TargetNoTemplateTargetConstraint]]

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

One of the following:
class TargetNoTemplateTargetConstraintPocketConstraint: …

Constrains the binder to interact with specific pocket residues on the target.

binder_chain_id: str

Chain ID of the binder molecule

contact_residues: Dict[str, Iterable[int]]

Binding pocket residues keyed by chain ID. Each key is a chain ID (e.g. “A”) and the value is an array of 0-indexed residue indices that define the pocket on that chain.

max_distance_angstrom: float

Maximum allowed distance in Angstroms between binder and pocket residues. Typical range: 4-8 A.

type: Literal["pocket"]
force: Optional[bool]

Whether to force the constraint

class TargetNoTemplateTargetConstraintContactConstraint: …

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

max_distance_angstrom: float

Maximum distance in Angstroms

token1: TargetNoTemplateTargetConstraintContactConstraintToken1

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

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

Chain ID

residue_index: int

0-based residue index

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

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

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

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

Chain ID

residue_index: int

0-based residue index

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

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

epitope_ligand_chains: Optional[Sequence[str]]

Chain IDs of ligand entities that are part of the binding epitope. Ligands are marked as epitope in full (no residue-level selection).

epitope_residues: Optional[Dict[str, Iterable[int]]]

Polymer chain residues where binder contact is desired (the epitope). Each key is a chain ID of a polymer entity, each value is an array of 0-indexed residue indices. Residues must not overlap non_binding_residues on the same chain.

non_binding_residues: Optional[Dict[str, Iterable[int]]]

Polymer chain residues where binder contact should be discouraged. Each key is a chain ID of a polymer entity, each value is an array of 0-indexed residue indices. Residues must not overlap epitope_residues on the same chain.

idempotency_key: Optional[str]

Client-provided key to prevent duplicate submissions on retries

maxLength255
workspace_id: Optional[str]

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

ReturnsExpand Collapse
class LibraryScreenEstimateCostResponse: …

Estimate response with monetary values encoded as decimal strings to preserve precision.

breakdown: Breakdown

Cost breakdown for the billed application.

application: Literal["structure_and_binding", "small_molecule_design", "small_molecule_library_screen", 4 more]
One of the following:
"structure_and_binding"
"small_molecule_design"
"small_molecule_library_screen"
"protein_design"
"protein_redesign"
"protein_library_screen"
"adme"
cost_per_unit_usd: str

Estimated cost per displayed unit as a decimal string, rounded up to 4 decimal places. This may include token-size multipliers or generation overhead; estimated_cost_usd is the authoritative total.

num_units: int

Number of billable units in the estimate. The unit depends on the endpoint: samples for structure-and-binding, molecules for ADME, and requested proteins or molecules for design/screen endpoints.

disclaimer: str
estimated_cost_usd: str

Estimated total cost as a decimal string

Estimate cost for a protein library screen

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.protein.library_screen.estimate_cost(
    proteins=[{
        "entities": [{
            "chain_ids": ["string"],
            "type": "protein",
            "value": "value",
        }]
    }],
    target={
        "chain_selection": {
            "A": {
                "chain_type": "polymer",
                "crop_residues": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12],
            }
        },
        "structure": {
            "type": "url",
            "url": "https://example.com",
        },
        "type": "structure_template",
    },
)
print(response.breakdown)
{
  "breakdown": {
    "application": "structure_and_binding",
    "cost_per_unit_usd": "0.0500",
    "num_units": 1
  },
  "disclaimer": "This is an estimate only and may differ from your actual charges. Final billing is based on exact token counts computed at run time. For large library screens, the estimate is extrapolated from a sample and may be less accurate for highly variable inputs.",
  "estimated_cost_usd": "0.0500"
}
Returns Examples
{
  "breakdown": {
    "application": "structure_and_binding",
    "cost_per_unit_usd": "0.0500",
    "num_units": 1
  },
  "disclaimer": "This is an estimate only and may differ from your actual charges. Final billing is based on exact token counts computed at run time. For large library screens, the estimate is extrapolated from a sample and may be less accurate for highly variable inputs.",
  "estimated_cost_usd": "0.0500"
}