## Retrieve

`protein.library_screen.retrieve(strid, LibraryScreenRetrieveParams**kwargs)  -> LibraryScreenRetrieveResponse`

**get** `/compute/v1/protein/library-screen/{id}`

Retrieve a library screen by ID, including progress and status

### Parameters

- `id: str`

- `workspace_id: Optional[str]`

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

### Returns

- `class LibraryScreenRetrieveResponse: …`

  A protein library screening engine run

  - `id: str`

    Unique ProteinLibraryScreen identifier

  - `completed_at: Optional[datetime]`

  - `created_at: datetime`

  - `data_deleted_at: Optional[datetime]`

    When the input, output, and result data was permanently deleted. Null if data has not been deleted.

  - `engine: Literal["boltz-protein-screen"]`

    Engine used for protein library screen

    - `"boltz-protein-screen"`

  - `engine_version: str`

    Engine version used for protein library screen

  - `error: Optional[Error]`

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

  - `input: Optional[Input]`

    Pipeline input (null if data deleted)

    - `proteins: InputProteins`

      - `url: str`

        URL to download the file

      - `url_expires_at: datetime`

        When the presigned URL expires

    - `target: InputTarget`

      Target specification (structure template or template-free)

      - `class InputTargetStructureTemplateTargetResponse: …`

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

        - `chain_selection: Dict[str, InputTargetStructureTemplateTargetResponseChainSelection]`

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

          - `class InputTargetStructureTemplateTargetResponseChainSelectionStructureTemplateTargetPolymerChainSpec: …`

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

            - `chain_type: Literal["polymer"]`

              - `"polymer"`

            - `crop_residues: Union[List[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 engine run.

              - `List[int]`

                0-indexed residue indices to keep

              - `Literal["all"]`

                - `"all"`

            - `epitope_residues: Optional[List[int]]`

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

            - `flexible_residues: Optional[List[int]]`

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

          - `class InputTargetStructureTemplateTargetResponseChainSelectionStructureTemplateTargetLigandChainSpec: …`

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

            - `chain_type: Literal["ligand"]`

              - `"ligand"`

        - `structure: InputTargetStructureTemplateTargetResponseStructure`

          - `url: str`

            URL to download the file

          - `url_expires_at: datetime`

            When the presigned URL expires

        - `type: Literal["structure_template"]`

          - `"structure_template"`

      - `class InputTargetNoTemplateTargetResponse: …`

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

        - `entities: List[InputTargetNoTemplateTargetResponseEntity]`

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

          - `class InputTargetNoTemplateTargetResponseEntityProteinEntityResponse: …`

            - `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[InputTargetNoTemplateTargetResponseEntityProteinEntityResponseModification]]`

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

              - `class InputTargetNoTemplateTargetResponseEntityProteinEntityResponseModificationCcdModificationResponse: …`

                - `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 InputTargetNoTemplateTargetResponseEntityProteinEntityResponseModificationSmilesModificationResponse: …`

                - `residue_index: int`

                  0-based index of the residue to modify

                - `type: Literal["smiles"]`

                  - `"smiles"`

                - `value: str`

                  SMILES string for the modification

          - `class InputTargetNoTemplateTargetResponseEntityRnaEntityResponse: …`

            - `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[InputTargetNoTemplateTargetResponseEntityRnaEntityResponseModification]]`

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

              - `class InputTargetNoTemplateTargetResponseEntityRnaEntityResponseModificationCcdModificationResponse: …`

                - `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 InputTargetNoTemplateTargetResponseEntityRnaEntityResponseModificationSmilesModificationResponse: …`

                - `residue_index: int`

                  0-based index of the residue to modify

                - `type: Literal["smiles"]`

                  - `"smiles"`

                - `value: str`

                  SMILES string for the modification

          - `class InputTargetNoTemplateTargetResponseEntityDnaEntityResponse: …`

            - `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[InputTargetNoTemplateTargetResponseEntityDnaEntityResponseModification]]`

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

              - `class InputTargetNoTemplateTargetResponseEntityDnaEntityResponseModificationCcdModificationResponse: …`

                - `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 InputTargetNoTemplateTargetResponseEntityDnaEntityResponseModificationSmilesModificationResponse: …`

                - `residue_index: int`

                  0-based index of the residue to modify

                - `type: Literal["smiles"]`

                  - `"smiles"`

                - `value: str`

                  SMILES string for the modification

          - `class InputTargetNoTemplateTargetResponseEntityLigandCcdEntityResponse: …`

            - `chain_ids: List[str]`

              Chain IDs for this ligand

            - `type: Literal["ligand_ccd"]`

              - `"ligand_ccd"`

            - `value: str`

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

          - `class InputTargetNoTemplateTargetResponseEntityLigandSmilesEntityResponse: …`

            - `chain_ids: List[str]`

              Chain IDs for this ligand

            - `type: Literal["ligand_smiles"]`

              - `"ligand_smiles"`

            - `value: str`

              SMILES string representing the ligand

        - `type: Literal["no_template"]`

          - `"no_template"`

        - `bonds: Optional[List[InputTargetNoTemplateTargetResponseBond]]`

          Covalent bond constraints between atoms in the target complex. Atom-level ligand references currently support ligand_ccd only; ligand_smiles is unsupported.

          - `atom1: InputTargetNoTemplateTargetResponseBondAtom1`

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

            - `class InputTargetNoTemplateTargetResponseBondAtom1LigandAtomResponse: …`

              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 InputTargetNoTemplateTargetResponseBondAtom1PolymerAtomResponse: …`

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

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

            - `class InputTargetNoTemplateTargetResponseBondAtom2LigandAtomResponse: …`

              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 InputTargetNoTemplateTargetResponseBondAtom2PolymerAtomResponse: …`

              - `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[InputTargetNoTemplateTargetResponseConstraint]]`

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

          - `class InputTargetNoTemplateTargetResponseConstraintPocketConstraintResponse: …`

            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 InputTargetNoTemplateTargetResponseConstraintContactConstraintResponse: …`

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

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

              - `class InputTargetNoTemplateTargetResponseConstraintContactConstraintResponseToken1PolymerContactTokenResponse: …`

                - `chain_id: str`

                  Chain ID

                - `residue_index: int`

                  0-based residue index

                - `type: Literal["polymer_contact"]`

                  - `"polymer_contact"`

              - `class InputTargetNoTemplateTargetResponseConstraintContactConstraintResponseToken1LigandContactTokenResponse: …`

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

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

              - `class InputTargetNoTemplateTargetResponseConstraintContactConstraintResponseToken2PolymerContactTokenResponse: …`

                - `chain_id: str`

                  Chain ID

                - `residue_index: int`

                  0-based residue index

                - `type: Literal["polymer_contact"]`

                  - `"polymer_contact"`

              - `class InputTargetNoTemplateTargetResponseConstraintContactConstraintResponseToken2LigandContactTokenResponse: …`

                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

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

  - `livemode: bool`

    Whether this resource was created with a live API key.

  - `progress: Optional[Progress]`

    - `num_proteins_failed: int`

      Number of accepted proteins that reached terminal failure during screening.

    - `num_proteins_screened: int`

      Number of accepted proteins that produced usable screening results.

    - `total_proteins_to_screen: int`

      Total number of proteins accepted into the screening run.

    - `latest_result_id: Optional[str]`

      ID of the latest result

  - `started_at: Optional[datetime]`

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

    - `"pending"`

    - `"running"`

    - `"succeeded"`

    - `"failed"`

    - `"stopped"`

  - `stopped_at: Optional[datetime]`

  - `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
)
library_screen = client.protein.library_screen.retrieve(
    id="id",
)
print(library_screen.id)
```