# Introduction

<h4 align="center">Pioneering the next stage of computational Drug Discovery. Empowering chemists to discover faster in novel, untouched spaces - to turn impossible targets into tomorrow's therapeutics.</h4>

***

Pending AI has developed a comprehensive drug discovery platform enabled by scalable artificial intelligence and quantum mechanics, ushering in a new paradigm of medicinal innovation where higher-quality small molecule drugs can be developed in a fraction of the time and cost.

<table data-card-size="large" data-view="cards" data-full-width="false"><thead><tr><th></th><th></th><th data-hidden data-card-cover data-type="image">Cover image</th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Quickstart</strong></td><td>Create a simple workflow for a synthetic screening campaign or use an existing template to <a data-footnote-ref href="#user-content-fn-1">boost</a> your Drug Discovery pipeline</td><td><a href="/files/tewvJnRHYBymDzLyxqJt">/files/tewvJnRHYBymDzLyxqJt</a></td><td><a href="/pages/AGT4YBEf2z5MVCSU2Dlq">/pages/AGT4YBEf2z5MVCSU2Dlq</a></td></tr><tr><td><strong>Installation</strong></td><td>Setup a convenient environment for integrating services directly into your pipeline development space</td><td><a href="/files/TwT8OJtK1JqNr0STOuLy">/files/TwT8OJtK1JqNr0STOuLy</a></td><td><a href="/pages/5AdGpO3FQYZluzCBJM9X">/pages/5AdGpO3FQYZluzCBJM9X</a></td></tr><tr><td><strong>PAI Retro</strong></td><td>Leverage the <a data-footnote-ref href="#user-content-fn-2">fastest</a> Retrosynthesis engine capable of screening and returning diverse synthetic routes</td><td><a href="/files/7gIIxFnRg2cPlL7cXNJJ">/files/7gIIxFnRg2cPlL7cXNJJ</a></td><td><a href="/pages/vJ7Gd0Hgw185Lq5YZ76K">/pages/vJ7Gd0Hgw185Lq5YZ76K</a></td></tr><tr><td><strong>PAI Generator</strong></td><td>Expand into targeted chemical subspaces for identifying novel structures for specific industry domains</td><td><a href="/files/Am9BNIvQkhsD69ambZFr">/files/Am9BNIvQkhsD69ambZFr</a></td><td><a href="/pages/Cjr6ws19xxEBwzOesIdY">/pages/Cjr6ws19xxEBwzOesIdY</a></td></tr></tbody></table>

[^1]: Pending AI offers state-of-the-art capabilities for Drug Discovery reducing the time for early hit discovery

[^2]: Our unique machine-learning engine can screen over 10,000 molecules per hour


# Quickstart

Create a Drug Discovery pipeline in minutes

The Pending AI platform offers a variety of capabilities to assist different targeted pipelines. This quick-start guide demonstrates how to build a simple Python script to generate and screen batches of novel structures.

{% hint style="info" %}
**Prerequisites**: Install Python 3.9 or later (latest recommended). See [here](https://www.python.org/downloads/) for more information. Create a [Pending AI account](http://lab.pending.ai/) with access to the different services.&#x20;
{% endhint %}

## Getting Started

Start by installing the Pending AI Python library. For more information see our [Installation](/getting-started/installation) guide.

```bash
pip install pendingai
```

You can check this was installed correctly using `pendingai --version`.

### Setting up the Client

The SDK provides a client interface for accessing the Pending AI platform seamlessly. Since an authenticated session is needed for using the different services associated with your account, the client can create and store cached session information.

{% code title="Creating an authenticated client" lineNumbers="true" %}

```python
from pendingai import PendingAiClient

pai = PendingAiClient()
pai.authentication.login()
```

{% endcode %}

**Note:** The following examples will no longer include the above snippet but it is recommended to start each script by checking the authenticated session status.

## Create a screening campaign

For this pipeline we wish to run a script capable of leveraging novel molecule generation ([PAI Generator](/pai-generator/cli-reference)) with high-throughput synthetic accessibility screening ([PAI Retro](/pai-retro/cli-reference)).

{% stepper %}
{% step %}

### Generate a novel batch of structures

A user has the fine-grained control over selecting which model is used by listing and checking the individual status for each and sampling from that particular model `id` - sampling via any available model is also possible.

{% code title="Select and sample from a generative model" lineNumbers="true" %}

```python
pai = PendingAiClient()

# Iterate over the models and check their status
models = pai.generator.models.list(size=5)
for model in models:
    model_status = pai.generator.models.status(model.id)
    print(f"Model '{model.id}' has status '{model_status.status}'")
    
# Sample a batch of structures from any model
sample_random = pai.generator.generate.call(n=1000)

# Sample a batch of structures from a target model
sample_target = pai.generator.generate.call(models[0].id, n=1000)
print(f"Sampled {len(sample_target.smiles)} structures.")
```

{% endcode %}

{% file src="/files/6c6CtOB2z3uI48GJ2229" %}
Example of sampled structures from the generative model.
{% endfile %}
{% endstep %}

{% step %}

### Submit the batch for retrosynthesis

The [PAI Retro](/api-reference/pai-retro) service requires submitting to a retrosynthesis engine with a collection of building block libraries of purchasable structures. With those resource IDs, the batch can be submitted with additional parameters to control the synthesis jobs.

{% code title="Submit a retrosynthesis batch" lineNumbers="true" %}

```python
# Retrieve a retrosynthesis engine to submit the batch to
engine = pai.retrosynthesus.engines.list()[0].id
# Retrieve building block libraries to define the synthesis context
libraries = [lib.id for lib in pai.retrosynthesus.libraries.list()]

# Batch submission uses the set of generated SMILES and resource ids
batch = pai.retrosynthesis.batch.create(
    smiles=sample_target.smiles,
    engine=engine,
    libraries=libraries,
    number_of_routes=1,
    processing_time=60,
)
print(f"Batch submitted with ID '{batch.id}'")
```

{% endcode %}

**Note:** Be sure to track the batch `id` or attach additional identifying metadata so it can be found easily when batches are listed (`pai.retrosynthesis.batches.list()`).
{% endstep %}

{% step %}

### Retrieve the screening result summary

Batch screening can be time consuming depending on the number of jobs submitted. A polling strategy should be employed when checking the progress and retrieving results. Once the batch is completed, results can be retrieved, inspected, and saved for further analysis.

{% code title="Retrieve synthetic accessibility results" lineNumbers="true" %}

```python
import time
import json

while True:
    time.sleep(5)  # Poll every 5 seconds
    batch_status = pai.retrosynthesis.batches.status(batch.id)
    if batch_status.status == "completed":
        # All jobs have completed and have available results
        results = pai.retrosynthesis.batches.result(batch.id)
        break
        
# Inspect the batch results
num_synthesizable = sum([1 for job in results if job.synthesizable])
print(f"Found {num_synthesizable} synthesizable structures!") 
        
# Save the batch results to file
with open("results.json", "w") as fp:
    json.dump(results, fp, indent=2)
    
```

{% endcode %}
{% endstep %}
{% endstepper %}

:tada: Well done! You've created your first pipeline to aid in increasing the speed of your Drug Discovery process. For more help in creating pipeline components, see the different [Guides](/developer-tools/guides) we have made and reach out for any more suggestions.


# Installation

Easily setup the right tool integrations

Access to the different Pending AI services is made available through a variety of different tools. Integrations are defined at different software layers to make installation more streamlined.

Depending on your pipeline environment, there are many different available tools with more <mark style="color:$warning;">**under development**</mark> coming in [future releases.](#user-content-fn-1)[^1] All integrations leverage our API as the entry-point for the different Pending AI capabilities.

***

## Installing the CLI

<mark style="color:$info;">For creating simple scripts or interacting with the platform from your terminal</mark>

{% hint style="info" %}
**Prerequisites**: Install Python 3.9 or later (latest recommended). See [here](https://www.python.org/downloads/) for more information. Create a [Pending AI account](http://lab.pending.ai/) with access to the different services.&#x20;
{% endhint %}

### 1. Create a Python Environment (Recommended)

The CLI tool is made available via the Python [PyPI](https://pypi.org/project/pendingai/) repository and can be installed using your favourite dependency manager. Before installing the tool, it's **recommended** to set up a clean environment to avoid dependency conflicts with cheminformatics libraries like `rdkit`.

<details>

<summary>Setting up a <code>venv</code> runtime</summary>

Python's built-in `venv` module is the simplest way to get started with virtual environments.

**1. Create a Virtual Environment:** Navigate to your project directory and run the following command. This creates a new directory (`.venv`) containing the Python interpreter and newly added libraries.

```
# For macOS / Linux
python3 -m venv .venv

# For Windows
py -m venv .venv

```

**2. Activate the Environment:** Before you can use it, you need to activate the environment.

```bash
# For macOS / Linux (bash/zsh)
source .venv/bin/activate

# For Windows (Command Prompt)
.venv\Scripts\activate.bat

# For Windows (PowerShell)
.venv\Scripts\Activate.ps1
```

You'll know the environment is active because the terminal prompt will change to show the environment name (e.g. `(.venv) Computer-Name:~ $`).

</details>

<details>

<summary>Setting up a <code>conda</code> runtime (Recommended)</summary>

If you use the [Anaconda](https://www.anaconda.com/distribution/) or [Miniconda](https://docs.conda.io/en/latest/miniconda.html) distribution, `conda` is your go-to tool for environment management. It's particularly powerful for managing complex cheminformatics packages.

**1. Create a Conda Environment:** This command creates a new environment named `pendingai-env` with a specific Python version.

```bash
conda create --name pendingai-env python=3.13
```

**2. Activate the Environment:** Before you can use it, you need to activate the environment.

```bash
conda activate pendingai-env
```

You'll know the environment is active because the terminal prompt will change to show the environment name (e.g. `(pendingai-env) Computer-Name:~ $`).

</details>

### 2. Installation Methods

Once your environment is active, you can install the `pendingai` tool. Here are some common methods.

{% tabs %}
{% tab title="pip" %}

#### Using `pip` (Standard)

`pip` is Python's standard package installer and is included with most Python installations. It's perfect for installing tools as part of a specific project's dependencies regardless of runtime.

```bash
pip install pendingai
```

**To install a specific version:**

```bash
pip install pendingai==0.4.0
```

The tool is continually being improved, to **upgrade an existing installed version:**

```bash
pip install --upgrade pendingai
```

{% endtab %}

{% tab title="uv" %}

#### Using uv (Recommended for performance)

[uv](https://github.com/astral-sh/uv) is an extremely fast Python package installer and resolver. If you value speed, you can use it within any activated virtual environment (`venv` or `conda`).

**Install `uv`:**&#x20;

```bash
pip install uv
```

**Install packages using `uv` similar to `pip`:**

```bash
uv pip install pendingai            # Latest
uv pip install pendingai==0.4.0     # Specific version
```

<mark style="color:$warning;">**Note:**</mark> `uv` can install into activated virtual environments and requires running tools such as `pendingai` prefixing commands with `uv run <command>`:

```bash
uv run pendingai <commands>
```

{% endtab %}

{% tab title="poetry" %}

#### Using `poetry` (Recommended for projects)

A modern Python project and dependency manager like [poetry](https://python-poetry.org/) can streamline version management in larger software projects.

**Install `poetry`:**&#x20;

```bash
pip install poetry
```

**Install packages with `poetry`:**

```bash
poetry add pendingai                # Add as a main dependency
poetry add -G <group> pendingai     # Add to a dependency group
poetry add pendingai==0.4.0         # Specific version
```

<mark style="color:$warning;">**Note:**</mark> `poetry` installs into the Python environment automatically but it is recommended to invoke commands prefixed with `poetry run <command>` which is important for reproducibility:&#x20;

```bash
poetry run pendingai <commands>
```

{% endtab %}

{% tab title="pipx" %}

#### Using `pipx` (Recommended for global dependency management)

The [pipx](https://github.com/pypa/pipx) tool is ideal for installing dependencies into the global Python runtime to be used across different virtual environments making it easier for use in different projects.

**Install `pipx`:**

```bash
pip install pipx
pipx ensurepath
```

**Install packages with `pipx`:**&#x20;

```bash
pipx install pendingai
```

{% endtab %}
{% endtabs %}

### 3. Verifying Your Installation

Check the installation was successful by checking CLI is available in your terminal.

```bash
pendingai --help
pendingai --version
```

#### Authentication

We provide a simple authentication flow from the CLI that will automatically redirect you to our login page. Multiple commands are provided to help manage the access control when using the different Pending AI services.

```bash
pendingai auth login        # Login to the Pending AI platform
pendingai auth refresh      # Refresh an authenticated session
```

## Installing the SDK

Pending AI currently supports a Python-based SDK available to install following the same steps as the CLI tool as both are bundled in the same package.

Verify your installation with a simple script that sets up an authenticated client and lists our Retrosynthesis engines that are available for use:

{% code lineNumbers="true" %}

```python
from pendingai import PendingAiClient

pai = PendingAiClient()        # Create the client
pai.authentication.login()     # Login to the platform

# Retrieve all retrosynthesis engines
for engine in pai.retrosynthesis.engines.list():
    print(f"Engine ID: {engine.id}")
```

{% endcode %}

#### Authentication

The SDK mimics the same authentication flow as the CLI tool but from a Python script. Cached active sessions can be used without any additional code after logging in from executing a script. To maintain the active session, it needs to be routinely refreshed, otherwise you will be redirect to login again.

{% code lineNumbers="true" %}

```python
from pendingai import PendingAiClient

pai = PendingAiClient()    
pai.authentication.login()     # Initially calling a script must login
pai.authentication.refresh()   # Repeated scripts can refresh a session
```

{% endcode %}

## Troubleshooting

{% hint style="success" %}
Have a specialised use case? Contact us at `support@pending.ai` for help with building custom pipelines.
{% endhint %}

Here are some common questions and how to resolve them.

<details>

<summary>Q: I installed a tool, but my terminal says <code>command not found</code>. What's wrong?</summary>

A: This issues generally means  your shell can't find the tool you just installed. Here are a few troubleshooting steps to try:

* **Is your virtual environment active?** If you used `pip`, `uv`, or `conda`, your terminal prompt should have a prefix like `(.venv)` or `(pendingai-env)`. If it doesn't, you just need to reactivate it. Scroll up to the activation commands for `venv` or `conda`.
* Does your project use a special runtime? Tools like `uv` and `poetry` have dependency resolvers that require an extra prefix before running a command, add `uv run` or `poetry run` to the start of your command.
* **Did you just install `pipx`?** After running `pipx ensurepath`, you often need to open a brand new terminal window for the changes to your system's `PATH` to be applied.
* **A handy workaround:** You can often run the tool directly as a Python module. For example, instead of running `pendingai --version`, you can type `python -m pendingai --version`. This can be a good temporary fix but a new Python environment is recommended.

</details>

<details>

<summary>Q: Why am I seeing a <code>Permission denied</code> error when I try to install something?</summary>

A: This usually means you're trying to install a package into a protected system-wide directory without the right permissions (like using `pip` without `sudo`).

The best solution is to **avoid using `sudo` with `pip`**. Doing so can cause issues with your operating system. Instead, stick to one of the methods as shown above:

* Install inside a `venv` or `conda` environment.
* Use `pipx` for global tools.

These methods install packages in your user's home directory.

</details>

<details>

<summary>Q: The installation failed because of a dependency conflict. What does that mean?</summary>

A: This happens when the tool you're installing needs a specific version of a package ( `rdkit==2025.3.5`), but another package has a conflicting requirement.

It is recommended to use a new virtual environment or project-level dependency manager such as `poetry` to resolve this.

* **Fix your environment:** Create a new, clean virtual environment using `venv` or `conda` and try installing the tool again. By isolating the tool and its dependencies, you give it a fresh start without any conflicting packages to worry about.
* **Fix your project:** Within your project you can lock your dependencies (e.g. `poetry lock` or `uv lock`) and update the required packages to be compatible (likely by using the latest Python version). These tools guide you on how to resolve the conflicting packages.

</details>

<details>

<summary>Q: The tool installed, but it's crashing with a <code>SyntaxError</code> or another unexpected error.</summary>

A: Our tool is under constant development and this may be the cause of new breaking changes. When invoking a command, a message is provided to upgrade your tool to the latest for out-of-date CLI usage.

* **A quick fix:** Upgrade the package to the latest version using your chosen dependency manager (e.g. `pip install --upgrade pendingai`).
* **Raise a ticket:** We are constantly improving our platform, let us know about this issue and how we could improve your journey using our solutions.

</details>

## Next Steps

* See the different capabilities Pending AI offers to customers like [Retrosynthesis](/capabilities/retrosynthesis) or [Generative AI](/capabilities/generative-ai)
* Follow one of our [Guides](/developer-tools/guides) to jump-start integrating our services into your Drug Discovery pipelines.
* See our documentation for the [CLI](/developer-tools/cli) and [SDK](/developer-tools/sdks/python) for more information.

[^1]: If you have any suggestions for more features or tools best suited for you, contact us as we look to create new integrations.


# Web application


# Generative AI

Explore novel molecular space leveraging Generative Deep-Learning

{% hint style="info" %}
Pending AI’s various capabilities are powered by artificial intelligence which is an experimental technology and may occasionally be misleading or incorrect.
{% endhint %}

Pending AI's <mark style="color:$primary;">**Molecule Generator**</mark> is a state-of-the-art, transformer-based service engineered to cut down the time and cost of early-stage drug discovery. It delivers <mark style="color:$primary;">**ultra-high-throughput sampling**</mark> of novel, diverse, and pharmacologically-relevant compounds, empowering R\&D teams to rapidly explore vast chemical space and construct highly effective virtual libraries.

Our advanced deep learning models perform unconditional molecule generation based on the distribution of massive, quality-focused input datasets. Models are built with drug discovery as a primary concern:

* <mark style="color:$primary;">**Validity**</mark>: Molecules are chemically sound, meeting standards for synthetic accessibility and structural integrity required for progression.
* <mark style="color:$primary;">**Novelty**</mark>: Minimal structural overlap with known or patented compounds, ensuring a maximum RoI by focusing on true novel chemical entities.
* <mark style="color:$primary;">**Diversity**</mark>: Compounds exhibit significant structural dissimilarity, reducing repeated chemical screens and maximising the chemical space explored for a target.

See the <mark style="color:$primary;">**PAI Generator**</mark> page for more information about the service.

{% content-ref url="/pages/Cjr6ws19xxEBwzOesIdY" %}
[PAI Generator](/api-reference/pai-generator)
{% endcontent-ref %}

***

## Applications

The Molecule Generator is built to address critical bottlenecks in the therapeutic development cycle - it flexibly addresses several applicable areas for integration into an existing drug discovery pipeline:

<table data-card-size="large" data-view="cards"><thead><tr><th align="center"></th><th align="center"></th></tr></thead><tbody><tr><td align="center"><i class="fa-pen-ruler">:pen-ruler:</i> De Novo Drug Design</td><td align="center">Rapid creation of entirely new molecular scaffolds to address novel or challenging therapeutic targets.</td></tr><tr><td align="center"><i class="fa-forward">:forward:</i> <a href="/pages/1h5TxpTFc56h802JWFzt">Ultra-High-Throughput Screening</a></td><td align="center">Efficiently enumerating and screening massive virtual libraries (in the billions) to identify promising lead candidates faster than traditional methods.</td></tr><tr><td align="center"><i class="fa-bullseye-arrow">:bullseye-arrow:</i> Novel Hit-Identification</td><td align="center">Pinpointing unique, high-potential compounds ready for experimental validation and subsequent lead optimisation.</td></tr><tr><td align="center"><i class="fa-book">:book:</i> Focused Library Construction</td><td align="center">Targeted sampling to build custom libraries for specific drug targets, scaffolds, or physicochemical property profiles.</td></tr></tbody></table>

***

## Features & Advantages

### 1. High-Performance Architecture for Scale

Pending AI's proprietary transformer models are fine-tuned for the unique demands of chemical generation, prioritising speed without compromising quality.

* <mark style="color:$primary;">**Industry-Leading Throughput**</mark>: Generate millions of high-quality molecules, drastically compressing the timeline for virtual library creation ([screening](/capabilities/retrosynthesis) is made readily available).
* <mark style="color:$primary;">**Precision Customisation**</mark>: Leverage fine-tuning capabilities to train the generator on in-house datasets, directing sampling toward specific scaffolds or therapeutically relevant ADMET profiles.

### 2. Rigorous Quality Control & Benchmarking

A comprehensive benchmarking suite is used that validates every output against industry standards for drug-like quality.

* <mark style="color:$primary;">**Drug-Likeness Validation**</mark>: Automated checks for validity, uniqueness, and adherence to established drug-like filters (e.g., Lipinski's Rule of Five).
* <mark style="color:$primary;">**Optimised Diversity**</mark>: Continuous measurement of novelty and average dissimilarity to confirm the effective exploration of new chemical space.
* <mark style="color:$primary;">**Feature Consistency**</mark>: Sampled physicochemical feature distributions (e.g., molecular weight,  $$LogP$$, $$TPSA$$) are compared against optimal ranges, ensuring molecules possess certain characteristics.

<div align="center" data-full-width="false"><figure><img src="/files/6PoikKwMY1HZFyQaLIh8" alt=""><figcaption></figcaption></figure></div>

### 3. Extensive and Vetted Chemical Data Foundation

The model is trained on a massive, diverse, and meticulously curated collection of molecular datasets drawn from both public and commercial sources. This foundation ensures the model has a vast embedded understanding of the complexity and rules of medicinal chemistry.

* <mark style="color:$primary;">**Data Integrity**</mark>: A rigorous preparation process ensures underlying data is high-quality and standardised, resulting a robust model that generates reliable, chemically-sound outputs.

***

## **Model Overview**

There are several models available for sampling molecules. Each model contains a semantically limited chemical space based on underlying training distributions sourced from large compound libraries.

Architecture components are specially designed for the drug discovery domain; advanced token embedding models optimised for novelty and diversity have been improved to further extract chemically relevant features for early Design & Make stages.&#x20;

{% hint style="info" %}
Model utility is uniquely validated against Pending AI's own drug discovery pipeline which has accelerated the early Hit Identification and refinement stages.&#x20;
{% endhint %}

<table><thead><tr><th width="149.5">Name</th><th width="466">Description</th><th data-type="rating" data-max="4">Overall Rank</th></tr></thead><tbody><tr><td>Diverse Small Transformer</td><td>This model excels at generating a broad range of general chemical structures, including those found in patents and reaction databases, natural products, and known drug molecules. It offers high diversity in its generated output.</td><td>2</td></tr><tr><td>Docking Tiny Transformer</td><td>This model specialises in generating molecules with high drug-likeness and is particularly well-suited for virtual screening applications. It offers a very high throughput for generating potentially relevant compounds for early-stage drug discovery.</td><td>4</td></tr><tr><td>Docking Small Transformer</td><td>Building on the strengths of its predecessor, this model also excels at virtual screening and generating drug-like molecules. It has the highest throughput and improved rates of generating valid and unique molecules compared to previous iterations.</td><td>3</td></tr><tr><td>Docking Medium Transformer</td><td>This model is the most robust for virtual screening molecule generation. It offers an excellent balance of generating valid, unique, and drug-like molecules, and its larger architecture provides a more comprehensive exploration of the chemical space relevant to drug discovery, leading to a high amount of novel, drug-like compounds.</td><td>4</td></tr></tbody></table>

{% @mermaid/diagram content="radar-beta
title PAI Generator Model Performance Rankings
axis t\["Throughput"], v\["Validity"], n\["Novelty"], d\["Diversity"]
curve aa\["Diverse Sml"]{1, 1, 1, 4}
curve ab\["Docking Tny"]{3, 3, 3, 3}
curve ac\["Docking Sml"]{4, 4, 2, 1}
curve ad\["Docking Med"]{2, 2, 4, 2}
max 4
min 0" fullWidth="false" %}


# Retrosynthesis

High-throughput Retrosynthesis for screening large compound libraries

{% hint style="info" %}
Pending AI’s various capabilities are powered by artificial intelligence which is an experimental technology and may occasionally be misleading or incorrect.
{% endhint %}

Pending AI's Retrosynthesis Engine is a cutting-edge service designed for ultra-high-throughput synthetic feasibility analysis. By integrating multiple unique deep learning models with a Monte Carlo Tree Search (MCTS) framework, the Engine rapidly identifies complex, multi-step, and economically viable synthetic routes for novel and existing chemical entities.

The synthetic bottleneck is a major impediment in drug discovery. Our engine drastically accelerates the Design-Make-Test-Analyze (DMTA) cycle by providing chemist-first, feasible synthesis routes early in the process.

* <mark style="color:$primary;">**Intelligent Feasibility**</mark>: Combines reaction pattern recognition from deep learning models with the exhaustive search capabilities of MCTS to propose routes that are both practically possible and literature-inspired.
* <mark style="color:$primary;">**Massive Throughput**</mark>: Designed to scale and screen the synthetic accessibility of hundreds of thousands of compounds per day, enabling proactive filtering of synthetically difficult molecules *prior* to the Make stage.
* <mark style="color:$primary;">**Actionable Outputs**</mark>: Provides detailed, step-by-step route trees, including learned scoring and pairwise diversity to guide lab-based synthesis.

See the <mark style="color:$primary;">**PAI Retro**</mark> page for more information about the service.

{% content-ref url="/pages/vJ7Gd0Hgw185Lq5YZ76K" %}
[PAI Retro](/api-reference/pai-retro)
{% endcontent-ref %}

***

## Applications

High-throughput large-scale molecule retrosynthesis has traditionally blocked drug discovery pipelines forcing chemists to perform insufficient workarounds for a target. The [PAI Retro](/api-reference/pai-retro) service provides an avenue to unlock previously time-restricted applications within the DMTA cycle:

<table data-card-size="large" data-view="cards"><thead><tr><th align="center"></th><th align="center"></th></tr></thead><tbody><tr><td align="center"><i class="fa-memo-circle-check">:memo-circle-check:</i> Assess Synthetic Accessibility</td><td align="center">Proactively filter lead candidates from virtual screening campaigns (or sampled synthetic libraries using <a data-mention href="/pages/wK2lO6QAKZOEG9j5xLRv">/pages/wK2lO6QAKZOEG9j5xLRv</a>).</td></tr><tr><td align="center"><i class="fa-route">:route:</i> Route Design &#x26; Optimisation</td><td align="center">Identify cheaper, shorter, or more scalable routes for existing commercial  products from specified building block libraries.</td></tr><tr><td align="center"><i class="fa-lock">:lock:</i> Targeted Proprietary Libraries</td><td align="center">Retrosynthesis models can be customised using proprietary datasets for reaction templates or building block libraries.</td></tr><tr><td align="center"><i class="fa-robot">:robot:</i> Automated Synthesis Integration</td><td align="center">Directly feed valid routes into automated synthesis platforms, electronic laboratory notebooks, or AI-driven environment.</td></tr></tbody></table>

***

## Features & Advantages

### 1. Chemically-Aware AI Architecture

Our unique approach integrates three distinct, high-quality AI models trained on chemically diverse datasets within an engine-variant MCTS search framework.

* <mark style="color:$primary;">**Reaction Prediction AI**</mark>: Base models are trained on millions of unique chemical reactions to accurately predict viable precursors in a single retrosynthetic step.
* <mark style="color:$primary;">**Template Extraction**</mark>: Over 75,000 high-quality, chemically relevant reaction templates are extracted and utilised, ensuring outputs reflect real-world reaction space.
* <mark style="color:$primary;">**AI-Driven Expansion Policy**</mark>: A highly optimised AI model (trained on 71 million samples) guides MCTS expansion, prioritising ideal reactions for a given target molecule for faster convergence.

### 2. Scalability and Customisation

We offer flexible solutions designed to meet both the scale of virtual screening and the specificity of proprietary data.

* <mark style="color:$primary;">**Ultra-High Throughput**</mark>: Standard processing capacity of up to 400,000 queries per day, with tiered options (High, Very-High, Ultra-High) available for bespoke campaigns.
* <mark style="color:$primary;">**Custom Data Integration**</mark>: The AI models can be customised and fine-tuned using proprietary datasets (e.g., in-house electronic laboratory notebook data), ensuring generated routes prioritise preferred, reliable, and available chemistry.
* <mark style="color:$primary;">**Building Block Awareness**</mark>: Routes are assessed against a comprehensive set of nearly ten million commercially available building blocks (including a subset of ZINC labelled as in-stock).

### 3. Chemist-First Capabilities

The Retrosynthesis engine is designed to augment, not replace, the medicinal chemist's expertise by providing practical, high-value insights.

* <mark style="color:$primary;">**Route Diversity Analysis**</mark>: MCTS is engineered to explore a rich set of distinct synthetic pathways. Diversity rankings and analysis of routes allows chemists to assess trade-offs in terms of cost, novelty, and other characteristics.
* <mark style="color:$primary;">**Feasibility Scoring**</mark>: Routes and reaction steps are assigned confidence scores allowing the chemist to quickly prioritise higher-confidence pathways and assess risks for lower scoring components.


# Subspace Search


# PAI Generator

Access Pending AI's high-throughput Molecule Generator models

Pending AI's Molecule Generator capability is designed to yield high-throughput novel and diverse molecule sampling ideal for expanding into untouched chemical spaces rapidly. The service provides a simple integration for dedicated AI inference with one of Pending AI's innovative generative models.

See the **capability** page for more information:

{% content-ref url="/pages/wK2lO6QAKZOEG9j5xLRv" %}
[Generative AI](/capabilities/generative-ai)
{% endcontent-ref %}

***

## Workflow Summary

Access to Pending AI's Molecule Generator models simplifies the workflow in drug discover pipelines for branching into different chemical spaces for targeted or broad molecular distributions. Building large-scale compound libraries is made possible through repeatedly requesting [**samples**](/api-reference/pai-generator/sampling-structures) from a generative [**model**](/api-reference/pai-generator/generative-models) when specifying an `id`.

{% @mermaid/diagram content="stateDiagram-v2
a: Inspect Molecule Generator Models
b: Request a Sample from a Model
ScreeningCampaign: Screening Campaign
SubspaceClustering: Subspace Clustering
state ScreeningCampaign {
c: Collect Molecules for a Compound Library
d: Screen Molecules for Synthetic Accessibility
e: Filter for Optimal Drug-Likeness and Target Affinity
c --> d
d --> e
}
state SubspaceClustering {
f: Collect Unique Molecules of Interest
g: Cluster Molecules using any Algorithm
f --> g
}
b --> ScreeningCampaign
b --> SubspaceClustering
SubspaceClustering --> ScreeningCampaign : Identify clusters with optimal synthetic accessibility
\[*] --> a
\[*] --> b
" %}

See the available [Guides](/developer-tools/guides) for more implementation possibilities when integrating with existing drug discovery pipelines.

***

## Frequently Asked Questions

<details>

<summary>Q: How do I decide which model to use?</summary>

A: Refer to the [**capability**](/capabilities/generative-ai) page for a detailed breakdown of each model's strengths. Consider the optimal model based on the primary metric for the intended purpose. Otherwise, any model is generally favourable for sampling drug-like novel and diverse molecules.

</details>

<details>

<summary>Q: How many molecules can I generate in one request?</summary>

A: Sampling is rate limited by Pending AI servers to prevent excessive content transferred in one request. Multiple smaller samples are made when specifying a number of molecules. The API limits requests at 2000 molecules to speed up individual responses and compressing results but there is no limit to how many times you can sample molecules from any given model.&#x20;

</details>

<details>

<summary>Q: What does it mean if a model status is <code>offline</code> or <code>error</code>?</summary>

A: Since inference models require expensive resource requirements and can have many people request molecules simultaneously, under certain conditions a model may be unavailable and set as `offline`. When an unexpected error occurs for the <mark style="color:$primary;">**PAI Generator**</mark> service, the model is given an `error` status instead. Otherwise it will be labelled as `online`.

</details>

<details>

<summary>Q: Can there be duplicate SMILES returned when sampling?</summary>

A: Within a given sample request no duplicates are returned. It should be considered that when generating molecules from the same model the chemical space captured by the AI embedding architecture is not infinite and there is always a possibility (although highly unlikely).&#x20;

</details>


# Generative Models

Explore SoTA Deep-Learning models for exploring novel chemical space

Capturing the complexity of novel chemical spaces requires advanced AI solutions to assist in generating diverse yet relevant molecular structures. Pending AI makes available a suite of pre-trained generative models, each designed with specific capabilities to address various drug discovery challenges.

Models can be fine-tuned to adapt to unique chemical subspaces, enhancing iteration speed for Hit Identification in early Drug Discovery. Contact us to learn more about custom model training and fine-tuning.

See [here](https://docs.pending.ai/capabilities/generative-ai) for more information on our **Generative AI** capability.

## List models

> Retrieve a list of models. Key-based pagination is supported. See query parameters for more details on how to retrieve the next or previous page of results.

```json
{"openapi":"3.1.0","info":{"title":"PAI Generator","version":"v1"},"tags":[{"description":"\nCapturing the complexity of novel chemical spaces requires advanced AI solutions to\nassist in generating diverse yet relevant molecular structures. Pending AI makes\navailable a suite of pre-trained generative models, each designed with specific\ncapabilities to address various drug discovery challenges.\n\nModels can be fine-tuned to adapt to unique chemical subspaces, enhancing iteration\nspeed for Hit Identification in early Drug Discovery. Contact us to learn more about\ncustom model training and fine-tuning.\n\nSee [here](https://docs.pending.ai/capabilities/generative-ai)  for more information on\nour **Generative AI** capability.\n","name":"Models"}],"servers":[{"description":"Pending AI Server","url":"https://api.pending.ai/generator/v1"}],"security":[{"oauth":[""],"token":[""]}],"components":{"securitySchemes":{"oauth":{"description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","scopes":{}}},"type":"oauth2"}},"schemas":{"ResourceList_ModelResource_":{"properties":{"data":{"description":"A list containing the retrieved objects. The list can contain fewer\nobjects than requested if a smaller number of results were found.","items":{"$ref":"#/components/schemas/ModelResource"},"title":"Data","type":"array"},"has_more":{"description":"A boolean flag that indicates whether there are more items available\nto be fetched on subsequent pages. Used for pagination control.","title":"Has More","type":"boolean"},"object":{"default":"list","description":"The type of resource.","pattern":"^\\w+$","title":"Resource Object","type":"string"}},"required":["data","has_more"],"title":"ResourceList[ModelResource]","type":"object"},"ModelResource":{"description":"A model resource represents a machine learning model that can be\nused for generating samples of molecular structures in batches of\nSMILES strings. Each model leverages a specific architecture and set\nof parameters to produce novel and diverse molecules.","properties":{"description":{"anyOf":[{"pattern":"^[A-Za-z0-9\\s.,;:!?\\(\\)]+$","type":"string"},{"type":"null"}],"description":"Optional description for the model.","title":"Description"},"id":{"description":"The unique resource identifier.","pattern":"^\\w+$","title":"Resource Id","type":"string"},"metadata":{"additionalProperties":true,"description":"Optional metadata for the model. Can include fields such as the\nnumber of parameters, training dataset, training time, and other\nrelevant information.","title":"Metadata","type":"object"},"name":{"anyOf":[{"pattern":"^[A-Za-z0-9\\s.,;:!?\\(\\)]+$","type":"string"},{"type":"null"}],"description":"Optional name for the model.","title":"Name"},"object":{"description":"The type of resource.","pattern":"^\\w+$","title":"Resource Object","type":"string"},"summary":{"additionalProperties":true,"description":"Optional summary statistics for the model. Can include fields\nsuch as accuracy, loss, and other relevant metrics to summarise the\noverall performance of the model.","title":"Summary","type":"object"},"version":{"anyOf":[{"pattern":"^[A-Za-z0-9\\s.,;:!?\\(\\)]+$","type":"string"},{"type":"null"}],"description":"Optional version for the model.","title":"Version"}},"required":["id","object"],"title":"Model","type":"object"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"},"ResponseValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"ResponseValidationError","type":"object"}}},"paths":{"/models":{"get":{"description":"Retrieve a list of models. Key-based pagination is supported. See query parameters for more details on how to retrieve the next or previous page of results.","operationId":"list_models_models_get","parameters":[{"description":"Limit the number of resources returned within the `data` field of the paged response. The field may contain fewer items than the specified limit when there are not enough items to return.","in":"query","name":"limit","required":false,"schema":{"default":5,"description":"Limit the number of resources returned within the `data` field of the paged response. The field may contain fewer items than the specified limit when there are not enough items to return.","maximum":100,"minimum":1,"title":"Limit","type":"integer"}},{"description":"A key used to navigate pagination results. The given value must match an `id` for the specific resource `object` type. If provided, the paged response will contain resources from the next 'page', or those that were submitted before the matched resource (reverse chronological order).","in":"query","name":"next-page","required":false,"schema":{"anyOf":[{"maxLength":255,"minLength":1,"pattern":"^\\w+$","type":"string"},{"type":"null"}],"description":"A key used to navigate pagination results. The given value must match an `id` for the specific resource `object` type. If provided, the paged response will contain resources from the next 'page', or those that were submitted before the matched resource (reverse chronological order).","title":"Next-Page"}},{"description":"A key used to navigate pagination results. The given value must match an `id` for the specific resource `object` type. If provided, the paged response will contain resources from the previous 'page', or those that were submitted after the matched resource (reverse chronological order).","in":"query","name":"prev-page","required":false,"schema":{"anyOf":[{"maxLength":255,"minLength":1,"pattern":"^\\w+$","type":"string"},{"type":"null"}],"description":"A key used to navigate pagination results. The given value must match an `id` for the specific resource `object` type. If provided, the paged response will contain resources from the previous 'page', or those that were submitted after the matched resource (reverse chronological order).","title":"Prev-Page"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResourceList_ModelResource_"}}},"description":"Returns a list of models."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationError"}}},"description":"Response Validation Error"}},"summary":"List models","tags":["Models"]}}}}
```

## Retrieve a model

> Retrieves a model and a detailed overview of its different features. Model information can optionally include metadata and summary statistics with other identifiable fields.

```json
{"openapi":"3.1.0","info":{"title":"PAI Generator","version":"v1"},"tags":[{"description":"\nCapturing the complexity of novel chemical spaces requires advanced AI solutions to\nassist in generating diverse yet relevant molecular structures. Pending AI makes\navailable a suite of pre-trained generative models, each designed with specific\ncapabilities to address various drug discovery challenges.\n\nModels can be fine-tuned to adapt to unique chemical subspaces, enhancing iteration\nspeed for Hit Identification in early Drug Discovery. Contact us to learn more about\ncustom model training and fine-tuning.\n\nSee [here](https://docs.pending.ai/capabilities/generative-ai)  for more information on\nour **Generative AI** capability.\n","name":"Models"}],"servers":[{"description":"Pending AI Server","url":"https://api.pending.ai/generator/v1"}],"security":[{"oauth":[""],"token":[""]}],"components":{"securitySchemes":{"oauth":{"description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","scopes":{}}},"type":"oauth2"}},"schemas":{"ModelResource":{"description":"A model resource represents a machine learning model that can be\nused for generating samples of molecular structures in batches of\nSMILES strings. Each model leverages a specific architecture and set\nof parameters to produce novel and diverse molecules.","properties":{"description":{"anyOf":[{"pattern":"^[A-Za-z0-9\\s.,;:!?\\(\\)]+$","type":"string"},{"type":"null"}],"description":"Optional description for the model.","title":"Description"},"id":{"description":"The unique resource identifier.","pattern":"^\\w+$","title":"Resource Id","type":"string"},"metadata":{"additionalProperties":true,"description":"Optional metadata for the model. Can include fields such as the\nnumber of parameters, training dataset, training time, and other\nrelevant information.","title":"Metadata","type":"object"},"name":{"anyOf":[{"pattern":"^[A-Za-z0-9\\s.,;:!?\\(\\)]+$","type":"string"},{"type":"null"}],"description":"Optional name for the model.","title":"Name"},"object":{"description":"The type of resource.","pattern":"^\\w+$","title":"Resource Object","type":"string"},"summary":{"additionalProperties":true,"description":"Optional summary statistics for the model. Can include fields\nsuch as accuracy, loss, and other relevant metrics to summarise the\noverall performance of the model.","title":"Summary","type":"object"},"version":{"anyOf":[{"pattern":"^[A-Za-z0-9\\s.,;:!?\\(\\)]+$","type":"string"},{"type":"null"}],"description":"Optional version for the model.","title":"Version"}},"required":["id","object"],"title":"Model","type":"object"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"},"ResponseValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"ResponseValidationError","type":"object"}}},"paths":{"/models/{model_id}":{"get":{"description":"Retrieves a model and a detailed overview of its different features. Model information can optionally include metadata and summary statistics with other identifiable fields.","operationId":"retrieve_model_models__model_id__get","parameters":[{"description":"A unique identifier for a model resource.","in":"path","name":"model_id","required":true,"schema":{"description":"A unique identifier for a model resource.","maxLength":255,"minLength":1,"pattern":"^\\w+$","title":"Model Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelResource"}}},"description":"Returns the model."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelResource"}}},"description":"Model resource not found."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationError"}}},"description":"Response Validation Error"}},"summary":"Retrieve a model","tags":["Models"]}}}}
```

## Retrieve a model status

> Retrieve the status of a model. Sampling is made available by the Pending AI platform and may be affected by heavy traffic or resource constraints. Check the status of a model before sampling to ensure it is available.

```json
{"openapi":"3.1.0","info":{"title":"PAI Generator","version":"v1"},"tags":[{"description":"\nCapturing the complexity of novel chemical spaces requires advanced AI solutions to\nassist in generating diverse yet relevant molecular structures. Pending AI makes\navailable a suite of pre-trained generative models, each designed with specific\ncapabilities to address various drug discovery challenges.\n\nModels can be fine-tuned to adapt to unique chemical subspaces, enhancing iteration\nspeed for Hit Identification in early Drug Discovery. Contact us to learn more about\ncustom model training and fine-tuning.\n\nSee [here](https://docs.pending.ai/capabilities/generative-ai)  for more information on\nour **Generative AI** capability.\n","name":"Models"}],"servers":[{"description":"Pending AI Server","url":"https://api.pending.ai/generator/v1"}],"security":[{"oauth":[""],"token":[""]}],"components":{"securitySchemes":{"oauth":{"description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","scopes":{}}},"type":"oauth2"}},"schemas":{"RetrieveStatusOutput":{"description":"Output model for retrieving the status of a model.","properties":{"status":{"description":"The status of the model. Requesting samples from the model\ndepends on the model being `online`. Generating structures can\nalso `timeout` or be unavailable if the model is `offline`.","enum":["online","offline","timeout","error"],"title":"Status","type":"string"}},"required":["status"],"title":"ModelRetrieveStatusOutput","type":"object"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"},"ResponseValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"ResponseValidationError","type":"object"}}},"paths":{"/models/{model_id}/status":{"get":{"description":"Retrieve the status of a model. Sampling is made available by the Pending AI platform and may be affected by heavy traffic or resource constraints. Check the status of a model before sampling to ensure it is available.","operationId":"retrieve_model_status_models__model_id__status_get","parameters":[{"description":"A unique identifier for a model resource.","in":"path","name":"model_id","required":true,"schema":{"description":"A unique identifier for a model resource.","maxLength":255,"minLength":1,"pattern":"^\\w+$","title":"Model Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrieveStatusOutput"}}},"description":"Returns the model status."},"404":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Model resource not found."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationError"}}},"description":"Response Validation Error"}},"summary":"Retrieve a model status","tags":["Models"]}}}}
```


# Sampling Structures

Speed up Hit Identification with rapid molecule sampling

Efficiently expand into chemical space by sampling from generative Deep-Learning models around an underlying distribution of molecules. With the ability to easily generate hundreds of thousands of unique structures in minutes, building a diverse library of molecular structures reduces the time and cost associated with traditional first Hit Identification methods - additionally see our other solutions to further improve Drug Discovery pipeline stages.

**Considerations:**

* Sampling speed is limited by API request rate limits and data transfer bottlenecks. For larger sampling requirements, contact us to discuss custom solutions.
* Structures are generated as unique SMILES within a single request, however duplicate structures may be generated across multiple requests. See individual model metadata for more information on uniqueness rates.

See [here](https://docs.pending.ai/capabilities/generative-ai) for more information on our **Generative AI** capability.

## List samples

> Retrieve a list of samples. Key-based pagination is supported. See query parameters for more details on how to retrieve the next or previous page of results.

```json
{"openapi":"3.1.0","info":{"title":"PAI Generator","version":"v1"},"tags":[{"description":"\nEfficiently expand into chemical space by sampling from generative Deep-Learning models\naround an underlying distribution of molecules. With the ability to easily generate\nhundreds of thousands of unique structures in minutes, building a diverse library of\nmolecular structures reduces the time and cost associated with traditional first\nHit Identification methods - additionally see our other solutions to further improve\nDrug Discovery pipeline stages.\n\n**Considerations:**\n\n- Sampling speed is limited by API request rate limits and data transfer bottlenecks.\nFor larger sampling requirements, contact us to discuss custom solutions.\n- Structures are generated as unique SMILES within a single request, however\nduplicate structures may be generated across multiple requests. See individual model\nmetadata for more information on uniqueness rates.\n\nSee [here](https://docs.pending.ai/capabilities/generative-ai)  for more information on\nour **Generative AI** capability.\n","name":"Samples"}],"servers":[{"description":"Pending AI Server","url":"https://api.pending.ai/generator/v1"}],"security":[{"oauth":[""],"token":[""]}],"components":{"securitySchemes":{"oauth":{"description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","scopes":{}}},"type":"oauth2"}},"schemas":{"ResourceList_ListOutputItem_":{"properties":{"data":{"description":"A list containing the retrieved objects. The list can contain fewer\nobjects than requested if a smaller number of results were found.","items":{"$ref":"#/components/schemas/ListOutputItem"},"title":"Data","type":"array"},"has_more":{"description":"A boolean flag that indicates whether there are more items available\nto be fetched on subsequent pages. Used for pagination control.","title":"Has More","type":"boolean"},"object":{"default":"list","description":"The type of resource.","pattern":"^\\w+$","title":"Resource Object","type":"string"}},"required":["data","has_more"],"title":"ResourceList[Sample.ListOutputItem]","type":"object"},"ListOutputItem":{"description":"A reduced representation of a sample for providing metadata to\nallow for efficient listing. To retrieve sample results, request\nindividual samples by their `id`.","properties":{"created_at":{"description":"Timestamp for when the sample was created.","format":"date-time","title":"Created At","type":"string"},"id":{"description":"The unique resource identifier.","pattern":"^\\w+$","title":"Resource Id","type":"string"},"model_id":{"description":"An `id` belonging to the model used to generate the sample. The\nvalue can be used to retrieve more information about the model.","pattern":"^\\w+$","title":"Model Id","type":"string"},"num_smiles":{"description":"The number of sampled molecules to be generated for the request.","maximum":10000,"minimum":1,"title":"Num Smiles","type":"integer"},"object":{"description":"The type of resource.","pattern":"^\\w+$","title":"Resource Object","type":"string"}},"required":["id","object","model_id","num_smiles"],"title":"Sample","type":"object"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"},"ResponseValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"ResponseValidationError","type":"object"}}},"paths":{"/samples":{"get":{"description":"Retrieve a list of samples. Key-based pagination is supported. See query parameters for more details on how to retrieve the next or previous page of results.","operationId":"list_samples_samples_get","parameters":[{"description":"Limit the number of resources returned within the `data` field of the paged response. The field may contain fewer items than the specified limit when there are not enough items to return.","in":"query","name":"limit","required":false,"schema":{"default":5,"description":"Limit the number of resources returned within the `data` field of the paged response. The field may contain fewer items than the specified limit when there are not enough items to return.","maximum":100,"minimum":1,"title":"Limit","type":"integer"}},{"description":"A key used to navigate pagination results. The given value must match an `id` for the specific resource `object` type. If provided, the paged response will contain resources from the next 'page', or those that were submitted before the matched resource (reverse chronological order).","in":"query","name":"next-page","required":false,"schema":{"anyOf":[{"maxLength":255,"minLength":1,"pattern":"^\\w+$","type":"string"},{"type":"null"}],"description":"A key used to navigate pagination results. The given value must match an `id` for the specific resource `object` type. If provided, the paged response will contain resources from the next 'page', or those that were submitted before the matched resource (reverse chronological order).","title":"Next-Page"}},{"description":"A key used to navigate pagination results. The given value must match an `id` for the specific resource `object` type. If provided, the paged response will contain resources from the previous 'page', or those that were submitted after the matched resource (reverse chronological order).","in":"query","name":"prev-page","required":false,"schema":{"anyOf":[{"maxLength":255,"minLength":1,"pattern":"^\\w+$","type":"string"},{"type":"null"}],"description":"A key used to navigate pagination results. The given value must match an `id` for the specific resource `object` type. If provided, the paged response will contain resources from the previous 'page', or those that were submitted after the matched resource (reverse chronological order).","title":"Prev-Page"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResourceList_ListOutputItem_"}}},"description":"Returns a list of samples."},"400":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Request contained invalid data."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationError"}}},"description":"Response Validation Error"}},"summary":"List samples","tags":["Samples"]}}}}
```

## Create a sample

> Create a sample by generating molecules from a specific model. When no model is provided, any will be used that is readily available.

```json
{"openapi":"3.1.0","info":{"title":"PAI Generator","version":"v1"},"tags":[{"description":"\nEfficiently expand into chemical space by sampling from generative Deep-Learning models\naround an underlying distribution of molecules. With the ability to easily generate\nhundreds of thousands of unique structures in minutes, building a diverse library of\nmolecular structures reduces the time and cost associated with traditional first\nHit Identification methods - additionally see our other solutions to further improve\nDrug Discovery pipeline stages.\n\n**Considerations:**\n\n- Sampling speed is limited by API request rate limits and data transfer bottlenecks.\nFor larger sampling requirements, contact us to discuss custom solutions.\n- Structures are generated as unique SMILES within a single request, however\nduplicate structures may be generated across multiple requests. See individual model\nmetadata for more information on uniqueness rates.\n\nSee [here](https://docs.pending.ai/capabilities/generative-ai)  for more information on\nour **Generative AI** capability.\n","name":"Samples"}],"servers":[{"description":"Pending AI Server","url":"https://api.pending.ai/generator/v1"}],"security":[{"oauth":[""],"token":[""]}],"components":{"securitySchemes":{"oauth":{"description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","scopes":{}}},"type":"oauth2"}},"schemas":{"pai_generator__models__samples__Sample__CreateParams":{"description":"Request data for creating a new sample.","properties":{"model_id":{"anyOf":[{"pattern":"^\\w+$","type":"string"},{"type":"null"}],"description":"Optional `id` belonging to a model to use for generating the\nsample. If no model is provided, any will be used that is\nreadily available.","title":"Model Id"},"size":{"description":"The number of sampled molecules to generate for the request.\nMust be a positive integer.","maximum":10000,"minimum":1,"title":"Size","type":"integer"}},"required":["size"],"title":"SampleCreateParams","type":"object"},"SampleResource":{"description":"A sample contains a collection of molecules generated by a machine-\nlearning model on a defined chemical space. Samples represent the\nnovel structures in a SMILES format.","properties":{"created_at":{"description":"Timestamp for when the sample was created.","format":"date-time","title":"Created At","type":"string"},"id":{"description":"The unique resource identifier.","pattern":"^\\w+$","title":"Resource Id","type":"string"},"model_id":{"description":"An `id` belonging to the model used to generate the sample. The\nvalue can be used to retrieve more information about the model.","pattern":"^\\w+$","title":"Model Id","type":"string"},"object":{"description":"The type of resource.","pattern":"^\\w+$","title":"Resource Object","type":"string"},"smiles":{"description":"A collection of generated SMILES structures from the model. The\nnumber of structures will correspond to the `num_samples` value\nprovided when creating the sample.","items":{"type":"string"},"title":"Smiles","type":"array"}},"required":["id","object","model_id","smiles"],"title":"Sample","type":"object"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"},"ResponseValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"ResponseValidationError","type":"object"}}},"paths":{"/samples":{"post":{"description":"Create a sample by generating molecules from a specific model. When no model is provided, any will be used that is readily available.","operationId":"create_sample_samples_post","parameters":[{"description":"An optional header to be provided when accepting Base64 compressed response content. Providing the header value `gzip` yields gzipped Base64-encoded content for the response body.","in":"header","name":"accept-encoding","required":false,"schema":{"default":"*","description":"An optional header to be provided when accepting Base64 compressed response content. Providing the header value `gzip` yields gzipped Base64-encoded content for the response body.","enum":["gzip","*"],"title":"Accept-Encoding","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/pai_generator__models__samples__Sample__CreateParams"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SampleResource"}}},"description":"Returns the sample."},"400":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Request contained invalid data."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationError"}}},"description":"Response Validation Error"}},"summary":"Create a sample","tags":["Samples"]}}}}
```

## Retrieve a sample

> Retrieves a sample and all generated structures. This is designed to allow retrieving any samples previously generated.

```json
{"openapi":"3.1.0","info":{"title":"PAI Generator","version":"v1"},"tags":[{"description":"\nEfficiently expand into chemical space by sampling from generative Deep-Learning models\naround an underlying distribution of molecules. With the ability to easily generate\nhundreds of thousands of unique structures in minutes, building a diverse library of\nmolecular structures reduces the time and cost associated with traditional first\nHit Identification methods - additionally see our other solutions to further improve\nDrug Discovery pipeline stages.\n\n**Considerations:**\n\n- Sampling speed is limited by API request rate limits and data transfer bottlenecks.\nFor larger sampling requirements, contact us to discuss custom solutions.\n- Structures are generated as unique SMILES within a single request, however\nduplicate structures may be generated across multiple requests. See individual model\nmetadata for more information on uniqueness rates.\n\nSee [here](https://docs.pending.ai/capabilities/generative-ai)  for more information on\nour **Generative AI** capability.\n","name":"Samples"}],"servers":[{"description":"Pending AI Server","url":"https://api.pending.ai/generator/v1"}],"security":[{"oauth":[""],"token":[""]}],"components":{"securitySchemes":{"oauth":{"description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","scopes":{}}},"type":"oauth2"}},"schemas":{"SampleResource":{"description":"A sample contains a collection of molecules generated by a machine-\nlearning model on a defined chemical space. Samples represent the\nnovel structures in a SMILES format.","properties":{"created_at":{"description":"Timestamp for when the sample was created.","format":"date-time","title":"Created At","type":"string"},"id":{"description":"The unique resource identifier.","pattern":"^\\w+$","title":"Resource Id","type":"string"},"model_id":{"description":"An `id` belonging to the model used to generate the sample. The\nvalue can be used to retrieve more information about the model.","pattern":"^\\w+$","title":"Model Id","type":"string"},"object":{"description":"The type of resource.","pattern":"^\\w+$","title":"Resource Object","type":"string"},"smiles":{"description":"A collection of generated SMILES structures from the model. The\nnumber of structures will correspond to the `num_samples` value\nprovided when creating the sample.","items":{"type":"string"},"title":"Smiles","type":"array"}},"required":["id","object","model_id","smiles"],"title":"Sample","type":"object"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"},"ResponseValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"ResponseValidationError","type":"object"}}},"paths":{"/samples/{sample_id}":{"get":{"description":"Retrieves a sample and all generated structures. This is designed to allow retrieving any samples previously generated.","operationId":"retrieve_sample_samples__sample_id__get","parameters":[{"description":"A unique identifier for a sample resource.","in":"path","name":"sample_id","required":true,"schema":{"description":"A unique identifier for a sample resource.","maxLength":255,"minLength":1,"pattern":"^\\w+$","title":"Sample Id","type":"string"}},{"description":"An optional header to be provided when accepting Base64 compressed response content. Providing the header value `gzip` yields gzipped Base64-encoded content for the response body.","in":"header","name":"accept-encoding","required":false,"schema":{"default":"*","description":"An optional header to be provided when accepting Base64 compressed response content. Providing the header value `gzip` yields gzipped Base64-encoded content for the response body.","enum":["gzip","*"],"title":"Accept-Encoding","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SampleResource"}}},"description":"Returns the sample."},"404":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Sample resource not found."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationError"}}},"description":"Response Validation Error"}},"summary":"Retrieve a sample","tags":["Samples"]}}}}
```


# PAI Retro

Access Pending AI's high-throughput Retrosynthesis engines

Pending AI's Retrosynthesis Engine capability, engineered for high-throughput synthetic feasibility analysis, combines well-curated and diverse datasets to rapidly identify complex multi-step synthetic routes for broad regions of chemical space.

See the **capability** page for more information:

{% content-ref url="/pages/1h5TxpTFc56h802JWFzt" %}
[Retrosynthesis](/capabilities/retrosynthesis)
{% endcontent-ref %}

***

## Workflow Summary

Pending AI's Retrosynthesis engine runs behind a queue-based environment for each specific engine. An [**engine**](/api-reference/pai-retro/retrosynthesis-engines) and set of [**building block libraries**](/api-reference/pai-retro/building-block-libraries), containing molecules used to terminate a synthetic route, must be provided when submitting a query.&#x20;

On submission, a [**job**](/api-reference/pai-retro/synthesis-jobs) `id` is provided and then used to poll for results until it is completed, at which point results should be retrieved and saved per query. A similar workflow is made available through [**batch-based**](/api-reference/pai-retro/batch-screening) submission to provide a faster screening interface on larger collections of query molecules.

{% @mermaid/diagram content="stateDiagram-v2
a: Inspect Retrosynthesis Engines
b: Inspect Building Block Libraries
c: Submit a Retrosynthesis Query Molecule
d: Retrieve a Status for the Query
e: Retrieve Synthesis Routes for the Query
note right of c: Select engines and libraries as configuration parameters.
note right of d: Repeat until status changes to **completed**.
\[*] --> a
\[*] --> b
\[*] --> c
c --> d
d --> e
e --> \[*]: Further Processing
" %}

See the available [Guides](/developer-tools/guides) for more implementation possibilities when integrating with existing drug discovery pipelines.

***

## Frequently Asked Questions

<details>

<summary>Q: Why do some molecules take significantly longer than others for retrosynthesis?</summary>

A: The total time until the results of a retrosynthesis job are ready to be retrieved is dependent on the queue wait time and synthesis processing.&#x20;

* Queues are affected by other jobs shared by an engine when too many requests are made in a given time.
* Processing time can be affected by optional parameters such as the number of routes requested or processing timeout.&#x20;

Some molecules may also fail to find any synthetic routes which means the engine will run longer trying to exhaust all reasonable expandable reaction templates.

</details>

<details>

<summary>Q: Why do results contains fewer synthetic routes than requested?</summary>

A: Configuration specifies a *maximum number of routes* to be found during retrosynthesis, results are limited due to a number of facts such as other optional parameters that enforce diversity, the complexity of a structure, the allowed time limit for a job, and the existence of chemically viable synthetic routes.

</details>

<details>

<summary>Q: What happens if one job fails within a batch?</summary>

A: When an individual query molecule fails (due to an invalid SMILES structure or unexpected processing error), the batch will continue processing until all other jobs are completed. A batch summary can be retrieve storing a success flag per job to help screen any unhandled query molecules from within the batch.

</details>

<details>

<summary>Q: What is the maximum size for a batch submission?</summary>

A: Currently Pending AI offers a batch limit of 100,000 which should be created with multiple `POST /batches` and `PUT /batches` requests due to the size of retrosynthesis result data. Use multiple batches if a screening campaign contains more query molecules.

</details>


# Retrosynthesis Engines

Explore the various engines available for retrosynthesis

Pending AI offers a novel Deep-Learning MCTS **Retrosynthesis** platform for synthetic planning. An *engine* provides the underlying architecture and functional procedure used for building complex multi-step synthetic routes. When submitting a query molecule for assessing synthetic accessibility, an engine must be specified using its respective `id` field.

**Considerations**

* An engine requires significant computational resources affected by different parameters when completing a Retrosynthesis job. Large screening campaigns are queued onto identical engine instances, potentially leading to longer wait times for screening results.
* Engine selection can significantly impact the diversity of the generated synthetic routes. Try different engines to yield varied synthetic routes

See [here](https://docs.pending.ai/capabilities/synthetic-accessibility) for more information on our **Retrosynthesis** capability.

## List engines

> Retrieve a list of engines.

```json
{"openapi":"3.1.0","info":{"title":"PAI Retro","version":"v2"},"tags":[{"description":"\nPending AI offers a novel Deep-Learning MCTS **Retrosynthesis** platform for synthetic \nplanning. An *engine* provides the underlying architecture and functional procedure \nused for building complex multi-step synthetic routes. When submitting a query molecule\nfor assessing synthetic accessibility, an engine must be specified using its respective \n`id` field.\n\n**Considerations**\n\n- An engine requires significant computational resources affected by different parameters\nwhen completing a Retrosynthesis job. Large screening campaigns are queued onto identical\nengine instances, potentially leading to longer wait times for screening results.\n- Engine selection can significantly impact the diversity of the generated synthetic \nroutes. Try different engines to yield varied synthetic routes\n\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility) \nfor more information on our **Retrosynthesis** capability.\n","name":"Engines"}],"servers":[{"description":"Pending AI Server","url":"https://api.pending.ai/retro/v2","variables":{"environment":{"default":"api","description":"The environment to use for the API.","enum":["api","api.dev","api.stage"]}}}],"security":[{"oauth":[""],"token":[""]}],"components":{"securitySchemes":{"oauth":{"description":"OAuth2 authentication.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","refreshUrl":"https://auth.pending.ai/oauth/token","scopes":{}}},"type":"oauth2"}},"schemas":{"EngineResource":{"description":"Engines are used when performing a retrosynthesis plan for a target\nmolecule. Engines determine the Deep-Learning infrastructure used\nfor building retrosynthetic routes and the specific algorithms\nemployed during the procedure.\n\nSince time requirements can vary for each molecule, consider that\nthe wait time for a job can depend on other requests for a\nparticular engine.","properties":{"id":{"description":"The unique resource identifier.","pattern":"^\\w+$","title":"Resource Id","type":"string"},"last_alive":{"description":"The lastest time the engine was used.","format":"date-time","title":"Last Alive","type":"string"},"name":{"description":"Name of the engine.","title":"Name","type":"string"},"object":{"description":"The type of resource.","pattern":"^\\w+$","title":"Resource Object","type":"string"}},"required":["id","object","name","last_alive"],"title":"Engine","type":"object"},"RequestValidationErrorContent":{"description":"A request or response encountered a validation error when enforcing field constraints. Refer to `error.details` to resolve individual errors. For any unexpected validation errors, contact Pending AI support via email at [support@pending.ai](mailto:support@pending.ai).","properties":{"error":{"$ref":"#/components/schemas/RequestValidationErrorInfo","default":null},"request_id":{"default":null,"description":"A unique ID given to each request.","title":"Request ID","type":"string"},"status":{"default":"error","description":"Status of the request.","enum":["error","success"],"title":"Request Status","type":"string"},"status_code":{"description":"Response status code received for the request.","title":"Status Code","type":"integer"}},"required":["status_code"],"title":"Request Validation Error","type":"object"},"RequestValidationErrorInfo":{"description":"Response content containing extra information for an error.","properties":{"code":{"description":"Short identifier code to classify the error.","title":"Code","type":"string"},"details":{"default":null,"description":"Validation errors with extra information.","items":{"$ref":"#/components/schemas/RequestValidationErrorInfoDetails"},"title":"Detailed Message","type":"array"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"}},"required":["code","path"],"title":"Error Information","type":"object"},"RequestValidationErrorInfoDetails":{"description":"An individual validation error with extra information.","properties":{"error_type":{"default":null,"description":"A description of the validation constraint that was broken.","title":"Constraint Type"},"location":{"default":null,"description":"One or more parameters for where the validation failed.","title":"Validation Location"}},"title":"Detailed Error Content","type":"object"}}},"paths":{"/engines":{"get":{"description":"Retrieve a list of engines.","operationId":"list_engines_engines_get","responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/EngineResource"},"title":"Return","type":"array"}}},"description":"Returns a list of engines."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}},"description":"Request validation failed."}},"summary":"List engines","tags":["Engines"]}}}}
```


# Building Block Libraries

Explore the various libraries available for retrosynthesis

For planning valid multi-step synthetic routes, various *building block libraries* are used to facilitate terminating different reaction subtrees. Our **Retrosynthesis** platform allows users to specify specific libraries for synthetic planning although it is recommended to select all libraries to improve the overall success rate. When submitting a query molecule for assessing synthetic accessibility, a list of libraries must be specified using respective `id` fields.

**Considerations**

* Library selection can influence the success of the retrosynthesis process. It's important to choose libraries that are well-suited for the specific synthetic routes.
* Some libraries may have limitations in terms of the reactions they can support or the average cost of available molecules. Use the latest libraries for optimal results (refer to the `available_from` field).

See [here](https://docs.pending.ai/capabilities/synthetic-accessibility) for more information on our **Retrosynthesis** capability.

## List libraries

> Retrieve a list of libraries.

```json
{"openapi":"3.1.0","info":{"title":"PAI Retro","version":"v2"},"tags":[{"description":"\nFor planning valid multi-step synthetic routes, various *building block libraries* are\nused to facilitate terminating different reaction subtrees. Our **Retrosynthesis** \nplatform allows users to specify specific libraries for synthetic planning although it\nis recommended to select all libraries to improve the overall success rate. When \nsubmitting a query molecule for assessing synthetic accessibility, a list of libraries \nmust be specified using respective `id` fields.\n\n**Considerations**\n\n- Library selection can influence the success of the retrosynthesis process. It's \nimportant to choose libraries that are well-suited for the specific synthetic routes.\n- Some libraries may have limitations in terms of the reactions they can support or the\naverage cost of available molecules. Use the latest libraries for optimal results (refer\nto the `available_from` field).\n\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility)\nfor more information on our **Retrosynthesis** capability.\n                ","name":"Libraries"}],"servers":[{"description":"Pending AI Server","url":"https://api.pending.ai/retro/v2","variables":{"environment":{"default":"api","description":"The environment to use for the API.","enum":["api","api.dev","api.stage"]}}}],"security":[{"oauth":[""],"token":[""]}],"components":{"securitySchemes":{"oauth":{"description":"OAuth2 authentication.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","refreshUrl":"https://auth.pending.ai/oauth/token","scopes":{}}},"type":"oauth2"}},"schemas":{"LibraryResource":{"description":"Libraries contain large collections of building blocks that can be\nused to construct computed synthetic routes. They contain additional\nmetadata such as source information and price to aid in reproducing\nthe synthesis process. The selection of libraries impacts the\nability to resolve a retrosynthesis target meaning that with more\nbuilding block libraries selected when submitting a query molecule,\nthe chances of finding a viable synthetic route improves.","properties":{"available_from":{"description":"The time when the library was made available. Older libraries may\ncontain out-of-date information or have changing price data. It is\nrecommended to use the latest libraries for optimal results.","format":"date-time","title":"Available From","type":"string"},"id":{"description":"The unique resource identifier.","pattern":"^\\w+$","title":"Resource Id","type":"string"},"name":{"description":"Name of the library.","title":"Name","type":"string"},"object":{"description":"The type of resource.","pattern":"^\\w+$","title":"Resource Object","type":"string"},"version":{"description":"A version tag for the library.","title":"Version","type":"string"}},"required":["id","object","name","version","available_from"],"title":"Library","type":"object"},"RequestValidationErrorContent":{"description":"A request or response encountered a validation error when enforcing field constraints. Refer to `error.details` to resolve individual errors. For any unexpected validation errors, contact Pending AI support via email at [support@pending.ai](mailto:support@pending.ai).","properties":{"error":{"$ref":"#/components/schemas/RequestValidationErrorInfo","default":null},"request_id":{"default":null,"description":"A unique ID given to each request.","title":"Request ID","type":"string"},"status":{"default":"error","description":"Status of the request.","enum":["error","success"],"title":"Request Status","type":"string"},"status_code":{"description":"Response status code received for the request.","title":"Status Code","type":"integer"}},"required":["status_code"],"title":"Request Validation Error","type":"object"},"RequestValidationErrorInfo":{"description":"Response content containing extra information for an error.","properties":{"code":{"description":"Short identifier code to classify the error.","title":"Code","type":"string"},"details":{"default":null,"description":"Validation errors with extra information.","items":{"$ref":"#/components/schemas/RequestValidationErrorInfoDetails"},"title":"Detailed Message","type":"array"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"}},"required":["code","path"],"title":"Error Information","type":"object"},"RequestValidationErrorInfoDetails":{"description":"An individual validation error with extra information.","properties":{"error_type":{"default":null,"description":"A description of the validation constraint that was broken.","title":"Constraint Type"},"location":{"default":null,"description":"One or more parameters for where the validation failed.","title":"Validation Location"}},"title":"Detailed Error Content","type":"object"}}},"paths":{"/libraries":{"get":{"description":"Retrieve a list of libraries.","operationId":"list_libraries_libraries_get","responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/LibraryResource"},"title":"Return","type":"array"}}},"description":"Returns a list of libraries."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}},"description":"Request validation failed."}},"summary":"List libraries","tags":["Libraries"]}}}}
```


# Synthesis Jobs

Submit target molecules for retrosynthesis and explore novel synthetic routes

For low-throughput screening or synthetic route exploration, a **Retrosynthesis** *job* can be submitted for a single `query` target molecule. The molecule, represented in [SMILES](http://opensmiles.org/opensmiles.html) format, is provided alongside a set of guiding `parameters` impacting route diversity and results.

* **Fast synthetic accessibility** can be assessed by reducing the time requirement for planning to `processing_time=60` and yield only a single route `number_of_routes=1`.
* **Novel route exploration** can be achieved by increasing the time and resource allocation, allowing for multiple routes to be generated and evaluated. Additionally, decreasing `building_block_limit` and `reaction_limit` forces the engine to consider more diverse reaction pathways, potentially leading to more novel synthetic routes.

Each job requires specifying a `retrosynthesis_engine` and `building_block_libraries` list corresponding to respective resource `id` fields of the engine and libraries. Our unique representation of synthetic routes provides a detailed reaction tree overview. See our [examples](https://docs.pending.ai/libraries/guides) for handling results for detailed analysis.

See [here](https://docs.pending.ai/capabilities/synthetic-accessibility) for more information on our **Retrosynthesis** capability.

## List jobs

> Retrieve a list of jobs.

```json
{"openapi":"3.1.0","info":{"title":"PAI Retro","version":"v2"},"tags":[{"description":"\nFor low-throughput screening or synthetic route exploration, a **Retrosynthesis** *job* \ncan be submitted for a single `query` target molecule. The molecule, represented in\n[SMILES](http://opensmiles.org/opensmiles.html) format, is provided alongside a set of\nguiding `parameters` impacting route diversity and results. \n\n- **Fast synthetic accessibility** can be assessed by reducing the time requirement for\nplanning to `processing_time=60` and yield only a single route `number_of_routes=1`.\n- **Novel route exploration** can be achieved by increasing the time and resource\nallocation, allowing for multiple routes to be generated and evaluated. Additionally,\ndecreasing `building_block_limit` and `reaction_limit` forces the engine to consider\nmore diverse reaction pathways, potentially leading to more novel synthetic routes.\n\nEach job requires specifying a `retrosynthesis_engine` and `building_block_libraries`\nlist corresponding to respective resource `id` fields of the engine and libraries. Our\nunique representation of synthetic routes provides a detailed reaction tree overview. See\nour [examples](https://docs.pending.ai/libraries/guides) for handling results for \ndetailed analysis.\n\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility)\nfor more information on our **Retrosynthesis** capability.\n                ","name":"Jobs"}],"servers":[{"description":"Pending AI Server","url":"https://api.pending.ai/retro/v2","variables":{"environment":{"default":"api","description":"The environment to use for the API.","enum":["api","api.dev","api.stage"]}}}],"security":[{"oauth":[""],"token":[""]}],"components":{"securitySchemes":{"oauth":{"description":"OAuth2 authentication.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","refreshUrl":"https://auth.pending.ai/oauth/token","scopes":{}}},"type":"oauth2"}},"schemas":{"ResourceList_JobResource_":{"properties":{"data":{"description":"A list containing the retrieved objects. The list can contain fewer\nobjects than requested if a smaller number of results were found.","items":{"$ref":"#/components/schemas/JobResource"},"title":"Data","type":"array"},"has_more":{"description":"A boolean flag that indicates whether there are more items available\nto be fetched on subsequent pages. Used for pagination control.","title":"Has More","type":"boolean"},"object":{"default":"list","description":"The type of resource.","pattern":"^\\w+$","title":"Resource Object","type":"string"}},"required":["data","has_more"],"title":"ResourceList[JobResource]","type":"object"},"JobResource":{"description":"A retrosynthesis job for a single target molecule. Jobs provide an\ninterface for controlling the synthesis process and retrieving the\ndetailed results from the retrosynthesis engine. The `parameters`\nfield provides more information about the job configuration.","properties":{"created":{"description":"Timestamp for when the retrosynthesis job was created.","format":"date-time","title":"Created","type":"string"},"id":{"description":"The unique resource identifier.","pattern":"^\\w+$","title":"Resource Id","type":"string"},"object":{"description":"The type of resource.","pattern":"^\\w+$","title":"Resource Object","type":"string"},"parameters":{"$ref":"#/components/schemas/Parameters","description":"Parameters used for controlling the retrosynthesis process."},"query":{"description":"A target molecule in a SMILES format to perform retrosynthesis on.\nIf a molecule cannot be processed, the job will return no results.","pattern":"^[a-zA-Z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*]+$","title":"Query","type":"string"},"routes":{"description":"A collection of unique retrosynthesis routes generated by the job.\nIf no valid routes were found or none could be found within the time\nlimit, this list will be empty.","items":{"$ref":"#/components/schemas/Route"},"title":"Routes","type":"array"},"status":{"description":"A flag indicating the current status of the job.","enum":["submitted","processing","failed","completed"],"title":"Status","type":"string"},"updated":{"description":"Timestamp for when the retrosynthesis job was last updated.","format":"date-time","title":"Updated","type":"string"}},"required":["id","object","query","status","created","updated","routes","parameters"],"title":"Job","type":"object"},"Parameters":{"description":"Retrosynthesis configuration parameters. These values control the\nsynthesis planning process and impact the generation procedure and\npotential results. Refer to individual parameters for more details.","properties":{"building_block_libraries":{"description":"A list of building block library `id`s used for controlling \nsynthetic route termination. Refer to documentation on libraries.","items":{"pattern":"^\\w+$","type":"string"},"minItems":1,"title":"Building Block Libraries","type":"array"},"building_block_limit":{"default":3,"description":"The maximum number of times a single building block molecule can \nappear in the result set of a retrosynthesis job.","maximum":25,"minimum":1,"title":"Building Block Limit","type":"integer"},"number_of_routes":{"default":25,"description":"The maximum number of routes to be generated by the retrosynthesis \nengine. Synthetic routes can be limited by the number found, chosen \nbuilding block libraries, and other control parameters.","maximum":50,"minimum":1,"title":"Number Of Routes","type":"integer"},"processing_time":{"default":300,"description":"The maximum allowable processing time to complete a target molecule.\nA retrosynthesis job will exit if this time is exceeded with either\nno result or fewer routes than requested in `number_of_routes`.","maximum":720,"minimum":60,"title":"Processing Time","type":"integer"},"reaction_limit":{"default":3,"description":"The maximum number of times a single reaction synthesis step can\nappear in the result set of a retrosynthesis job.","maximum":25,"minimum":1,"title":"Reaction Limit","type":"integer"},"retrosynthesis_engine":{"description":"A retrosynthesis engine `id` used for executing the synthesis \nplanning procedure. Refer to documentation on engines.","pattern":"^\\w+$","title":"Retrosynthesis Engine","type":"string"}},"required":["retrosynthesis_engine","building_block_libraries"],"title":"Parameters","type":"object"},"Route":{"description":"A retrosynthesis route. The reaction tree provides a structured\nrepresentation of the synthesis process with building blocks\nas leaf nodes and the target molecule as the root.","properties":{"buildingBlocks":{"description":"Building blocks used in the synthetic route. Each building block\nappears in at least one synthesis step.","items":{"$ref":"#/components/schemas/BuildingBlock"},"title":"Building Blocks","type":"array"},"reactionSmiles":{"description":"Reduced SMILES representation of a retrosynthetic route. Reactants \nare the required building blocks with the product as the target \nmolecule.","pattern":"^[A-Za-z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*>]+$","title":"Summary","type":"string"},"steps":{"description":"Synthesis steps to produce the target molecule from a collection of\nbuilding block molecules. Steps are given in post-order to imitate \nthe synthesis process.","items":{"$ref":"#/components/schemas/RouteStep"},"title":"Steps","type":"array"}},"required":["reactionSmiles","buildingBlocks","steps"],"title":"Route","type":"object"},"BuildingBlock":{"description":"A building block molecule with associated metadata. Constituent\nbuilding blocks from retrosynthesis pathways appear multiple times\nin reaction trees. Refer to metadata for accessing dataset provider\ninformation.","properties":{"buildingBlockMetadata":{"description":"Associated metadata from different building block providers. Some\nproviders may offer more detailed information than others with\nvarying availability and pricing.","items":{"$ref":"#/components/schemas/BuildingBlockMetadata"},"title":"Building Block Metadata","type":"array"},"smiles":{"description":"A building block molecule SMILES representation.","pattern":"^[a-zA-Z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*]+$","title":"Smiles","type":"string"}},"required":["smiles","buildingBlockMetadata"],"title":"BuildingBlock","type":"object"},"BuildingBlockMetadata":{"description":"Metadata associated with a building block molecule. Since a molecule\ncan have different providers, a building block may be available from\nmultiple sources with varying availability and pricing.","properties":{"availability":{"default":"unknown","description":"Availability status of the building block molecule. A molecule is\n`in stock` if it is available for purchase and `unavailable`\notherwise.","pattern":"^\\w+$","title":"Availability","type":"string"},"datasetProvider":{"default":"unknown","description":"Name of the dataset provider with the building block molecule.","pattern":"^\\w+$","title":"Dataset Provider","type":"string"},"identifier":{"default":"unknown","description":"A unique identifier for the building block molecule.","pattern":"^\\w+$","title":"Identifier","type":"string"},"price":{"description":"Price of the building block molecule for the `dataset_provider`. A\nmolecule can have different prices between different providers. ","title":"Price","type":"number"}},"required":["price"],"title":"BuildingBlockMetadata","type":"object"},"RouteStep":{"description":"A single-step reaction representing a synthesis step in a\nretrosynthesis route. Only single-step reactions are supported at\nthis time.","properties":{"number":{"description":"Post-order position of the reaction step in the synthetic route.\nNote that this field is not required to reproduce the retrosynthesis\npathway.","title":"Order","type":"integer"},"reactionSmiles":{"description":"Single-step reaction SMILES representing synthesis step. Reactants\nare guaranteed to be a product of a different synthesis step or are\na building block. The product, if not the synthesis target, appears\nas a reactant in a different synthesis step.","pattern":"^[A-Za-z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*>]+$","title":"Reaction Smiles","type":"string"}},"required":["reactionSmiles","number"],"title":"RouteStep","type":"object"},"RequestValidationErrorContent":{"description":"A request or response encountered a validation error when enforcing field constraints. Refer to `error.details` to resolve individual errors. For any unexpected validation errors, contact Pending AI support via email at [support@pending.ai](mailto:support@pending.ai).","properties":{"error":{"$ref":"#/components/schemas/RequestValidationErrorInfo","default":null},"request_id":{"default":null,"description":"A unique ID given to each request.","title":"Request ID","type":"string"},"status":{"default":"error","description":"Status of the request.","enum":["error","success"],"title":"Request Status","type":"string"},"status_code":{"description":"Response status code received for the request.","title":"Status Code","type":"integer"}},"required":["status_code"],"title":"Request Validation Error","type":"object"},"RequestValidationErrorInfo":{"description":"Response content containing extra information for an error.","properties":{"code":{"description":"Short identifier code to classify the error.","title":"Code","type":"string"},"details":{"default":null,"description":"Validation errors with extra information.","items":{"$ref":"#/components/schemas/RequestValidationErrorInfoDetails"},"title":"Detailed Message","type":"array"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"}},"required":["code","path"],"title":"Error Information","type":"object"},"RequestValidationErrorInfoDetails":{"description":"An individual validation error with extra information.","properties":{"error_type":{"default":null,"description":"A description of the validation constraint that was broken.","title":"Constraint Type"},"location":{"default":null,"description":"One or more parameters for where the validation failed.","title":"Validation Location"}},"title":"Detailed Error Content","type":"object"}}},"paths":{"/jobs":{"get":{"description":"Retrieve a list of jobs.","operationId":"list_jobs_jobs_get","parameters":[{"description":"A page number for retrieving a collection of jobs. Pagination is number-based allowing for arbitrary page lookups. Note that `page-size` can impact page offset results.","in":"query","name":"page-number","required":false,"schema":{"default":1,"description":"A page number for retrieving a collection of jobs. Pagination is number-based allowing for arbitrary page lookups. Note that `page-size` can impact page offset results.","minimum":1,"title":"Page-Number","type":"integer"}},{"description":"The number of job resources returned in the response `data`. There can be fewer jobs returned than requested if the results do not exceed `page-size`.","in":"query","name":"page-size","required":false,"schema":{"default":10,"description":"The number of job resources returned in the response `data`. There can be fewer jobs returned than requested if the results do not exceed `page-size`.","maximum":100,"minimum":1,"title":"Page-Size","type":"integer"}},{"description":"Filter for job statuses to return resources with a matching status value. Use `none` to skip filtering.","in":"query","name":"status","required":false,"schema":{"default":"none","description":"Filter for job statuses to return resources with a matching status value. Use `none` to skip filtering.","enum":["submitted","processing","failed","completed","none"],"title":"Status","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResourceList_JobResource_"}}},"description":"Returns a list of jobs."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}},"description":"Request validation failed."}},"summary":"List jobs","tags":["Jobs"]}}}}
```

## Create a job

> Create a new retrosynthesis job. See the \`parameters\` field for options to control the retrosynthesis process.

```json
{"openapi":"3.1.0","info":{"title":"PAI Retro","version":"v2"},"tags":[{"description":"\nFor low-throughput screening or synthetic route exploration, a **Retrosynthesis** *job* \ncan be submitted for a single `query` target molecule. The molecule, represented in\n[SMILES](http://opensmiles.org/opensmiles.html) format, is provided alongside a set of\nguiding `parameters` impacting route diversity and results. \n\n- **Fast synthetic accessibility** can be assessed by reducing the time requirement for\nplanning to `processing_time=60` and yield only a single route `number_of_routes=1`.\n- **Novel route exploration** can be achieved by increasing the time and resource\nallocation, allowing for multiple routes to be generated and evaluated. Additionally,\ndecreasing `building_block_limit` and `reaction_limit` forces the engine to consider\nmore diverse reaction pathways, potentially leading to more novel synthetic routes.\n\nEach job requires specifying a `retrosynthesis_engine` and `building_block_libraries`\nlist corresponding to respective resource `id` fields of the engine and libraries. Our\nunique representation of synthetic routes provides a detailed reaction tree overview. See\nour [examples](https://docs.pending.ai/libraries/guides) for handling results for \ndetailed analysis.\n\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility)\nfor more information on our **Retrosynthesis** capability.\n                ","name":"Jobs"}],"servers":[{"description":"Pending AI Server","url":"https://api.pending.ai/retro/v2","variables":{"environment":{"default":"api","description":"The environment to use for the API.","enum":["api","api.dev","api.stage"]}}}],"security":[{"oauth":[""],"token":[""]}],"components":{"securitySchemes":{"oauth":{"description":"OAuth2 authentication.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","refreshUrl":"https://auth.pending.ai/oauth/token","scopes":{}}},"type":"oauth2"}},"schemas":{"pai_retro__models__jobs__Job__CreateParams":{"description":"Request data for creating a new retrosynthesis job.","properties":{"parameters":{"$ref":"#/components/schemas/Parameters","description":"Parameters used for controlling the retrosynthesis process."},"query":{"description":"A target molecule in a SMILES format to perform retrosynthesis \non. If a molecule cannot be processed, the job will return no \nresults.","pattern":"^[a-zA-Z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*]+$","title":"Query","type":"string"}},"required":["query","parameters"],"title":"JobCreateParams","type":"object"},"Parameters":{"description":"Retrosynthesis configuration parameters. These values control the\nsynthesis planning process and impact the generation procedure and\npotential results. Refer to individual parameters for more details.","properties":{"building_block_libraries":{"description":"A list of building block library `id`s used for controlling \nsynthetic route termination. Refer to documentation on libraries.","items":{"pattern":"^\\w+$","type":"string"},"minItems":1,"title":"Building Block Libraries","type":"array"},"building_block_limit":{"default":3,"description":"The maximum number of times a single building block molecule can \nappear in the result set of a retrosynthesis job.","maximum":25,"minimum":1,"title":"Building Block Limit","type":"integer"},"number_of_routes":{"default":25,"description":"The maximum number of routes to be generated by the retrosynthesis \nengine. Synthetic routes can be limited by the number found, chosen \nbuilding block libraries, and other control parameters.","maximum":50,"minimum":1,"title":"Number Of Routes","type":"integer"},"processing_time":{"default":300,"description":"The maximum allowable processing time to complete a target molecule.\nA retrosynthesis job will exit if this time is exceeded with either\nno result or fewer routes than requested in `number_of_routes`.","maximum":720,"minimum":60,"title":"Processing Time","type":"integer"},"reaction_limit":{"default":3,"description":"The maximum number of times a single reaction synthesis step can\nappear in the result set of a retrosynthesis job.","maximum":25,"minimum":1,"title":"Reaction Limit","type":"integer"},"retrosynthesis_engine":{"description":"A retrosynthesis engine `id` used for executing the synthesis \nplanning procedure. Refer to documentation on engines.","pattern":"^\\w+$","title":"Retrosynthesis Engine","type":"string"}},"required":["retrosynthesis_engine","building_block_libraries"],"title":"Parameters","type":"object"},"JobResource":{"description":"A retrosynthesis job for a single target molecule. Jobs provide an\ninterface for controlling the synthesis process and retrieving the\ndetailed results from the retrosynthesis engine. The `parameters`\nfield provides more information about the job configuration.","properties":{"created":{"description":"Timestamp for when the retrosynthesis job was created.","format":"date-time","title":"Created","type":"string"},"id":{"description":"The unique resource identifier.","pattern":"^\\w+$","title":"Resource Id","type":"string"},"object":{"description":"The type of resource.","pattern":"^\\w+$","title":"Resource Object","type":"string"},"parameters":{"$ref":"#/components/schemas/Parameters","description":"Parameters used for controlling the retrosynthesis process."},"query":{"description":"A target molecule in a SMILES format to perform retrosynthesis on.\nIf a molecule cannot be processed, the job will return no results.","pattern":"^[a-zA-Z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*]+$","title":"Query","type":"string"},"routes":{"description":"A collection of unique retrosynthesis routes generated by the job.\nIf no valid routes were found or none could be found within the time\nlimit, this list will be empty.","items":{"$ref":"#/components/schemas/Route"},"title":"Routes","type":"array"},"status":{"description":"A flag indicating the current status of the job.","enum":["submitted","processing","failed","completed"],"title":"Status","type":"string"},"updated":{"description":"Timestamp for when the retrosynthesis job was last updated.","format":"date-time","title":"Updated","type":"string"}},"required":["id","object","query","status","created","updated","routes","parameters"],"title":"Job","type":"object"},"Route":{"description":"A retrosynthesis route. The reaction tree provides a structured\nrepresentation of the synthesis process with building blocks\nas leaf nodes and the target molecule as the root.","properties":{"buildingBlocks":{"description":"Building blocks used in the synthetic route. Each building block\nappears in at least one synthesis step.","items":{"$ref":"#/components/schemas/BuildingBlock"},"title":"Building Blocks","type":"array"},"reactionSmiles":{"description":"Reduced SMILES representation of a retrosynthetic route. Reactants \nare the required building blocks with the product as the target \nmolecule.","pattern":"^[A-Za-z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*>]+$","title":"Summary","type":"string"},"steps":{"description":"Synthesis steps to produce the target molecule from a collection of\nbuilding block molecules. Steps are given in post-order to imitate \nthe synthesis process.","items":{"$ref":"#/components/schemas/RouteStep"},"title":"Steps","type":"array"}},"required":["reactionSmiles","buildingBlocks","steps"],"title":"Route","type":"object"},"BuildingBlock":{"description":"A building block molecule with associated metadata. Constituent\nbuilding blocks from retrosynthesis pathways appear multiple times\nin reaction trees. Refer to metadata for accessing dataset provider\ninformation.","properties":{"buildingBlockMetadata":{"description":"Associated metadata from different building block providers. Some\nproviders may offer more detailed information than others with\nvarying availability and pricing.","items":{"$ref":"#/components/schemas/BuildingBlockMetadata"},"title":"Building Block Metadata","type":"array"},"smiles":{"description":"A building block molecule SMILES representation.","pattern":"^[a-zA-Z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*]+$","title":"Smiles","type":"string"}},"required":["smiles","buildingBlockMetadata"],"title":"BuildingBlock","type":"object"},"BuildingBlockMetadata":{"description":"Metadata associated with a building block molecule. Since a molecule\ncan have different providers, a building block may be available from\nmultiple sources with varying availability and pricing.","properties":{"availability":{"default":"unknown","description":"Availability status of the building block molecule. A molecule is\n`in stock` if it is available for purchase and `unavailable`\notherwise.","pattern":"^\\w+$","title":"Availability","type":"string"},"datasetProvider":{"default":"unknown","description":"Name of the dataset provider with the building block molecule.","pattern":"^\\w+$","title":"Dataset Provider","type":"string"},"identifier":{"default":"unknown","description":"A unique identifier for the building block molecule.","pattern":"^\\w+$","title":"Identifier","type":"string"},"price":{"description":"Price of the building block molecule for the `dataset_provider`. A\nmolecule can have different prices between different providers. ","title":"Price","type":"number"}},"required":["price"],"title":"BuildingBlockMetadata","type":"object"},"RouteStep":{"description":"A single-step reaction representing a synthesis step in a\nretrosynthesis route. Only single-step reactions are supported at\nthis time.","properties":{"number":{"description":"Post-order position of the reaction step in the synthetic route.\nNote that this field is not required to reproduce the retrosynthesis\npathway.","title":"Order","type":"integer"},"reactionSmiles":{"description":"Single-step reaction SMILES representing synthesis step. Reactants\nare guaranteed to be a product of a different synthesis step or are\na building block. The product, if not the synthesis target, appears\nas a reactant in a different synthesis step.","pattern":"^[A-Za-z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*>]+$","title":"Reaction Smiles","type":"string"}},"required":["reactionSmiles","number"],"title":"RouteStep","type":"object"},"RequestValidationErrorContent":{"description":"A request or response encountered a validation error when enforcing field constraints. Refer to `error.details` to resolve individual errors. For any unexpected validation errors, contact Pending AI support via email at [support@pending.ai](mailto:support@pending.ai).","properties":{"error":{"$ref":"#/components/schemas/RequestValidationErrorInfo","default":null},"request_id":{"default":null,"description":"A unique ID given to each request.","title":"Request ID","type":"string"},"status":{"default":"error","description":"Status of the request.","enum":["error","success"],"title":"Request Status","type":"string"},"status_code":{"description":"Response status code received for the request.","title":"Status Code","type":"integer"}},"required":["status_code"],"title":"Request Validation Error","type":"object"},"RequestValidationErrorInfo":{"description":"Response content containing extra information for an error.","properties":{"code":{"description":"Short identifier code to classify the error.","title":"Code","type":"string"},"details":{"default":null,"description":"Validation errors with extra information.","items":{"$ref":"#/components/schemas/RequestValidationErrorInfoDetails"},"title":"Detailed Message","type":"array"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"}},"required":["code","path"],"title":"Error Information","type":"object"},"RequestValidationErrorInfoDetails":{"description":"An individual validation error with extra information.","properties":{"error_type":{"default":null,"description":"A description of the validation constraint that was broken.","title":"Constraint Type"},"location":{"default":null,"description":"One or more parameters for where the validation failed.","title":"Validation Location"}},"title":"Detailed Error Content","type":"object"}}},"paths":{"/jobs":{"post":{"description":"Create a new retrosynthesis job. See the `parameters` field for options to control the retrosynthesis process.","operationId":"create_job_jobs_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/pai_retro__models__jobs__Job__CreateParams"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResource"}}},"description":"Returns the job."},"402":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Payment gateway failed."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}},"description":"Request validation failed."}},"summary":"Create a job","tags":["Jobs"]}}}}
```

## Retrieve a job

> Retrieve a retrosynthesis job and any generated synthetic routes.

```json
{"openapi":"3.1.0","info":{"title":"PAI Retro","version":"v2"},"tags":[{"description":"\nFor low-throughput screening or synthetic route exploration, a **Retrosynthesis** *job* \ncan be submitted for a single `query` target molecule. The molecule, represented in\n[SMILES](http://opensmiles.org/opensmiles.html) format, is provided alongside a set of\nguiding `parameters` impacting route diversity and results. \n\n- **Fast synthetic accessibility** can be assessed by reducing the time requirement for\nplanning to `processing_time=60` and yield only a single route `number_of_routes=1`.\n- **Novel route exploration** can be achieved by increasing the time and resource\nallocation, allowing for multiple routes to be generated and evaluated. Additionally,\ndecreasing `building_block_limit` and `reaction_limit` forces the engine to consider\nmore diverse reaction pathways, potentially leading to more novel synthetic routes.\n\nEach job requires specifying a `retrosynthesis_engine` and `building_block_libraries`\nlist corresponding to respective resource `id` fields of the engine and libraries. Our\nunique representation of synthetic routes provides a detailed reaction tree overview. See\nour [examples](https://docs.pending.ai/libraries/guides) for handling results for \ndetailed analysis.\n\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility)\nfor more information on our **Retrosynthesis** capability.\n                ","name":"Jobs"}],"servers":[{"description":"Pending AI Server","url":"https://api.pending.ai/retro/v2","variables":{"environment":{"default":"api","description":"The environment to use for the API.","enum":["api","api.dev","api.stage"]}}}],"security":[{"oauth":[""],"token":[""]}],"components":{"securitySchemes":{"oauth":{"description":"OAuth2 authentication.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","refreshUrl":"https://auth.pending.ai/oauth/token","scopes":{}}},"type":"oauth2"}},"schemas":{"JobResource":{"description":"A retrosynthesis job for a single target molecule. Jobs provide an\ninterface for controlling the synthesis process and retrieving the\ndetailed results from the retrosynthesis engine. The `parameters`\nfield provides more information about the job configuration.","properties":{"created":{"description":"Timestamp for when the retrosynthesis job was created.","format":"date-time","title":"Created","type":"string"},"id":{"description":"The unique resource identifier.","pattern":"^\\w+$","title":"Resource Id","type":"string"},"object":{"description":"The type of resource.","pattern":"^\\w+$","title":"Resource Object","type":"string"},"parameters":{"$ref":"#/components/schemas/Parameters","description":"Parameters used for controlling the retrosynthesis process."},"query":{"description":"A target molecule in a SMILES format to perform retrosynthesis on.\nIf a molecule cannot be processed, the job will return no results.","pattern":"^[a-zA-Z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*]+$","title":"Query","type":"string"},"routes":{"description":"A collection of unique retrosynthesis routes generated by the job.\nIf no valid routes were found or none could be found within the time\nlimit, this list will be empty.","items":{"$ref":"#/components/schemas/Route"},"title":"Routes","type":"array"},"status":{"description":"A flag indicating the current status of the job.","enum":["submitted","processing","failed","completed"],"title":"Status","type":"string"},"updated":{"description":"Timestamp for when the retrosynthesis job was last updated.","format":"date-time","title":"Updated","type":"string"}},"required":["id","object","query","status","created","updated","routes","parameters"],"title":"Job","type":"object"},"Parameters":{"description":"Retrosynthesis configuration parameters. These values control the\nsynthesis planning process and impact the generation procedure and\npotential results. Refer to individual parameters for more details.","properties":{"building_block_libraries":{"description":"A list of building block library `id`s used for controlling \nsynthetic route termination. Refer to documentation on libraries.","items":{"pattern":"^\\w+$","type":"string"},"minItems":1,"title":"Building Block Libraries","type":"array"},"building_block_limit":{"default":3,"description":"The maximum number of times a single building block molecule can \nappear in the result set of a retrosynthesis job.","maximum":25,"minimum":1,"title":"Building Block Limit","type":"integer"},"number_of_routes":{"default":25,"description":"The maximum number of routes to be generated by the retrosynthesis \nengine. Synthetic routes can be limited by the number found, chosen \nbuilding block libraries, and other control parameters.","maximum":50,"minimum":1,"title":"Number Of Routes","type":"integer"},"processing_time":{"default":300,"description":"The maximum allowable processing time to complete a target molecule.\nA retrosynthesis job will exit if this time is exceeded with either\nno result or fewer routes than requested in `number_of_routes`.","maximum":720,"minimum":60,"title":"Processing Time","type":"integer"},"reaction_limit":{"default":3,"description":"The maximum number of times a single reaction synthesis step can\nappear in the result set of a retrosynthesis job.","maximum":25,"minimum":1,"title":"Reaction Limit","type":"integer"},"retrosynthesis_engine":{"description":"A retrosynthesis engine `id` used for executing the synthesis \nplanning procedure. Refer to documentation on engines.","pattern":"^\\w+$","title":"Retrosynthesis Engine","type":"string"}},"required":["retrosynthesis_engine","building_block_libraries"],"title":"Parameters","type":"object"},"Route":{"description":"A retrosynthesis route. The reaction tree provides a structured\nrepresentation of the synthesis process with building blocks\nas leaf nodes and the target molecule as the root.","properties":{"buildingBlocks":{"description":"Building blocks used in the synthetic route. Each building block\nappears in at least one synthesis step.","items":{"$ref":"#/components/schemas/BuildingBlock"},"title":"Building Blocks","type":"array"},"reactionSmiles":{"description":"Reduced SMILES representation of a retrosynthetic route. Reactants \nare the required building blocks with the product as the target \nmolecule.","pattern":"^[A-Za-z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*>]+$","title":"Summary","type":"string"},"steps":{"description":"Synthesis steps to produce the target molecule from a collection of\nbuilding block molecules. Steps are given in post-order to imitate \nthe synthesis process.","items":{"$ref":"#/components/schemas/RouteStep"},"title":"Steps","type":"array"}},"required":["reactionSmiles","buildingBlocks","steps"],"title":"Route","type":"object"},"BuildingBlock":{"description":"A building block molecule with associated metadata. Constituent\nbuilding blocks from retrosynthesis pathways appear multiple times\nin reaction trees. Refer to metadata for accessing dataset provider\ninformation.","properties":{"buildingBlockMetadata":{"description":"Associated metadata from different building block providers. Some\nproviders may offer more detailed information than others with\nvarying availability and pricing.","items":{"$ref":"#/components/schemas/BuildingBlockMetadata"},"title":"Building Block Metadata","type":"array"},"smiles":{"description":"A building block molecule SMILES representation.","pattern":"^[a-zA-Z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*]+$","title":"Smiles","type":"string"}},"required":["smiles","buildingBlockMetadata"],"title":"BuildingBlock","type":"object"},"BuildingBlockMetadata":{"description":"Metadata associated with a building block molecule. Since a molecule\ncan have different providers, a building block may be available from\nmultiple sources with varying availability and pricing.","properties":{"availability":{"default":"unknown","description":"Availability status of the building block molecule. A molecule is\n`in stock` if it is available for purchase and `unavailable`\notherwise.","pattern":"^\\w+$","title":"Availability","type":"string"},"datasetProvider":{"default":"unknown","description":"Name of the dataset provider with the building block molecule.","pattern":"^\\w+$","title":"Dataset Provider","type":"string"},"identifier":{"default":"unknown","description":"A unique identifier for the building block molecule.","pattern":"^\\w+$","title":"Identifier","type":"string"},"price":{"description":"Price of the building block molecule for the `dataset_provider`. A\nmolecule can have different prices between different providers. ","title":"Price","type":"number"}},"required":["price"],"title":"BuildingBlockMetadata","type":"object"},"RouteStep":{"description":"A single-step reaction representing a synthesis step in a\nretrosynthesis route. Only single-step reactions are supported at\nthis time.","properties":{"number":{"description":"Post-order position of the reaction step in the synthetic route.\nNote that this field is not required to reproduce the retrosynthesis\npathway.","title":"Order","type":"integer"},"reactionSmiles":{"description":"Single-step reaction SMILES representing synthesis step. Reactants\nare guaranteed to be a product of a different synthesis step or are\na building block. The product, if not the synthesis target, appears\nas a reactant in a different synthesis step.","pattern":"^[A-Za-z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*>]+$","title":"Reaction Smiles","type":"string"}},"required":["reactionSmiles","number"],"title":"RouteStep","type":"object"},"RequestValidationErrorContent":{"description":"A request or response encountered a validation error when enforcing field constraints. Refer to `error.details` to resolve individual errors. For any unexpected validation errors, contact Pending AI support via email at [support@pending.ai](mailto:support@pending.ai).","properties":{"error":{"$ref":"#/components/schemas/RequestValidationErrorInfo","default":null},"request_id":{"default":null,"description":"A unique ID given to each request.","title":"Request ID","type":"string"},"status":{"default":"error","description":"Status of the request.","enum":["error","success"],"title":"Request Status","type":"string"},"status_code":{"description":"Response status code received for the request.","title":"Status Code","type":"integer"}},"required":["status_code"],"title":"Request Validation Error","type":"object"},"RequestValidationErrorInfo":{"description":"Response content containing extra information for an error.","properties":{"code":{"description":"Short identifier code to classify the error.","title":"Code","type":"string"},"details":{"default":null,"description":"Validation errors with extra information.","items":{"$ref":"#/components/schemas/RequestValidationErrorInfoDetails"},"title":"Detailed Message","type":"array"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"}},"required":["code","path"],"title":"Error Information","type":"object"},"RequestValidationErrorInfoDetails":{"description":"An individual validation error with extra information.","properties":{"error_type":{"default":null,"description":"A description of the validation constraint that was broken.","title":"Constraint Type"},"location":{"default":null,"description":"One or more parameters for where the validation failed.","title":"Validation Location"}},"title":"Detailed Error Content","type":"object"}}},"paths":{"/jobs/{job_id}":{"get":{"description":"Retrieve a retrosynthesis job and any generated synthetic routes.","operationId":"retrieve_job_jobs__job_id__get","parameters":[{"description":"A unique identifier for a job resource.","in":"path","name":"job_id","required":true,"schema":{"description":"A unique identifier for a job resource.","maxLength":255,"minLength":1,"pattern":"^\\w+$","title":"Job Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResource"}}},"description":"Returns the job."},"404":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Job resource not found."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}},"description":"Request validation failed."}},"summary":"Retrieve a job","tags":["Jobs"]}}}}
```

## Delete a job

> Delete a retrosynthesis job and any generated synthetic routes. The job cannot be deleted while in progress.

```json
{"openapi":"3.1.0","info":{"title":"PAI Retro","version":"v2"},"tags":[{"description":"\nFor low-throughput screening or synthetic route exploration, a **Retrosynthesis** *job* \ncan be submitted for a single `query` target molecule. The molecule, represented in\n[SMILES](http://opensmiles.org/opensmiles.html) format, is provided alongside a set of\nguiding `parameters` impacting route diversity and results. \n\n- **Fast synthetic accessibility** can be assessed by reducing the time requirement for\nplanning to `processing_time=60` and yield only a single route `number_of_routes=1`.\n- **Novel route exploration** can be achieved by increasing the time and resource\nallocation, allowing for multiple routes to be generated and evaluated. Additionally,\ndecreasing `building_block_limit` and `reaction_limit` forces the engine to consider\nmore diverse reaction pathways, potentially leading to more novel synthetic routes.\n\nEach job requires specifying a `retrosynthesis_engine` and `building_block_libraries`\nlist corresponding to respective resource `id` fields of the engine and libraries. Our\nunique representation of synthetic routes provides a detailed reaction tree overview. See\nour [examples](https://docs.pending.ai/libraries/guides) for handling results for \ndetailed analysis.\n\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility)\nfor more information on our **Retrosynthesis** capability.\n                ","name":"Jobs"}],"servers":[{"description":"Pending AI Server","url":"https://api.pending.ai/retro/v2","variables":{"environment":{"default":"api","description":"The environment to use for the API.","enum":["api","api.dev","api.stage"]}}}],"security":[{"oauth":[""],"token":[""]}],"components":{"securitySchemes":{"oauth":{"description":"OAuth2 authentication.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","refreshUrl":"https://auth.pending.ai/oauth/token","scopes":{}}},"type":"oauth2"}},"schemas":{"JobResource":{"description":"A retrosynthesis job for a single target molecule. Jobs provide an\ninterface for controlling the synthesis process and retrieving the\ndetailed results from the retrosynthesis engine. The `parameters`\nfield provides more information about the job configuration.","properties":{"created":{"description":"Timestamp for when the retrosynthesis job was created.","format":"date-time","title":"Created","type":"string"},"id":{"description":"The unique resource identifier.","pattern":"^\\w+$","title":"Resource Id","type":"string"},"object":{"description":"The type of resource.","pattern":"^\\w+$","title":"Resource Object","type":"string"},"parameters":{"$ref":"#/components/schemas/Parameters","description":"Parameters used for controlling the retrosynthesis process."},"query":{"description":"A target molecule in a SMILES format to perform retrosynthesis on.\nIf a molecule cannot be processed, the job will return no results.","pattern":"^[a-zA-Z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*]+$","title":"Query","type":"string"},"routes":{"description":"A collection of unique retrosynthesis routes generated by the job.\nIf no valid routes were found or none could be found within the time\nlimit, this list will be empty.","items":{"$ref":"#/components/schemas/Route"},"title":"Routes","type":"array"},"status":{"description":"A flag indicating the current status of the job.","enum":["submitted","processing","failed","completed"],"title":"Status","type":"string"},"updated":{"description":"Timestamp for when the retrosynthesis job was last updated.","format":"date-time","title":"Updated","type":"string"}},"required":["id","object","query","status","created","updated","routes","parameters"],"title":"Job","type":"object"},"Parameters":{"description":"Retrosynthesis configuration parameters. These values control the\nsynthesis planning process and impact the generation procedure and\npotential results. Refer to individual parameters for more details.","properties":{"building_block_libraries":{"description":"A list of building block library `id`s used for controlling \nsynthetic route termination. Refer to documentation on libraries.","items":{"pattern":"^\\w+$","type":"string"},"minItems":1,"title":"Building Block Libraries","type":"array"},"building_block_limit":{"default":3,"description":"The maximum number of times a single building block molecule can \nappear in the result set of a retrosynthesis job.","maximum":25,"minimum":1,"title":"Building Block Limit","type":"integer"},"number_of_routes":{"default":25,"description":"The maximum number of routes to be generated by the retrosynthesis \nengine. Synthetic routes can be limited by the number found, chosen \nbuilding block libraries, and other control parameters.","maximum":50,"minimum":1,"title":"Number Of Routes","type":"integer"},"processing_time":{"default":300,"description":"The maximum allowable processing time to complete a target molecule.\nA retrosynthesis job will exit if this time is exceeded with either\nno result or fewer routes than requested in `number_of_routes`.","maximum":720,"minimum":60,"title":"Processing Time","type":"integer"},"reaction_limit":{"default":3,"description":"The maximum number of times a single reaction synthesis step can\nappear in the result set of a retrosynthesis job.","maximum":25,"minimum":1,"title":"Reaction Limit","type":"integer"},"retrosynthesis_engine":{"description":"A retrosynthesis engine `id` used for executing the synthesis \nplanning procedure. Refer to documentation on engines.","pattern":"^\\w+$","title":"Retrosynthesis Engine","type":"string"}},"required":["retrosynthesis_engine","building_block_libraries"],"title":"Parameters","type":"object"},"Route":{"description":"A retrosynthesis route. The reaction tree provides a structured\nrepresentation of the synthesis process with building blocks\nas leaf nodes and the target molecule as the root.","properties":{"buildingBlocks":{"description":"Building blocks used in the synthetic route. Each building block\nappears in at least one synthesis step.","items":{"$ref":"#/components/schemas/BuildingBlock"},"title":"Building Blocks","type":"array"},"reactionSmiles":{"description":"Reduced SMILES representation of a retrosynthetic route. Reactants \nare the required building blocks with the product as the target \nmolecule.","pattern":"^[A-Za-z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*>]+$","title":"Summary","type":"string"},"steps":{"description":"Synthesis steps to produce the target molecule from a collection of\nbuilding block molecules. Steps are given in post-order to imitate \nthe synthesis process.","items":{"$ref":"#/components/schemas/RouteStep"},"title":"Steps","type":"array"}},"required":["reactionSmiles","buildingBlocks","steps"],"title":"Route","type":"object"},"BuildingBlock":{"description":"A building block molecule with associated metadata. Constituent\nbuilding blocks from retrosynthesis pathways appear multiple times\nin reaction trees. Refer to metadata for accessing dataset provider\ninformation.","properties":{"buildingBlockMetadata":{"description":"Associated metadata from different building block providers. Some\nproviders may offer more detailed information than others with\nvarying availability and pricing.","items":{"$ref":"#/components/schemas/BuildingBlockMetadata"},"title":"Building Block Metadata","type":"array"},"smiles":{"description":"A building block molecule SMILES representation.","pattern":"^[a-zA-Z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*]+$","title":"Smiles","type":"string"}},"required":["smiles","buildingBlockMetadata"],"title":"BuildingBlock","type":"object"},"BuildingBlockMetadata":{"description":"Metadata associated with a building block molecule. Since a molecule\ncan have different providers, a building block may be available from\nmultiple sources with varying availability and pricing.","properties":{"availability":{"default":"unknown","description":"Availability status of the building block molecule. A molecule is\n`in stock` if it is available for purchase and `unavailable`\notherwise.","pattern":"^\\w+$","title":"Availability","type":"string"},"datasetProvider":{"default":"unknown","description":"Name of the dataset provider with the building block molecule.","pattern":"^\\w+$","title":"Dataset Provider","type":"string"},"identifier":{"default":"unknown","description":"A unique identifier for the building block molecule.","pattern":"^\\w+$","title":"Identifier","type":"string"},"price":{"description":"Price of the building block molecule for the `dataset_provider`. A\nmolecule can have different prices between different providers. ","title":"Price","type":"number"}},"required":["price"],"title":"BuildingBlockMetadata","type":"object"},"RouteStep":{"description":"A single-step reaction representing a synthesis step in a\nretrosynthesis route. Only single-step reactions are supported at\nthis time.","properties":{"number":{"description":"Post-order position of the reaction step in the synthetic route.\nNote that this field is not required to reproduce the retrosynthesis\npathway.","title":"Order","type":"integer"},"reactionSmiles":{"description":"Single-step reaction SMILES representing synthesis step. Reactants\nare guaranteed to be a product of a different synthesis step or are\na building block. The product, if not the synthesis target, appears\nas a reactant in a different synthesis step.","pattern":"^[A-Za-z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*>]+$","title":"Reaction Smiles","type":"string"}},"required":["reactionSmiles","number"],"title":"RouteStep","type":"object"},"RequestValidationErrorContent":{"description":"A request or response encountered a validation error when enforcing field constraints. Refer to `error.details` to resolve individual errors. For any unexpected validation errors, contact Pending AI support via email at [support@pending.ai](mailto:support@pending.ai).","properties":{"error":{"$ref":"#/components/schemas/RequestValidationErrorInfo","default":null},"request_id":{"default":null,"description":"A unique ID given to each request.","title":"Request ID","type":"string"},"status":{"default":"error","description":"Status of the request.","enum":["error","success"],"title":"Request Status","type":"string"},"status_code":{"description":"Response status code received for the request.","title":"Status Code","type":"integer"}},"required":["status_code"],"title":"Request Validation Error","type":"object"},"RequestValidationErrorInfo":{"description":"Response content containing extra information for an error.","properties":{"code":{"description":"Short identifier code to classify the error.","title":"Code","type":"string"},"details":{"default":null,"description":"Validation errors with extra information.","items":{"$ref":"#/components/schemas/RequestValidationErrorInfoDetails"},"title":"Detailed Message","type":"array"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"}},"required":["code","path"],"title":"Error Information","type":"object"},"RequestValidationErrorInfoDetails":{"description":"An individual validation error with extra information.","properties":{"error_type":{"default":null,"description":"A description of the validation constraint that was broken.","title":"Constraint Type"},"location":{"default":null,"description":"One or more parameters for where the validation failed.","title":"Validation Location"}},"title":"Detailed Error Content","type":"object"}}},"paths":{"/jobs/{job_id}":{"delete":{"description":"Delete a retrosynthesis job and any generated synthetic routes. The job cannot be deleted while in progress.","operationId":"delete_job_jobs__job_id__delete","parameters":[{"description":"A unique identifier for a job resource.","in":"path","name":"job_id","required":true,"schema":{"description":"A unique identifier for a job resource.","maxLength":255,"minLength":1,"pattern":"^\\w+$","title":"Job Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResource"}}},"description":"Returns the deleted job."},"402":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Payment gateway failed."},"404":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Job resource not found."},"409":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Job resource in progress."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}},"description":"Request validation failed."}},"summary":"Delete a job","tags":["Jobs"]}}}}
```


# Batch Screening

Screen large batches of molecules using our high-throughput retrosynthesis

A high-throughput screening campaign for large-scale chemical libraries can be achieved through submitting *batches* of **Retrosynthesis** jobs with shared `parameters`. Pending AI offers batch sizes of up to 100000 jobs which can be created and then appended to with additional API requests. Batch progress can be tracked with live updates to the number of completed jobs and a high-level screening overview can be retrieved.

Batch synthesis jobs impact the overall queue size for a given engine. Larger batches may lead to a longer wait time for it to complete. Additional metadata data can also be added to the batch submission to help distinguish results beyond an arbitrary batch `id` field.

See [here](https://docs.pending.ai/capabilities/synthetic-accessibility) for more information on our **Retrosynthesis** capability.

## List batches

> Retrieve a list of batches.

```json
{"openapi":"3.1.0","info":{"title":"PAI Retro","version":"v2"},"tags":[{"description":"\nA high-throughput screening campaign for large-scale chemical libraries can be achieved\nthrough submitting *batches* of **Retrosynthesis** jobs with shared `parameters`. Pending\nAI offers batch sizes of up to 100000 jobs which can be created and then appended to with\nadditional API requests. Batch progress can be tracked with live updates to the number of\ncompleted jobs and a high-level screening overview can be retrieved.\n\nBatch synthesis jobs impact the overall queue size for a given engine. Larger batches may\nlead to a longer wait time for it to complete. Additional metadata data can also be added\nto the batch submission to help distinguish results beyond an arbitrary batch `id` field.\n\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility)\nfor more information on our **Retrosynthesis** capability.\n                ","name":"Batches"}],"servers":[{"description":"Pending AI Server","url":"https://api.pending.ai/retro/v2","variables":{"environment":{"default":"api","description":"The environment to use for the API.","enum":["api","api.dev","api.stage"]}}}],"security":[{"oauth":[""],"token":[""]}],"components":{"securitySchemes":{"oauth":{"description":"OAuth2 authentication.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","refreshUrl":"https://auth.pending.ai/oauth/token","scopes":{}}},"type":"oauth2"}},"schemas":{"ResourceList_BatchResource_":{"properties":{"data":{"description":"A list containing the retrieved objects. The list can contain fewer\nobjects than requested if a smaller number of results were found.","items":{"$ref":"#/components/schemas/BatchResource"},"title":"Data","type":"array"},"has_more":{"description":"A boolean flag that indicates whether there are more items available\nto be fetched on subsequent pages. Used for pagination control.","title":"Has More","type":"boolean"},"object":{"default":"list","description":"The type of resource.","pattern":"^\\w+$","title":"Resource Object","type":"string"}},"required":["data","has_more"],"title":"ResourceList[BatchResource]","type":"object"},"BatchResource":{"description":"Batches are collections of retrosynthesis jobs that share a common\nset of parameters. Batches allow for easy management of large sets\nof synthesis targets and provide a mechanism for tracking the status\nof multiple jobs as a single entity.\n\nThere is an upper limit of 100,000 jobs per batch which requires any\nfurther jobs to be submitted in a new batch. Multiple identifiers\ncan be used to distinguish between them.","properties":{"created":{"description":"Timestamp for when the batch was created.","format":"date-time","title":"Created","type":"string"},"description":{"anyOf":[{"maxLength":2048,"pattern":"^[\\w\\s\\-\\:]*$","type":"string"},{"type":"null"}],"description":"An optional description for the batch. The description provides\nadditional context about the batch to help with distinguishing\nbetween other batches.","title":"Description"},"filename":{"anyOf":[{"maxLength":2048,"pattern":"^[\\w\\-\\:]*$","type":"string"},{"type":"null"}],"description":"An optional filename to help identify the batch and ideal for when a\nbatch is submitted via file.","title":"Filename"},"id":{"description":"The unique resource identifier.","pattern":"^\\w+$","title":"Resource Id","type":"string"},"name":{"anyOf":[{"maxLength":256,"pattern":"^[\\w\\s\\-\\:]*$","type":"string"},{"type":"null"}],"description":"An optional name for the batch. The name provides a human-readable\nidentifier for the batch and is not required to be unique.","title":"Name"},"number_of_jobs":{"description":"Total number of retrosynthesis jobs that belong to a batch. The\nvalue can change over time as new jobs are added to the batch.","maximum":100000,"minimum":1,"title":"Number Of Jobs","type":"integer"},"object":{"description":"The type of resource.","pattern":"^\\w+$","title":"Resource Object","type":"string"},"parameters":{"$ref":"#/components/schemas/Parameters","description":"Parameters used for controlling the retrosynthesis process. These\noptions are shared across all jobs that belong to the batch."},"updated":{"description":"Timestamp for when the batch was last updated.","format":"date-time","title":"Updated","type":"string"}},"required":["id","object","number_of_jobs","parameters"],"title":"Batch","type":"object"},"Parameters":{"description":"Retrosynthesis configuration parameters. These values control the\nsynthesis planning process and impact the generation procedure and\npotential results. Refer to individual parameters for more details.","properties":{"building_block_libraries":{"description":"A list of building block library `id`s used for controlling \nsynthetic route termination. Refer to documentation on libraries.","items":{"pattern":"^\\w+$","type":"string"},"minItems":1,"title":"Building Block Libraries","type":"array"},"building_block_limit":{"default":3,"description":"The maximum number of times a single building block molecule can \nappear in the result set of a retrosynthesis job.","maximum":25,"minimum":1,"title":"Building Block Limit","type":"integer"},"number_of_routes":{"default":25,"description":"The maximum number of routes to be generated by the retrosynthesis \nengine. Synthetic routes can be limited by the number found, chosen \nbuilding block libraries, and other control parameters.","maximum":50,"minimum":1,"title":"Number Of Routes","type":"integer"},"processing_time":{"default":300,"description":"The maximum allowable processing time to complete a target molecule.\nA retrosynthesis job will exit if this time is exceeded with either\nno result or fewer routes than requested in `number_of_routes`.","maximum":720,"minimum":60,"title":"Processing Time","type":"integer"},"reaction_limit":{"default":3,"description":"The maximum number of times a single reaction synthesis step can\nappear in the result set of a retrosynthesis job.","maximum":25,"minimum":1,"title":"Reaction Limit","type":"integer"},"retrosynthesis_engine":{"description":"A retrosynthesis engine `id` used for executing the synthesis \nplanning procedure. Refer to documentation on engines.","pattern":"^\\w+$","title":"Retrosynthesis Engine","type":"string"}},"required":["retrosynthesis_engine","building_block_libraries"],"title":"Parameters","type":"object"},"RequestValidationErrorContent":{"description":"A request or response encountered a validation error when enforcing field constraints. Refer to `error.details` to resolve individual errors. For any unexpected validation errors, contact Pending AI support via email at [support@pending.ai](mailto:support@pending.ai).","properties":{"error":{"$ref":"#/components/schemas/RequestValidationErrorInfo","default":null},"request_id":{"default":null,"description":"A unique ID given to each request.","title":"Request ID","type":"string"},"status":{"default":"error","description":"Status of the request.","enum":["error","success"],"title":"Request Status","type":"string"},"status_code":{"description":"Response status code received for the request.","title":"Status Code","type":"integer"}},"required":["status_code"],"title":"Request Validation Error","type":"object"},"RequestValidationErrorInfo":{"description":"Response content containing extra information for an error.","properties":{"code":{"description":"Short identifier code to classify the error.","title":"Code","type":"string"},"details":{"default":null,"description":"Validation errors with extra information.","items":{"$ref":"#/components/schemas/RequestValidationErrorInfoDetails"},"title":"Detailed Message","type":"array"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"}},"required":["code","path"],"title":"Error Information","type":"object"},"RequestValidationErrorInfoDetails":{"description":"An individual validation error with extra information.","properties":{"error_type":{"default":null,"description":"A description of the validation constraint that was broken.","title":"Constraint Type"},"location":{"default":null,"description":"One or more parameters for where the validation failed.","title":"Validation Location"}},"title":"Detailed Error Content","type":"object"}}},"paths":{"/batches":{"get":{"description":"Retrieve a list of batches.","operationId":"retrieve_batches_batches_get","parameters":[{"description":"A pagination field for looking up items in the previous page of results from this resource `id`. Use the first item in the `data` field of the previous response.","in":"query","name":"created-before","required":false,"schema":{"anyOf":[{"maxLength":255,"minLength":1,"pattern":"^\\w+$","type":"string"},{"type":"null"}],"description":"A pagination field for looking up items in the previous page of results from this resource `id`. Use the first item in the `data` field of the previous response.","title":"Created-Before"}},{"description":"A pagination field for looking up items in the next page of results from this resource `id`. Use the final item in the `data` field of the previous response.","in":"query","name":"created-after","required":false,"schema":{"anyOf":[{"maxLength":255,"minLength":1,"pattern":"^\\w+$","type":"string"},{"type":"null"}],"description":"A pagination field for looking up items in the next page of results from this resource `id`. Use the final item in the `data` field of the previous response.","title":"Created-After"}},{"description":"Limit the number of results in the `data` field of the returned list. The number of items in the page can be fewer than the requested value.","in":"query","name":"size","required":false,"schema":{"default":50,"description":"Limit the number of results in the `data` field of the returned list. The number of items in the page can be fewer than the requested value.","maximum":100,"minimum":1,"title":"Size","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResourceList_BatchResource_"}}},"description":"Returns a list of batches."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}},"description":"Request validation failed."}},"summary":"List batches","tags":["Batches"]}}}}
```

## Create a batch

> Create a new batch of retrosynthesis jobs. Individual jobs are provided as a collection of molecules and share a set of \`parameters\` options for each.\
> \
> \- Provide additional metadata to tag and identify the batch.\
> \- The batch size limit is 10000 jobs, although for requests that timeout or fail can be updated with jobs after creation.

```json
{"openapi":"3.1.0","info":{"title":"PAI Retro","version":"v2"},"tags":[{"description":"\nA high-throughput screening campaign for large-scale chemical libraries can be achieved\nthrough submitting *batches* of **Retrosynthesis** jobs with shared `parameters`. Pending\nAI offers batch sizes of up to 100000 jobs which can be created and then appended to with\nadditional API requests. Batch progress can be tracked with live updates to the number of\ncompleted jobs and a high-level screening overview can be retrieved.\n\nBatch synthesis jobs impact the overall queue size for a given engine. Larger batches may\nlead to a longer wait time for it to complete. Additional metadata data can also be added\nto the batch submission to help distinguish results beyond an arbitrary batch `id` field.\n\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility)\nfor more information on our **Retrosynthesis** capability.\n                ","name":"Batches"}],"servers":[{"description":"Pending AI Server","url":"https://api.pending.ai/retro/v2","variables":{"environment":{"default":"api","description":"The environment to use for the API.","enum":["api","api.dev","api.stage"]}}}],"security":[{"oauth":[""],"token":[""]}],"components":{"securitySchemes":{"oauth":{"description":"OAuth2 authentication.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","refreshUrl":"https://auth.pending.ai/oauth/token","scopes":{}}},"type":"oauth2"}},"schemas":{"pai_retro__models__batches__Batch__CreateParams":{"description":"Request data for creating a new batch.","properties":{"description":{"anyOf":[{"maxLength":2048,"type":"string"},{"type":"null"}],"description":"An optional name for the batch. The name provides a human-\nreadable identifier for the batch and is not required to be \nunique.","title":"Description"},"filename":{"anyOf":[{"maxLength":2048,"type":"string"},{"type":"null"}],"description":"An optional filename to help identify the batch and ideal for \nwhen a batch is submitted via file.","title":"Filename"},"name":{"anyOf":[{"maxLength":128,"type":"string"},{"type":"null"}],"description":"An optional name for the batch. The name provides a human-\nreadable identifier for the batch and is not required to be \nunique.","title":"Name"},"parameters":{"$ref":"#/components/schemas/Parameters","description":"Parameters used for controlling the retrosynthesis process. \nThese options are shared across all jobs that belong to the \nbatch."},"smiles":{"description":"A collection of target molecules in a SMILES format to perform \nretrosynthesis on. Each structure is submitted as an individual \njob and queued separately.\n\n**NOTE**: Duplicate structures are removed automatically.","items":{"pattern":"^[a-zA-Z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*]+$","type":"string"},"maxItems":100000,"minItems":1,"title":"Smiles","type":"array"}},"required":["smiles","parameters"],"title":"BatchCreateParams","type":"object"},"Parameters":{"description":"Retrosynthesis configuration parameters. These values control the\nsynthesis planning process and impact the generation procedure and\npotential results. Refer to individual parameters for more details.","properties":{"building_block_libraries":{"description":"A list of building block library `id`s used for controlling \nsynthetic route termination. Refer to documentation on libraries.","items":{"pattern":"^\\w+$","type":"string"},"minItems":1,"title":"Building Block Libraries","type":"array"},"building_block_limit":{"default":3,"description":"The maximum number of times a single building block molecule can \nappear in the result set of a retrosynthesis job.","maximum":25,"minimum":1,"title":"Building Block Limit","type":"integer"},"number_of_routes":{"default":25,"description":"The maximum number of routes to be generated by the retrosynthesis \nengine. Synthetic routes can be limited by the number found, chosen \nbuilding block libraries, and other control parameters.","maximum":50,"minimum":1,"title":"Number Of Routes","type":"integer"},"processing_time":{"default":300,"description":"The maximum allowable processing time to complete a target molecule.\nA retrosynthesis job will exit if this time is exceeded with either\nno result or fewer routes than requested in `number_of_routes`.","maximum":720,"minimum":60,"title":"Processing Time","type":"integer"},"reaction_limit":{"default":3,"description":"The maximum number of times a single reaction synthesis step can\nappear in the result set of a retrosynthesis job.","maximum":25,"minimum":1,"title":"Reaction Limit","type":"integer"},"retrosynthesis_engine":{"description":"A retrosynthesis engine `id` used for executing the synthesis \nplanning procedure. Refer to documentation on engines.","pattern":"^\\w+$","title":"Retrosynthesis Engine","type":"string"}},"required":["retrosynthesis_engine","building_block_libraries"],"title":"Parameters","type":"object"},"BatchResource":{"description":"Batches are collections of retrosynthesis jobs that share a common\nset of parameters. Batches allow for easy management of large sets\nof synthesis targets and provide a mechanism for tracking the status\nof multiple jobs as a single entity.\n\nThere is an upper limit of 100,000 jobs per batch which requires any\nfurther jobs to be submitted in a new batch. Multiple identifiers\ncan be used to distinguish between them.","properties":{"created":{"description":"Timestamp for when the batch was created.","format":"date-time","title":"Created","type":"string"},"description":{"anyOf":[{"maxLength":2048,"pattern":"^[\\w\\s\\-\\:]*$","type":"string"},{"type":"null"}],"description":"An optional description for the batch. The description provides\nadditional context about the batch to help with distinguishing\nbetween other batches.","title":"Description"},"filename":{"anyOf":[{"maxLength":2048,"pattern":"^[\\w\\-\\:]*$","type":"string"},{"type":"null"}],"description":"An optional filename to help identify the batch and ideal for when a\nbatch is submitted via file.","title":"Filename"},"id":{"description":"The unique resource identifier.","pattern":"^\\w+$","title":"Resource Id","type":"string"},"name":{"anyOf":[{"maxLength":256,"pattern":"^[\\w\\s\\-\\:]*$","type":"string"},{"type":"null"}],"description":"An optional name for the batch. The name provides a human-readable\nidentifier for the batch and is not required to be unique.","title":"Name"},"number_of_jobs":{"description":"Total number of retrosynthesis jobs that belong to a batch. The\nvalue can change over time as new jobs are added to the batch.","maximum":100000,"minimum":1,"title":"Number Of Jobs","type":"integer"},"object":{"description":"The type of resource.","pattern":"^\\w+$","title":"Resource Object","type":"string"},"parameters":{"$ref":"#/components/schemas/Parameters","description":"Parameters used for controlling the retrosynthesis process. These\noptions are shared across all jobs that belong to the batch."},"updated":{"description":"Timestamp for when the batch was last updated.","format":"date-time","title":"Updated","type":"string"}},"required":["id","object","number_of_jobs","parameters"],"title":"Batch","type":"object"},"RequestValidationErrorContent":{"description":"A request or response encountered a validation error when enforcing field constraints. Refer to `error.details` to resolve individual errors. For any unexpected validation errors, contact Pending AI support via email at [support@pending.ai](mailto:support@pending.ai).","properties":{"error":{"$ref":"#/components/schemas/RequestValidationErrorInfo","default":null},"request_id":{"default":null,"description":"A unique ID given to each request.","title":"Request ID","type":"string"},"status":{"default":"error","description":"Status of the request.","enum":["error","success"],"title":"Request Status","type":"string"},"status_code":{"description":"Response status code received for the request.","title":"Status Code","type":"integer"}},"required":["status_code"],"title":"Request Validation Error","type":"object"},"RequestValidationErrorInfo":{"description":"Response content containing extra information for an error.","properties":{"code":{"description":"Short identifier code to classify the error.","title":"Code","type":"string"},"details":{"default":null,"description":"Validation errors with extra information.","items":{"$ref":"#/components/schemas/RequestValidationErrorInfoDetails"},"title":"Detailed Message","type":"array"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"}},"required":["code","path"],"title":"Error Information","type":"object"},"RequestValidationErrorInfoDetails":{"description":"An individual validation error with extra information.","properties":{"error_type":{"default":null,"description":"A description of the validation constraint that was broken.","title":"Constraint Type"},"location":{"default":null,"description":"One or more parameters for where the validation failed.","title":"Validation Location"}},"title":"Detailed Error Content","type":"object"}}},"paths":{"/batches":{"post":{"description":"Create a new batch of retrosynthesis jobs. Individual jobs are provided as a collection of molecules and share a set of `parameters` options for each.\n\n- Provide additional metadata to tag and identify the batch.\n- The batch size limit is 10000 jobs, although for requests that timeout or fail can be updated with jobs after creation.","operationId":"create_batch_batches_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/pai_retro__models__batches__Batch__CreateParams"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResource"}}},"description":"Returns the batch."},"402":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Payment gateway failed."},"413":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Batch resource exceeded size limit."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}},"description":"Request validation failed."}},"summary":"Create a batch","tags":["Batches"]}}}}
```

## Retrieve a batch

> Retrieve a batch with attached metadata and job parameters.

```json
{"openapi":"3.1.0","info":{"title":"PAI Retro","version":"v2"},"tags":[{"description":"\nA high-throughput screening campaign for large-scale chemical libraries can be achieved\nthrough submitting *batches* of **Retrosynthesis** jobs with shared `parameters`. Pending\nAI offers batch sizes of up to 100000 jobs which can be created and then appended to with\nadditional API requests. Batch progress can be tracked with live updates to the number of\ncompleted jobs and a high-level screening overview can be retrieved.\n\nBatch synthesis jobs impact the overall queue size for a given engine. Larger batches may\nlead to a longer wait time for it to complete. Additional metadata data can also be added\nto the batch submission to help distinguish results beyond an arbitrary batch `id` field.\n\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility)\nfor more information on our **Retrosynthesis** capability.\n                ","name":"Batches"}],"servers":[{"description":"Pending AI Server","url":"https://api.pending.ai/retro/v2","variables":{"environment":{"default":"api","description":"The environment to use for the API.","enum":["api","api.dev","api.stage"]}}}],"security":[{"oauth":[""],"token":[""]}],"components":{"securitySchemes":{"oauth":{"description":"OAuth2 authentication.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","refreshUrl":"https://auth.pending.ai/oauth/token","scopes":{}}},"type":"oauth2"}},"schemas":{"BatchResource":{"description":"Batches are collections of retrosynthesis jobs that share a common\nset of parameters. Batches allow for easy management of large sets\nof synthesis targets and provide a mechanism for tracking the status\nof multiple jobs as a single entity.\n\nThere is an upper limit of 100,000 jobs per batch which requires any\nfurther jobs to be submitted in a new batch. Multiple identifiers\ncan be used to distinguish between them.","properties":{"created":{"description":"Timestamp for when the batch was created.","format":"date-time","title":"Created","type":"string"},"description":{"anyOf":[{"maxLength":2048,"pattern":"^[\\w\\s\\-\\:]*$","type":"string"},{"type":"null"}],"description":"An optional description for the batch. The description provides\nadditional context about the batch to help with distinguishing\nbetween other batches.","title":"Description"},"filename":{"anyOf":[{"maxLength":2048,"pattern":"^[\\w\\-\\:]*$","type":"string"},{"type":"null"}],"description":"An optional filename to help identify the batch and ideal for when a\nbatch is submitted via file.","title":"Filename"},"id":{"description":"The unique resource identifier.","pattern":"^\\w+$","title":"Resource Id","type":"string"},"name":{"anyOf":[{"maxLength":256,"pattern":"^[\\w\\s\\-\\:]*$","type":"string"},{"type":"null"}],"description":"An optional name for the batch. The name provides a human-readable\nidentifier for the batch and is not required to be unique.","title":"Name"},"number_of_jobs":{"description":"Total number of retrosynthesis jobs that belong to a batch. The\nvalue can change over time as new jobs are added to the batch.","maximum":100000,"minimum":1,"title":"Number Of Jobs","type":"integer"},"object":{"description":"The type of resource.","pattern":"^\\w+$","title":"Resource Object","type":"string"},"parameters":{"$ref":"#/components/schemas/Parameters","description":"Parameters used for controlling the retrosynthesis process. These\noptions are shared across all jobs that belong to the batch."},"updated":{"description":"Timestamp for when the batch was last updated.","format":"date-time","title":"Updated","type":"string"}},"required":["id","object","number_of_jobs","parameters"],"title":"Batch","type":"object"},"Parameters":{"description":"Retrosynthesis configuration parameters. These values control the\nsynthesis planning process and impact the generation procedure and\npotential results. Refer to individual parameters for more details.","properties":{"building_block_libraries":{"description":"A list of building block library `id`s used for controlling \nsynthetic route termination. Refer to documentation on libraries.","items":{"pattern":"^\\w+$","type":"string"},"minItems":1,"title":"Building Block Libraries","type":"array"},"building_block_limit":{"default":3,"description":"The maximum number of times a single building block molecule can \nappear in the result set of a retrosynthesis job.","maximum":25,"minimum":1,"title":"Building Block Limit","type":"integer"},"number_of_routes":{"default":25,"description":"The maximum number of routes to be generated by the retrosynthesis \nengine. Synthetic routes can be limited by the number found, chosen \nbuilding block libraries, and other control parameters.","maximum":50,"minimum":1,"title":"Number Of Routes","type":"integer"},"processing_time":{"default":300,"description":"The maximum allowable processing time to complete a target molecule.\nA retrosynthesis job will exit if this time is exceeded with either\nno result or fewer routes than requested in `number_of_routes`.","maximum":720,"minimum":60,"title":"Processing Time","type":"integer"},"reaction_limit":{"default":3,"description":"The maximum number of times a single reaction synthesis step can\nappear in the result set of a retrosynthesis job.","maximum":25,"minimum":1,"title":"Reaction Limit","type":"integer"},"retrosynthesis_engine":{"description":"A retrosynthesis engine `id` used for executing the synthesis \nplanning procedure. Refer to documentation on engines.","pattern":"^\\w+$","title":"Retrosynthesis Engine","type":"string"}},"required":["retrosynthesis_engine","building_block_libraries"],"title":"Parameters","type":"object"},"RequestValidationErrorContent":{"description":"A request or response encountered a validation error when enforcing field constraints. Refer to `error.details` to resolve individual errors. For any unexpected validation errors, contact Pending AI support via email at [support@pending.ai](mailto:support@pending.ai).","properties":{"error":{"$ref":"#/components/schemas/RequestValidationErrorInfo","default":null},"request_id":{"default":null,"description":"A unique ID given to each request.","title":"Request ID","type":"string"},"status":{"default":"error","description":"Status of the request.","enum":["error","success"],"title":"Request Status","type":"string"},"status_code":{"description":"Response status code received for the request.","title":"Status Code","type":"integer"}},"required":["status_code"],"title":"Request Validation Error","type":"object"},"RequestValidationErrorInfo":{"description":"Response content containing extra information for an error.","properties":{"code":{"description":"Short identifier code to classify the error.","title":"Code","type":"string"},"details":{"default":null,"description":"Validation errors with extra information.","items":{"$ref":"#/components/schemas/RequestValidationErrorInfoDetails"},"title":"Detailed Message","type":"array"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"}},"required":["code","path"],"title":"Error Information","type":"object"},"RequestValidationErrorInfoDetails":{"description":"An individual validation error with extra information.","properties":{"error_type":{"default":null,"description":"A description of the validation constraint that was broken.","title":"Constraint Type"},"location":{"default":null,"description":"One or more parameters for where the validation failed.","title":"Validation Location"}},"title":"Detailed Error Content","type":"object"}}},"paths":{"/batches/{batch_id}":{"get":{"description":"Retrieve a batch with attached metadata and job parameters.","operationId":"retrieve_batch_batches__batch_id__get","parameters":[{"description":"A unique identifier for a batch resource.","in":"path","name":"batch_id","required":true,"schema":{"description":"A unique identifier for a batch resource.","maxLength":255,"minLength":1,"pattern":"^\\w+$","title":"Batch Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResource"}}},"description":"Returns the batch."},"404":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Batch resource not found."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}},"description":"Request validation failed."}},"summary":"Retrieve a batch","tags":["Batches"]}}}}
```

## Update a batch

> Update a batch resource with more retrosynthesis jobs. The added jobs are queued but must not exceed the total batch limit for a batch resource.

```json
{"openapi":"3.1.0","info":{"title":"PAI Retro","version":"v2"},"tags":[{"description":"\nA high-throughput screening campaign for large-scale chemical libraries can be achieved\nthrough submitting *batches* of **Retrosynthesis** jobs with shared `parameters`. Pending\nAI offers batch sizes of up to 100000 jobs which can be created and then appended to with\nadditional API requests. Batch progress can be tracked with live updates to the number of\ncompleted jobs and a high-level screening overview can be retrieved.\n\nBatch synthesis jobs impact the overall queue size for a given engine. Larger batches may\nlead to a longer wait time for it to complete. Additional metadata data can also be added\nto the batch submission to help distinguish results beyond an arbitrary batch `id` field.\n\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility)\nfor more information on our **Retrosynthesis** capability.\n                ","name":"Batches"}],"servers":[{"description":"Pending AI Server","url":"https://api.pending.ai/retro/v2","variables":{"environment":{"default":"api","description":"The environment to use for the API.","enum":["api","api.dev","api.stage"]}}}],"security":[{"oauth":[""],"token":[""]}],"components":{"securitySchemes":{"oauth":{"description":"OAuth2 authentication.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","refreshUrl":"https://auth.pending.ai/oauth/token","scopes":{}}},"type":"oauth2"}},"schemas":{"UpdateParams":{"description":"Request data for updating an existing batch.","properties":{"smiles":{"description":"A collection of target molecules in a SMILES format to perform \nretrosynthesis on. Each structure is submitted as an individual \njob and queued separately.\n\n**NOTE**: Duplicate structures are removed automatically.","items":{"pattern":"^[a-zA-Z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*]+$","type":"string"},"maxItems":100000,"minItems":1,"title":"Smiles","type":"array"}},"required":["smiles"],"title":"BatchUpdateParams","type":"object"},"BatchResource":{"description":"Batches are collections of retrosynthesis jobs that share a common\nset of parameters. Batches allow for easy management of large sets\nof synthesis targets and provide a mechanism for tracking the status\nof multiple jobs as a single entity.\n\nThere is an upper limit of 100,000 jobs per batch which requires any\nfurther jobs to be submitted in a new batch. Multiple identifiers\ncan be used to distinguish between them.","properties":{"created":{"description":"Timestamp for when the batch was created.","format":"date-time","title":"Created","type":"string"},"description":{"anyOf":[{"maxLength":2048,"pattern":"^[\\w\\s\\-\\:]*$","type":"string"},{"type":"null"}],"description":"An optional description for the batch. The description provides\nadditional context about the batch to help with distinguishing\nbetween other batches.","title":"Description"},"filename":{"anyOf":[{"maxLength":2048,"pattern":"^[\\w\\-\\:]*$","type":"string"},{"type":"null"}],"description":"An optional filename to help identify the batch and ideal for when a\nbatch is submitted via file.","title":"Filename"},"id":{"description":"The unique resource identifier.","pattern":"^\\w+$","title":"Resource Id","type":"string"},"name":{"anyOf":[{"maxLength":256,"pattern":"^[\\w\\s\\-\\:]*$","type":"string"},{"type":"null"}],"description":"An optional name for the batch. The name provides a human-readable\nidentifier for the batch and is not required to be unique.","title":"Name"},"number_of_jobs":{"description":"Total number of retrosynthesis jobs that belong to a batch. The\nvalue can change over time as new jobs are added to the batch.","maximum":100000,"minimum":1,"title":"Number Of Jobs","type":"integer"},"object":{"description":"The type of resource.","pattern":"^\\w+$","title":"Resource Object","type":"string"},"parameters":{"$ref":"#/components/schemas/Parameters","description":"Parameters used for controlling the retrosynthesis process. These\noptions are shared across all jobs that belong to the batch."},"updated":{"description":"Timestamp for when the batch was last updated.","format":"date-time","title":"Updated","type":"string"}},"required":["id","object","number_of_jobs","parameters"],"title":"Batch","type":"object"},"Parameters":{"description":"Retrosynthesis configuration parameters. These values control the\nsynthesis planning process and impact the generation procedure and\npotential results. Refer to individual parameters for more details.","properties":{"building_block_libraries":{"description":"A list of building block library `id`s used for controlling \nsynthetic route termination. Refer to documentation on libraries.","items":{"pattern":"^\\w+$","type":"string"},"minItems":1,"title":"Building Block Libraries","type":"array"},"building_block_limit":{"default":3,"description":"The maximum number of times a single building block molecule can \nappear in the result set of a retrosynthesis job.","maximum":25,"minimum":1,"title":"Building Block Limit","type":"integer"},"number_of_routes":{"default":25,"description":"The maximum number of routes to be generated by the retrosynthesis \nengine. Synthetic routes can be limited by the number found, chosen \nbuilding block libraries, and other control parameters.","maximum":50,"minimum":1,"title":"Number Of Routes","type":"integer"},"processing_time":{"default":300,"description":"The maximum allowable processing time to complete a target molecule.\nA retrosynthesis job will exit if this time is exceeded with either\nno result or fewer routes than requested in `number_of_routes`.","maximum":720,"minimum":60,"title":"Processing Time","type":"integer"},"reaction_limit":{"default":3,"description":"The maximum number of times a single reaction synthesis step can\nappear in the result set of a retrosynthesis job.","maximum":25,"minimum":1,"title":"Reaction Limit","type":"integer"},"retrosynthesis_engine":{"description":"A retrosynthesis engine `id` used for executing the synthesis \nplanning procedure. Refer to documentation on engines.","pattern":"^\\w+$","title":"Retrosynthesis Engine","type":"string"}},"required":["retrosynthesis_engine","building_block_libraries"],"title":"Parameters","type":"object"},"RequestValidationErrorContent":{"description":"A request or response encountered a validation error when enforcing field constraints. Refer to `error.details` to resolve individual errors. For any unexpected validation errors, contact Pending AI support via email at [support@pending.ai](mailto:support@pending.ai).","properties":{"error":{"$ref":"#/components/schemas/RequestValidationErrorInfo","default":null},"request_id":{"default":null,"description":"A unique ID given to each request.","title":"Request ID","type":"string"},"status":{"default":"error","description":"Status of the request.","enum":["error","success"],"title":"Request Status","type":"string"},"status_code":{"description":"Response status code received for the request.","title":"Status Code","type":"integer"}},"required":["status_code"],"title":"Request Validation Error","type":"object"},"RequestValidationErrorInfo":{"description":"Response content containing extra information for an error.","properties":{"code":{"description":"Short identifier code to classify the error.","title":"Code","type":"string"},"details":{"default":null,"description":"Validation errors with extra information.","items":{"$ref":"#/components/schemas/RequestValidationErrorInfoDetails"},"title":"Detailed Message","type":"array"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"}},"required":["code","path"],"title":"Error Information","type":"object"},"RequestValidationErrorInfoDetails":{"description":"An individual validation error with extra information.","properties":{"error_type":{"default":null,"description":"A description of the validation constraint that was broken.","title":"Constraint Type"},"location":{"default":null,"description":"One or more parameters for where the validation failed.","title":"Validation Location"}},"title":"Detailed Error Content","type":"object"}}},"paths":{"/batches/{batch_id}":{"put":{"description":"Update a batch resource with more retrosynthesis jobs. The added jobs are queued but must not exceed the total batch limit for a batch resource.","operationId":"update_batch_batches__batch_id__put","parameters":[{"description":"A unique identifier for a batch resource.","in":"path","name":"batch_id","required":true,"schema":{"description":"A unique identifier for a batch resource.","maxLength":255,"minLength":1,"pattern":"^\\w+$","title":"Batch Id","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateParams"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResource"}}},"description":"Returns the updated batch."},"402":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Payment gateway failed."},"404":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Batch resource not found."},"413":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Batch resource exceeded size limit."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}},"description":"Request validation failed."}},"summary":"Update a batch","tags":["Batches"]}}}}
```

## Delete a batch

> Delete a batch resource and all attached retrosynthesis jobs. When the request is made for a batch currently being processed, all queued jobs are cancelled.

```json
{"openapi":"3.1.0","info":{"title":"PAI Retro","version":"v2"},"tags":[{"description":"\nA high-throughput screening campaign for large-scale chemical libraries can be achieved\nthrough submitting *batches* of **Retrosynthesis** jobs with shared `parameters`. Pending\nAI offers batch sizes of up to 100000 jobs which can be created and then appended to with\nadditional API requests. Batch progress can be tracked with live updates to the number of\ncompleted jobs and a high-level screening overview can be retrieved.\n\nBatch synthesis jobs impact the overall queue size for a given engine. Larger batches may\nlead to a longer wait time for it to complete. Additional metadata data can also be added\nto the batch submission to help distinguish results beyond an arbitrary batch `id` field.\n\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility)\nfor more information on our **Retrosynthesis** capability.\n                ","name":"Batches"}],"servers":[{"description":"Pending AI Server","url":"https://api.pending.ai/retro/v2","variables":{"environment":{"default":"api","description":"The environment to use for the API.","enum":["api","api.dev","api.stage"]}}}],"security":[{"oauth":[""],"token":[""]}],"components":{"securitySchemes":{"oauth":{"description":"OAuth2 authentication.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","refreshUrl":"https://auth.pending.ai/oauth/token","scopes":{}}},"type":"oauth2"}},"schemas":{"BatchResource":{"description":"Batches are collections of retrosynthesis jobs that share a common\nset of parameters. Batches allow for easy management of large sets\nof synthesis targets and provide a mechanism for tracking the status\nof multiple jobs as a single entity.\n\nThere is an upper limit of 100,000 jobs per batch which requires any\nfurther jobs to be submitted in a new batch. Multiple identifiers\ncan be used to distinguish between them.","properties":{"created":{"description":"Timestamp for when the batch was created.","format":"date-time","title":"Created","type":"string"},"description":{"anyOf":[{"maxLength":2048,"pattern":"^[\\w\\s\\-\\:]*$","type":"string"},{"type":"null"}],"description":"An optional description for the batch. The description provides\nadditional context about the batch to help with distinguishing\nbetween other batches.","title":"Description"},"filename":{"anyOf":[{"maxLength":2048,"pattern":"^[\\w\\-\\:]*$","type":"string"},{"type":"null"}],"description":"An optional filename to help identify the batch and ideal for when a\nbatch is submitted via file.","title":"Filename"},"id":{"description":"The unique resource identifier.","pattern":"^\\w+$","title":"Resource Id","type":"string"},"name":{"anyOf":[{"maxLength":256,"pattern":"^[\\w\\s\\-\\:]*$","type":"string"},{"type":"null"}],"description":"An optional name for the batch. The name provides a human-readable\nidentifier for the batch and is not required to be unique.","title":"Name"},"number_of_jobs":{"description":"Total number of retrosynthesis jobs that belong to a batch. The\nvalue can change over time as new jobs are added to the batch.","maximum":100000,"minimum":1,"title":"Number Of Jobs","type":"integer"},"object":{"description":"The type of resource.","pattern":"^\\w+$","title":"Resource Object","type":"string"},"parameters":{"$ref":"#/components/schemas/Parameters","description":"Parameters used for controlling the retrosynthesis process. These\noptions are shared across all jobs that belong to the batch."},"updated":{"description":"Timestamp for when the batch was last updated.","format":"date-time","title":"Updated","type":"string"}},"required":["id","object","number_of_jobs","parameters"],"title":"Batch","type":"object"},"Parameters":{"description":"Retrosynthesis configuration parameters. These values control the\nsynthesis planning process and impact the generation procedure and\npotential results. Refer to individual parameters for more details.","properties":{"building_block_libraries":{"description":"A list of building block library `id`s used for controlling \nsynthetic route termination. Refer to documentation on libraries.","items":{"pattern":"^\\w+$","type":"string"},"minItems":1,"title":"Building Block Libraries","type":"array"},"building_block_limit":{"default":3,"description":"The maximum number of times a single building block molecule can \nappear in the result set of a retrosynthesis job.","maximum":25,"minimum":1,"title":"Building Block Limit","type":"integer"},"number_of_routes":{"default":25,"description":"The maximum number of routes to be generated by the retrosynthesis \nengine. Synthetic routes can be limited by the number found, chosen \nbuilding block libraries, and other control parameters.","maximum":50,"minimum":1,"title":"Number Of Routes","type":"integer"},"processing_time":{"default":300,"description":"The maximum allowable processing time to complete a target molecule.\nA retrosynthesis job will exit if this time is exceeded with either\nno result or fewer routes than requested in `number_of_routes`.","maximum":720,"minimum":60,"title":"Processing Time","type":"integer"},"reaction_limit":{"default":3,"description":"The maximum number of times a single reaction synthesis step can\nappear in the result set of a retrosynthesis job.","maximum":25,"minimum":1,"title":"Reaction Limit","type":"integer"},"retrosynthesis_engine":{"description":"A retrosynthesis engine `id` used for executing the synthesis \nplanning procedure. Refer to documentation on engines.","pattern":"^\\w+$","title":"Retrosynthesis Engine","type":"string"}},"required":["retrosynthesis_engine","building_block_libraries"],"title":"Parameters","type":"object"},"RequestValidationErrorContent":{"description":"A request or response encountered a validation error when enforcing field constraints. Refer to `error.details` to resolve individual errors. For any unexpected validation errors, contact Pending AI support via email at [support@pending.ai](mailto:support@pending.ai).","properties":{"error":{"$ref":"#/components/schemas/RequestValidationErrorInfo","default":null},"request_id":{"default":null,"description":"A unique ID given to each request.","title":"Request ID","type":"string"},"status":{"default":"error","description":"Status of the request.","enum":["error","success"],"title":"Request Status","type":"string"},"status_code":{"description":"Response status code received for the request.","title":"Status Code","type":"integer"}},"required":["status_code"],"title":"Request Validation Error","type":"object"},"RequestValidationErrorInfo":{"description":"Response content containing extra information for an error.","properties":{"code":{"description":"Short identifier code to classify the error.","title":"Code","type":"string"},"details":{"default":null,"description":"Validation errors with extra information.","items":{"$ref":"#/components/schemas/RequestValidationErrorInfoDetails"},"title":"Detailed Message","type":"array"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"}},"required":["code","path"],"title":"Error Information","type":"object"},"RequestValidationErrorInfoDetails":{"description":"An individual validation error with extra information.","properties":{"error_type":{"default":null,"description":"A description of the validation constraint that was broken.","title":"Constraint Type"},"location":{"default":null,"description":"One or more parameters for where the validation failed.","title":"Validation Location"}},"title":"Detailed Error Content","type":"object"}}},"paths":{"/batches/{batch_id}":{"delete":{"description":"Delete a batch resource and all attached retrosynthesis jobs. When the request is made for a batch currently being processed, all queued jobs are cancelled.","operationId":"delete_batch_batches__batch_id__delete","parameters":[{"description":"A unique identifier for a batch resource.","in":"path","name":"batch_id","required":true,"schema":{"description":"A unique identifier for a batch resource.","maxLength":255,"minLength":1,"pattern":"^\\w+$","title":"Batch Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResource"}}},"description":"Returns the deleted batch."},"402":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Payment gateway failed."},"404":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Batch resource not found."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}},"description":"Request validation failed."}},"summary":"Delete a batch","tags":["Batches"]}}}}
```

## Retrieve a batch result

> Retrieve the collection of results from retrosynthesis jobs in the batch. The list contains information about the individual job \`id\`s used for retrieving synthetic routes and whether the molecules were synthesizable.

```json
{"openapi":"3.1.0","info":{"title":"PAI Retro","version":"v2"},"tags":[{"description":"\nA high-throughput screening campaign for large-scale chemical libraries can be achieved\nthrough submitting *batches* of **Retrosynthesis** jobs with shared `parameters`. Pending\nAI offers batch sizes of up to 100000 jobs which can be created and then appended to with\nadditional API requests. Batch progress can be tracked with live updates to the number of\ncompleted jobs and a high-level screening overview can be retrieved.\n\nBatch synthesis jobs impact the overall queue size for a given engine. Larger batches may\nlead to a longer wait time for it to complete. Additional metadata data can also be added\nto the batch submission to help distinguish results beyond an arbitrary batch `id` field.\n\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility)\nfor more information on our **Retrosynthesis** capability.\n                ","name":"Batches"}],"servers":[{"description":"Pending AI Server","url":"https://api.pending.ai/retro/v2","variables":{"environment":{"default":"api","description":"The environment to use for the API.","enum":["api","api.dev","api.stage"]}}}],"security":[{"oauth":[""],"token":[""]}],"components":{"securitySchemes":{"oauth":{"description":"OAuth2 authentication.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","refreshUrl":"https://auth.pending.ai/oauth/token","scopes":{}}},"type":"oauth2"}},"schemas":{"RetrieveResultOutputItem":{"description":"Summary result for an individual job in a batch. Provides an\noverview of the job status and if any retrosynthesis results\nwere found.","properties":{"completed":{"description":"A flag to indicate if the job is completed. Results retrieved\nbefore a batch has completed may contain incomplete jobs.","title":"Completed","type":"boolean"},"job_id":{"description":"A unique identifier for the retrosynthesis job. The value can be\nused to retrieve the full job resource with any results.","pattern":"^\\w+$","title":"Job Id","type":"string"},"smiles":{"description":"The retrosynthesis target structure in a SMILES format.","pattern":"^[a-zA-Z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*]+$","title":"Smiles","type":"string"},"synthesizable":{"description":"A flag to indicate if the structure is synthesizable. A\nstructure is considered synthesizable if at least one synthesis\nroute was found during retrosynthesis.","title":"Synthesizable","type":"boolean"}},"required":["job_id","smiles","completed","synthesizable"],"title":"BatchResult","type":"object"},"RequestValidationErrorContent":{"description":"A request or response encountered a validation error when enforcing field constraints. Refer to `error.details` to resolve individual errors. For any unexpected validation errors, contact Pending AI support via email at [support@pending.ai](mailto:support@pending.ai).","properties":{"error":{"$ref":"#/components/schemas/RequestValidationErrorInfo","default":null},"request_id":{"default":null,"description":"A unique ID given to each request.","title":"Request ID","type":"string"},"status":{"default":"error","description":"Status of the request.","enum":["error","success"],"title":"Request Status","type":"string"},"status_code":{"description":"Response status code received for the request.","title":"Status Code","type":"integer"}},"required":["status_code"],"title":"Request Validation Error","type":"object"},"RequestValidationErrorInfo":{"description":"Response content containing extra information for an error.","properties":{"code":{"description":"Short identifier code to classify the error.","title":"Code","type":"string"},"details":{"default":null,"description":"Validation errors with extra information.","items":{"$ref":"#/components/schemas/RequestValidationErrorInfoDetails"},"title":"Detailed Message","type":"array"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"}},"required":["code","path"],"title":"Error Information","type":"object"},"RequestValidationErrorInfoDetails":{"description":"An individual validation error with extra information.","properties":{"error_type":{"default":null,"description":"A description of the validation constraint that was broken.","title":"Constraint Type"},"location":{"default":null,"description":"One or more parameters for where the validation failed.","title":"Validation Location"}},"title":"Detailed Error Content","type":"object"}}},"paths":{"/batches/{batch_id}/result":{"get":{"description":"Retrieve the collection of results from retrosynthesis jobs in the batch. The list contains information about the individual job `id`s used for retrieving synthetic routes and whether the molecules were synthesizable.","operationId":"retrieve_batch_result_batches__batch_id__result_get","parameters":[{"description":"A unique identifier for a batch resource.","in":"path","name":"batch_id","required":true,"schema":{"description":"A unique identifier for a batch resource.","maxLength":255,"minLength":1,"pattern":"^\\w+$","title":"Batch Id","type":"string"}},{"description":"Providing this header and the value `gzip` yields results from the endpoint as gzipped plaintext with a base64 encoding.","in":"header","name":"accept-encoding","required":false,"schema":{"anyOf":[{"const":"gzip","type":"string"},{"type":"null"}],"description":"Providing this header and the value `gzip` yields results from the endpoint as gzipped plaintext with a base64 encoding.","title":"Accept-Encoding"}}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/RetrieveResultOutputItem"},"title":"Return","type":"array"}}},"description":"Returns the batch result."},"404":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Batch resource not found."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}},"description":"Request validation failed."}},"summary":"Retrieve a batch result","tags":["Batches"]}}}}
```

## Retrieve a batch status

> Retrieve the current status of a batch. The batch status relies on the individual status of all retrosynthesis jobs and can take longer to process. Poll the route with spaced requests compared to the individual retrosynthesis jobs.

```json
{"openapi":"3.1.0","info":{"title":"PAI Retro","version":"v2"},"tags":[{"description":"\nA high-throughput screening campaign for large-scale chemical libraries can be achieved\nthrough submitting *batches* of **Retrosynthesis** jobs with shared `parameters`. Pending\nAI offers batch sizes of up to 100000 jobs which can be created and then appended to with\nadditional API requests. Batch progress can be tracked with live updates to the number of\ncompleted jobs and a high-level screening overview can be retrieved.\n\nBatch synthesis jobs impact the overall queue size for a given engine. Larger batches may\nlead to a longer wait time for it to complete. Additional metadata data can also be added\nto the batch submission to help distinguish results beyond an arbitrary batch `id` field.\n\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility)\nfor more information on our **Retrosynthesis** capability.\n                ","name":"Batches"}],"servers":[{"description":"Pending AI Server","url":"https://api.pending.ai/retro/v2","variables":{"environment":{"default":"api","description":"The environment to use for the API.","enum":["api","api.dev","api.stage"]}}}],"security":[{"oauth":[""],"token":[""]}],"components":{"securitySchemes":{"oauth":{"description":"OAuth2 authentication.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","refreshUrl":"https://auth.pending.ai/oauth/token","scopes":{}}},"type":"oauth2"}},"schemas":{"RetrieveStatusOutput":{"description":"Status information for a batch. Batches require routine polling\nto determine when all jobs have been completed. A batch will be\ncompleted once the `status` transitions to `completed` and the\n`number_of_jobs` matches the `completed_jobs`.","properties":{"completed_jobs":{"description":"The total number of jobs that have completed in the batch.","maximum":100000,"minimum":0,"title":"Completed Jobs","type":"integer"},"number_of_jobs":{"description":"The total number of jobs that have been submitted in the batch.","maximum":100000,"minimum":1,"title":"Number Of Jobs","type":"integer"},"status":{"description":"Current status of the batch.","enum":["submitted","processing","completed"],"title":"Status","type":"string"}},"required":["status","number_of_jobs","completed_jobs"],"title":"BatchStatus","type":"object"},"RequestValidationErrorContent":{"description":"A request or response encountered a validation error when enforcing field constraints. Refer to `error.details` to resolve individual errors. For any unexpected validation errors, contact Pending AI support via email at [support@pending.ai](mailto:support@pending.ai).","properties":{"error":{"$ref":"#/components/schemas/RequestValidationErrorInfo","default":null},"request_id":{"default":null,"description":"A unique ID given to each request.","title":"Request ID","type":"string"},"status":{"default":"error","description":"Status of the request.","enum":["error","success"],"title":"Request Status","type":"string"},"status_code":{"description":"Response status code received for the request.","title":"Status Code","type":"integer"}},"required":["status_code"],"title":"Request Validation Error","type":"object"},"RequestValidationErrorInfo":{"description":"Response content containing extra information for an error.","properties":{"code":{"description":"Short identifier code to classify the error.","title":"Code","type":"string"},"details":{"default":null,"description":"Validation errors with extra information.","items":{"$ref":"#/components/schemas/RequestValidationErrorInfoDetails"},"title":"Detailed Message","type":"array"},"message":{"default":null,"description":"Message associated with the encountered error.","title":"Message"},"path":{"description":"Request path for where the error occurred.","title":"Request Path","type":"string"},"timestamp":{"description":"Timestamp of when the error occurred.","format":"date-time","title":"Timestamp","type":"string"}},"required":["code","path"],"title":"Error Information","type":"object"},"RequestValidationErrorInfoDetails":{"description":"An individual validation error with extra information.","properties":{"error_type":{"default":null,"description":"A description of the validation constraint that was broken.","title":"Constraint Type"},"location":{"default":null,"description":"One or more parameters for where the validation failed.","title":"Validation Location"}},"title":"Detailed Error Content","type":"object"}}},"paths":{"/batches/{batch_id}/status":{"get":{"description":"Retrieve the current status of a batch. The batch status relies on the individual status of all retrosynthesis jobs and can take longer to process. Poll the route with spaced requests compared to the individual retrosynthesis jobs.","operationId":"retrieve_batch_status_batches__batch_id__status_get","parameters":[{"description":"A unique identifier for a batch resource.","in":"path","name":"batch_id","required":true,"schema":{"description":"A unique identifier for a batch resource.","maxLength":255,"minLength":1,"pattern":"^\\w+$","title":"Batch Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrieveStatusOutput"}}},"description":"Returns the batch status."},"404":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Batch resource not found."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}},"description":"Request validation failed."}},"summary":"Retrieve a batch status","tags":["Batches"]}}}}
```


# Agentic AI

Use the Pending AI MCP server to boost LLM possibilities

## Why use Agentic AI?

Agentic workflows are transforming how chemists and pharmaceutical researchers approach the Design-Make-Test-Analyze cycle. Rather than mastering numerous specialized software platforms, scientists can now operate as high-level supervisors while AI agents leverage best-in-class MCP tools to accomplish project objectives. This enables researchers to execute sophisticated, comprehensive campaigns—from de novo molecular design through synthetic route planning—in significantly less time than traditional manual approaches. Pending AI's agentic platform is built to enhance discovery pipeline success rates and accelerate the development of new therapeutics.

## Resources

See the different pages below for more information about our <i class="fa-sparkles">:sparkles:</i> Agentic AI capabilities.

<table data-card-size="large" data-view="cards" data-full-width="false"><thead><tr><th align="center"></th><th align="center"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td align="center"><h4>MCP Server</h4></td><td align="center">Get more information about what the Pending AI MCP Server can achieve.</td><td><a href="/pages/KHHEbG66bToi6ufEfF5F">/pages/KHHEbG66bToi6ufEfF5F</a></td></tr><tr><td align="center"><h4>Quickstart</h4></td><td align="center">Connect to the Pending AI MCP Server directly from your connector of choice.</td><td><a href="/pages/V4NTdYgamVaL59HQcrPj">/pages/V4NTdYgamVaL59HQcrPj</a></td></tr></tbody></table>


# MCP Server

Connect directly to the Pending AI platform from any AI Agent

## Model Context Protocol

Pending AI offers a Model Context Protocol (MCP) server for accessing the different [tool options](#pending-ai-mcp-tools). An MCP server gives existing LLM chats a way to call services enabled for a user and streamline different workflows. There are many possible workflow integrations, for example:

<details>

<summary><i class="fa-messages-question">:messages-question:</i> <a data-footnote-ref href="#user-content-fn-1"><mark style="color:$primary;">Generate</mark></a> a batch of molecules and find any with an amine functional group.</summary>

{% code title="Prompt" %}

```
Generate some random molecules and find any with an amine functional group.
```

{% endcode %}

{% code title="Response (GPT-4.1)" overflow="wrap" %}

```
Here are the generated SMILES that contain an amine functional group (looked for "N", "NH", "NH2" patterns):

1. CCN(CCNCc1cnn(C)c1)C(=O)c1ccccc1N+[O-]
    - Contains secondary and primary amines.
2. C=CCNC(=O)c1cc(-c2ccc(OC)cc2)nc2c(N)c(C(N)=O)oc12
    - Contains primary amine (N), and possibly amidine/amide.
3. NC(c1cc(Br)cs1)c1ccc(Br)cc1OC(F)F
    - Contains primary amine (NC).
4. NS(=O)(=O)c1ccc2c(ccn2C2CCCN(Cc3ccc(Cl)cc3Cl)C2=O)c1
    - Contains sulfonamide (NS(=O)(=O)) and tertiary amine in the ring.
5. Cn1cnc2sc(C(=O)Nc3ccc(N)cc3)cc2c1=N
    - Contains amide (Nc3ccc(N)cc3), and aromatic amine.

These 5 SMILES from the generated set contain at least one amine functional group. Let me know if you want to analyze further or need chemical names.
```

{% endcode %}

</details>

<details>

<summary><i class="fa-messages-question">:messages-question:</i> Perform <a data-footnote-ref href="#user-content-fn-2"><mark style="color:$primary;">retrosynthesis</mark></a> on the previously generated molecules.</summary>

{% code title="Prompt" %}

```
Perform retrosynthesis on the previously generated molecules.
```

{% endcode %}

{% code title="Response (GPT-4.1)" overflow="wrap" %}

```
Retrosynthesis jobs have been submitted for the 3 generated molecules:

CC(O)C(C)Nc1nc2ncnc(SCc3ccccc3F)c2s1 — Job ID: 691e6e6f53b31257cbcbd91c
CCOC(=O)CN1C(=O)C(=Cc2ccc(N(CC)CC)cc2)C=C(CC)C1=O — Job ID: 691e6e7044369a3ca4510ae4
CC1CCCC(Nc2cc(C(F)(F)F)nc(CC3CC3)n2)CC1 — Job ID: 691e6e70f7acb63a247fa8f8
Each job is currently in "submitted" status. Let me know if you want to poll for results or retrieve the completed routes when ready.
```

{% endcode %}

</details>

<details>

<summary><i class="fa-messages-question">:messages-question:</i> Poll the retrosynthesis jobs and find the one with the longest route. </summary>

{% code title="Prompt" overflow="wrap" %}

```
Poll the retrosynthesis jobs and find the one with the longest route. 
```

{% endcode %}

{% code title="Response (Sonnet 4.5)" overflow="wrap" %}

```
Summary
After polling all 27 retrosynthesis jobs, I found the longest synthetic route:

🏆 Winner: 6-Step Synthesis
Target Molecule: CSCCCCCSc1nc2c(c(=O)[nH]1)C(N)CC2
Job ID: 691fed6eaaa8ae1c9767f0dd
Amine Type: Primary amine

The 6-Step Route:
1. Core oxidation - Oxidize tetrahydropyrimidine scaffold
2. Chlorination - Install leaving group at reactive position
3. Reductive amination - Introduce primary amine
4. Bromination - Prepare alkyl bromide linker
5. Thiol formation - Convert bromide to thiol
6. Thioether coupling - Final SNAr to connect linker to core

Key Statistics:
- Total molecules analyzed: 27
- Completed routes: 23
- Route lengths found:
  - 6 steps: 1 molecule (longest)
  - 5 steps: 1 molecule
  - 4 steps: 1 molecule
  - 3 steps: 2 molecules
  - 2 steps: 5 molecules
  - 1 step: 3 molecules

Files Created:
- View longest route analysis
- View detailed 6-step synthesis

This complex heterocyclic molecule with a bis-thiol linker represents the upper end of synthetic accessibility among the randomly generated structures, requiring sophisticated multi-step synthesis with careful functional group manipulation.
```

{% endcode %}

</details>

As Pending AI continues to deliver new possibilities, when in doubt you can always ask "What am I able to do using Pending AI?" for more information.

### Supported Tools

The Pending AI MCP server currently supports the following tools in Early Access:

| Tool                                     | Description                                                                                                                                                                                                                                                                                                                  |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`list_retrosynthesis_engines`**        | List retrosynthesis engines. Use this tool to show available machine learning architectures and search strategies that can be used when submitting retrosynthesis jobs. Engine choice can impact the quality and diversity of retrosynthetic routes found.                                                                   |
| **`list_retrosynthesis_libraries`**      | List retrosynthesis libraries. Use this tool to show available building block libraries that can be used when submitting retrosynthesis jobs. Libraries specify collections of molecules that are available starting materials for a retrosynthetic search.                                                                  |
| **`list_retrosynthesis_jobs`**           | List retrosynthesis jobs. Use this tool to get short summaries of existing jobs, or to find a `job_id` based on SMILES and creation timestamps. Pagination is supported via offset-based `page` and `limit` parameters.                                                                                                      |
| **`create_retrosynthesis_job`**          | Create a retrosynthesis job. Use this tool to submit a molecule for retrosynthesis screening and provide optional parameters to customise the search behaviour. The molecule should be provided in SMILES format. A `job_id` is returned that can be used to poll the job status and retrieve results once it has completed. |
| **`retrieve_retrosynthesis_job`**        | Retrieve a retrosynthesis job. Use this tool to fetch the details of a previously created retrosynthesis job by its id. Each job contains the molecule SMILES, status, and added timestamps for simple summary information.                                                                                                  |
| **`retrieve_retrosynthesis_job_status`** | Retrieve the status of a retrosynthesis job. Expect a value that changes over time from `submitted` (waiting to be processed) to `processing` (actively being processed) to `completed` or `failed` (finished processing). Use this tool for polling the status of a job before before results become available.             |
| **`retrieve_retrosynthesis_job_result`** | Retrieve the results of a previously submitted retrosynthesis job by its id. The list of retrosynthetic routes that were computed contain the synthetic steps to make the molecule with relevant building blocks. See the documentation for details about how retrosynthetic routes are represented.                         |
| **`delete_retrosynthesis_job`**          | Delete a retrosynthesis job and generated results. The job will no longer be accessible. The operation is irreversible and should be used with caution. You cannot delete a job that is still processing.                                                                                                                    |
| **`list_molecule_generator_models`**     | List generative models for sampling molecules. Use this tool to retrieve models and their metadata that can be used to see if a model is online and ready for sampling.                                                                                                                                                      |
| **`create_molecule_generator_sample`**   | Sample molecules from a generative model. Molecules are represented in SMILES format and contain drug-like properties unique to the model used. Use this tool to generate novel structures that can be further filtered and evaluated. Conditional filtering should be applied after sampling to select relevant molecules.  |

### Authentication

The MCP server aligns with current OAuth2.0 authentication flows allows for Dynamic Client Registration. Upon connecting to the server from the integrated tool connectors such as Claude or VSCode, you will be prompted to log in with your Pending AI account without any further steps.

{% hint style="warning" %}
If you are connecting from a service that is not one of the supported connectors, contact our team so that we can help provide any required callback URLs for your particular use case. For ease of testing, the MCP server already supports a callback on `http://localhost:8000/auth/callback` as used by most frameworks.
{% endhint %}

[^1]: Leverage our Generative AI capabilities

[^2]: Leverage our [Retrosynthesis](/capabilities/retrosynthesis) capabilities


# Connectors

Setup your favourite Agentic AI tool with the Pending AI MCP server

## Supported Connectors

For easier access, setup guides below describe how to access the MCP Server via a variety of common AI agent providers:

* [Claude](/integrations/agentic-ai/mcp-server/connectors/claude)

## Building MCP Clients

For cases where you are building your own MCP Client connector, access the MCP Server via the HTTPS transport scheme at `https://mcp.pending.ai/mcp`. Authentication is required for tool access and listing. It is recommended to use a framework that supports the OAuth2.0 authentication flow. Below shows a minimal example for using the Python [FastMCP](https://github.com/jlowin/fastmcp) package.

{% code title="FastMCP Example" %}

```python
from fastmcp import Client

async with Client("https://mcp.pending.ai/mcp", auth="oauth") as client:
    result = await client.list_tools()
```

{% endcode %}


# Claude

## Prerequisites

* A Claude.ai Pro Plan account (register at <https://claude.ai/>)
* A Pending AI account (contact us at `support@pending.ai`)

## Setup Guide

{% stepper %}
{% step %}

### Navigate to your [**Connectors**](https://claude.ai/settings/connectors)

Once you are logged in with your Claude Pro account, navigate to your account's custom connectors via the bottom left menu <mark style="color:$primary;">**Settings > Connectors**</mark>.

<figure><img src="/files/bfTBKUCdEfk70PjfaYjI" alt="claudeai-connectors-page" width="563"><figcaption><p>Claude.ai account connectors settings</p></figcaption></figure>
{% endstep %}

{% step %}

### Add the Pending AI custom connector

Press <mark style="color:$primary;">**Add Custom Connector**</mark> and provide a name (such as "Pending AI") and set the Remote MCP server URL as `https://mcp.pending.ai/mcp` as shown in the image. Press <mark style="color:$primary;">**Add**</mark>.

<figure><img src="/files/pAsMLh9Y7jMZsCioORCM" alt="claudeai-add-custom-connector" width="563"><figcaption><p>Add the custom connector details</p></figcaption></figure>
{% endstep %}

{% step %}

### Authenticate with the Pending AI connector

Press <mark style="color:$primary;">**Connect**</mark> <i class="fa-up-right-from-square">:up-right-from-square:</i> to authenticate with the connector, you will be redirected to give consent for registering with the server, press <mark style="color:$primary;">**Allow Access**</mark> and login with your Pending AI account.

<figure><img src="/files/9dZ1avYLceGIfPVIpjhX" alt="server-consent-form" width="563"><figcaption><p>Allow access for the server to register your connector</p></figcaption></figure>
{% endstep %}
{% endstepper %}


# ChatGPT

## Prerequisites

* A ChatGPT account (register at <https://chatgpt.com/>)
* A Pending AI account (contact us at `support@pending.ai`)

## Setup Guide

{% stepper %}
{% step %}

### Navigate to your <mark style="color:$primary;">Settings ></mark> [<mark style="color:$primary;">Apps and</mark> <mark style="color:$primary;"></mark><mark style="color:$primary;">**Connectors**</mark>](#user-content-fn-1)[^1]

Once you are logged in with your ChatGPT Plus account, navigate to your account's settings tab, then click on Apps & Connectors via the bottom left menu <mark style="color:$primary;">**Settings > Apps & Connectors**</mark>.

<div><figure><img src="/files/FdICKoDYgoB62bIJGmUL" alt="" width="278"><figcaption></figcaption></figure> <figure><img src="/files/QBEHrbSrJ8phZGk7Gtdp" alt="" width="563"><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

### Enable Developer Mode

Scroll to the bottom of the panel to where it says Advanced Settings:

<div><figure><img src="/files/IcOkchZAK7KoCDOoDqmS" alt="" width="563"><figcaption></figcaption></figure> <figure><img src="/files/FKMItNzu6u7afdU6Ou6q" alt="" width="552"><figcaption></figcaption></figure></div>

Then toggle the developer mode to be enabled.&#x20;

<div><figure><img src="/files/dQqsbmA3gj7Ltp9ANtr4" alt="" width="545"><figcaption></figcaption></figure> <figure><img src="/files/x0DuQVAUBu9Oa3mvpAqd" alt="" width="549"><figcaption></figcaption></figure></div>

### 3. Create the Pending AI custom connector

Press <mark style="color:$primary;">**Create**</mark>.

<figure><img src="/files/MlkDYW8tQPFW47JqSc1L" alt="" width="563"><figcaption></figcaption></figure>
{% endstep %}

{% step %}
Provide a name (such as "Pending AI MCP") and set the Remote MCP server URL as `https://mcp.pending.ai/mcp` as shown in the image. Check the box to accept that MCP servers introduce risk, and press <mark style="color:$primary;">**Create**</mark>.

<figure><img src="/files/1hdOIWslJwzyOiak7KIk" alt="" width="495"><figcaption></figcaption></figure>

### Authenticate with the Pending AI connector

Press <mark style="color:$primary;">**Connect**</mark> <i class="fa-up-right-from-square">:up-right-from-square:</i> to authenticate with the connector, you will be redirected to give consent for registering with the server, press <mark style="color:$primary;">**Allow Access**</mark> and login with your Pending AI account.

<figure><img src="/files/reZlHSKoxBZ9gilCjkAQ" alt="" width="563"><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

The MCP server is now connected and you can now use it within ChatGPT.

<figure><img src="/files/EzcrHbcApQsgIKosJt5T" alt="" width="563"><figcaption></figcaption></figure>

[^1]:


# VS Code Github Copilot

## Prerequisites

* A prepared VSCode workplace with the file `.vscode/mcp.json` in the project directory.
* A Pending AI account (contact us at support`@pending.ai`)

## Setup Guide

{% stepper %}
{% step %}

### Navigate to your [**Connectors**](https://claude.ai/settings/connectors)

Once you are logged in with your Claude Pro account, navigate to your account's custom connectors via the bottom left menu <mark style="color:$primary;">**Settings > Connectors**</mark>.

<figure><img src="/files/bfTBKUCdEfk70PjfaYjI" alt="claudeai-connectors-page" width="563"><figcaption><p>Claude.ai account connectors settings</p></figcaption></figure>
{% endstep %}

{% step %}

### Add the Pending AI custom connector

Press <mark style="color:$primary;">**Add Custom Connector**</mark> and provide a name (such as "Pending AI") and set the Remote MCP server URL as `https://mcp.pending.ai/mcp` as shown in the image. Press <mark style="color:$primary;">**Add**</mark>.

<figure><img src="/files/pAsMLh9Y7jMZsCioORCM" alt="claudeai-add-custom-connector" width="563"><figcaption><p>Add the custom connector details</p></figcaption></figure>
{% endstep %}

{% step %}

### Authenticate with the Pending AI connector

Press <mark style="color:$primary;">**Connect**</mark> <i class="fa-up-right-from-square">:up-right-from-square:</i> to authenticate with the connector, you will be redirected to give consent for registering with the server, press <mark style="color:$primary;">**Allow Access**</mark> and login with your Pending AI account.

<figure><img src="/files/9dZ1avYLceGIfPVIpjhX" alt="server-consent-form" width="563"><figcaption><p>Allow access for the server to register your connector</p></figcaption></figure>
{% endstep %}
{% endstepper %}


# Troubleshooting

Detailed overview of MCP-related errors

When interfacing with the Pending AI MCP server, tool calls that contain invalid data or encounter an error related to the Pending AI platform will return an appropriate error message with additional context and directions to help guide a reasoning agent to find a solution.

Input and output schemas with constraints and descriptions are provided to also give context and suggestions to the interfacing agent to better traverse and use the offered tools.

For improved transparency and to help with addressing any client errors, a detailed overview is provided for the possible errors that may be encountered.

## Tool Errors

Tool-specific errors that can cause a tool to "fail", although the error message returned to the agent contains the needed information to resolve it or to provide the needed feedback to a user.

<table data-full-width="false"><thead><tr><th width="325.87109375" valign="middle">Tool</th><th>Details</th><th>Suggestion</th></tr></thead><tbody><tr><td valign="middle"><code>create_molecule_generator_sample</code></td><td>Argument <code>model</code> has a value that matches a model that does not exist.</td><td>Try again using the default model or check the status of the remaining available models.</td></tr><tr><td valign="middle"> </td><td>Argument <code>model</code> has a value that matches a model that is unavailable.</td><td>Try again using the default model or check the status of the remaining available models.</td></tr><tr><td valign="middle"><code>create_retrosynthesis_job</code></td><td>Argument <code>retrosynthesis_engine</code> matches a retrosynthesis engine that does not exist.</td><td>Try again by excluding the field for the next request or list the available engines.</td></tr><tr><td valign="middle"><code>retrieve_retrosynthesis_job</code></td><td>Argument <code>building_block_libraries</code> matches a building block library that does not exist.</td><td>Try again by excluding the field for the next request or list the available libraries.</td></tr><tr><td valign="middle"><code>retrieve_retrosynthesis_job_status</code></td><td>Argument <code>job_id</code> matches a retrosynthesis job that does not exist.</td><td>Try listing retrosynthesis jobs to find job ids that exist and are available.</td></tr><tr><td valign="middle"><code>retrieve_retrosynthesis_job_result</code></td><td>Argument <code>job_id</code> matches a retrosynthesis job that does not exist.</td><td>Try listing retrosynthesis jobs to find job ids that exist and are available.</td></tr><tr><td valign="middle"></td><td>Argument <code>job_id</code> matches a retrosynthesis job that is still being processed.</td><td>Please try again once the job has completed. Poll the job status to see if the job is no longer processing.</td></tr><tr><td valign="middle"><code>delete_retrosynthesis_job</code></td><td>Argument <code>job_id</code> matches a retrosynthesis job that does not exist.</td><td>Try listing retrosynthesis jobs to find job ids that exist and are available.</td></tr><tr><td valign="middle"></td><td>Argument <code>job_id</code> matches a retrosynthesis job that is still being processed.</td><td>Please try again once the job has completed. Poll the job status to see if the job is no longer processing.</td></tr></tbody></table>

{% hint style="info" %}
Tools also have constraints placed on the input arguments that an agent receives, it can be common for an agent to mistake or misname different fields which will return a generic error message. These messages are meant for the agent to be able to fix the issue on its next request or within the same chat.
{% endhint %}

## Service Errors

The Pending AI platform that is interfaced by the MCP server may also encounter errors due to maintenance or high usage traffic. As the platform is made available via a public API[^1], errors are addressed specifically in the previous section, but can also yield a generic error for unhandled issues with the platform.

| HTTP Status                | Details                                                                                                      | Suggestion                                                                                                  |
| -------------------------- | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`          | Bad request made to the Pending AI server. The request contained invalid content and could not be processed. | Refer to the agent to outline the invalid data provided.                                                    |
| `401 Unauthorized`         | Invalid or expired access token used for authentication.                                                     | Restart your MCP server connection, remove cached access credentials, and reauthenticate.                   |
| `402 Payment Required`     | An error occurred due to payment issues with your Pending AI account.                                        | Contact Pending AI support.                                                                                 |
| `403 Forbidden`            | You do not have permission to access this MCP tool.                                                          | Check your access permissions with the requested service, contact support if you believe there is an error. |
| `422 Unprocessable Entity` | Tool request made to the Pending AI server contained invalid or malformed data.                              | Refer to the agent to outline the invalid data provided.                                                    |
| `429 Too Many Requests`    | Unable to process the request due to rate limiting from too many requests.                                   | Please wait before retrying and employ rate limiting strategies to avoid this issue.                        |
| `502 Bad Gateway`          | The tool is currently unavailable due to server issues that rely on a third-party service.                   | Try again later or contact Pending AI support.                                                              |
| `503 Service Unavailable`  | The tool is currently unavailable due to maintenance or other reasons.                                       | Try again later or contact Pending AI support                                                               |
| `504 Gateway Timeout`      | The tool is currently unavailable due to server issues that rely on a third-party service.                   | Try again later or contact Pending AI support.                                                              |

[^1]: See the [PAI Retro](/api-reference/pai-retro) or [PAI Generator](/api-reference/pai-generator) APIs for more information.


# CLI

Documentation for the Pending AI platform CLI

## Overview

Our platform CLI tool allows integrating the different Pending AI services directly from your terminal. The documentation for different commands are described below and interface with the offered APIs with the convenience of wrapper logic provided for authentication and other access requirements:

* [PAI Retro](/pai-retro/cli-reference)
* [PAI Generator](/pai-generator/cli-reference)

### Authentication

Access to the Pending AI platform requires privileged access for the listed services. Creating cached sessions via the CLI is made possible via the [`pendingai auth`](#pendingai-auth) commands.

```bash
pendingai auth login      # Create a new session
pendingai auth refresh    # Refresh session access
```

***

## <mark style="color:$primary;">`pendingai`</mark>

The main entry point for the Pending AI platform CLI. Leverage the different capabilities offered via an authenticated session using `pendingai auth --help` for more information (or [see above](#authentication)). Ensure you have an active subscription with the different services.

***

#### **Synopsis**

```bash
pendingai [OPTIONS] COMMAND [ARGS] ...
```

**Commands**:

* `docs`: Open the Pending AI documentation in your web browser.
* `auth`: Authenticate with the Pending AI platform.
* `retro`: Interface with the [PAI Retro](/pai-retro/cli-reference) service.
* `generator`: Interface with the [PAI Generator](/pai-generator/cli-reference) service.

***

#### **Options**

| Option (Short) | Option (Long) | Description                            | Default |
| -------------- | ------------- | -------------------------------------- | ------- |
|                | `--version`   | Show the application version and exit. | `n/a`   |
|                | `--help`      | Show this message and exit.            | `n/a`   |

### <mark style="color:$primary;">`pendingai docs`</mark>

Open the Pending AI documentation in your default web browser. You will be redirected shortly from your terminal to the web page.

***

#### **Synopsis**

```bash
pendingai docs
```

### <mark style="color:$primary;">`pendingai auth`</mark>

Manage your authenticated session with the Pending AI platform. Access to certain products is restricted by account permissions. The session created will require you to login and routinely refresh the session access.

{% hint style="warning" %}
For changes to your account such as starting a new subscription, ensure you re-login to a new session. Permissions will be refreshed from the cached access information which may cause issues.
{% endhint %}

***

#### **Synopsis**

```bash
pendingai auth [OPTIONS] COMMAND [ARGS] ...
```

***

**Commands**:

* `login`: Login to your Pending AI account.
* `logout`: Logout of your Pending AI account.
* `refresh`: Refresh an authenticated session.
* `status`: Show active session information.
* `token`: Get the access token of the current session.

***

#### **Options**

| Option (Short) | Option (Long) | Description                 | Default |
| -------------- | ------------- | --------------------------- | ------- |
|                | `--help`      | Show this message and exit. | `n/a`   |

#### <mark style="color:$primary;">`pendingai auth login`</mark>

Login to your Pending AI account. You will be prompted with a login 6-digit code to enter when redirected to your web browser. From there you can login or **create a new account**. Once logged in, return to your terminal with a newly authenticated session - information will cached on your device to allow for repeated CLI commands.

***

#### **Synopsis**

```bash
pendingai auth login
```

#### <mark style="color:$primary;">`pendingai auth logout`</mark>

Logout of your Pending AI account. The cached session information will be deleted. Any future use of the CLI will require you to call `pendingai login` to continue.

***

#### **Synopsis**

```bash
pendingai auth logout
```

#### <mark style="color:$primary;">`pendingai auth refresh`</mark>

Refresh an authenticated session. Cached session information expires after **24 hours** in which you must refresh access for the session. If the session can no longer be refreshed, you will need to call `pendingai login` to create a new session.

***

#### **Synopsis**

```bash
pendingai auth refresh
```

#### <mark style="color:$primary;">`pendingai auth status`</mark>

Show active session information. If you have multiple accounts, you will be able to see which account you are currently using for the session and the remaining time before your session expires.

***

#### **Synopsis**

```bash
pendingai auth status 
```

#### <mark style="color:$primary;">`pendingai auth token`</mark>

Get the access token of the current session. The access token is used when interfacing with the Pending AI platform API containing your user information.

{% hint style="info" %}
Our API documentation allows you to test the different requests from your browser. This command allows you to easily copy the session token for testing authenticated API requests from the documentation.
{% endhint %}

***

#### **Synopsis**

```bash
pendingai auth token
```

### <mark style="color:$primary;">`pendingai retro`</mark>

Interface with the [PAI Retro](/pai-retro/cli-reference) service. Build high-throughput screening pipelines to perform low and high-throughput Retrosynthesis to find new and diverse reaction pathways and assess the synthetic accessibility of structures.

***

#### **Synopsis**

```bash
pendingai retro [OPTIONS] COMMAND [ARGS] ...
```

***

**Commands**:

* `engines`: List available retrosynthesis engines.
* `libraries`: List available building block libraries.
* `job`: A set of commands supporting submitting and exploring individual Retrosynthesis jobs.
* `batch`: A set of commands supporting large molecule library screening Retrosynthesis jobs.

***

#### **Options**

| Option (Short) | Option (Long) | Description                 | Default |
| -------------- | ------------- | --------------------------- | ------- |
|                | `--help`      | Show this message and exit. | `n/a`   |

#### <mark style="color:$primary;">`pendingai retro engines`</mark>

List available retrosynthesis engines. An engine provides the underlying architecture and functional procedure used for building complex multi-step synthetic routes. It is required when submitting molecules for retrosynthesis to specific an engine `id` parameter.

***

#### **Synopsis**

```bash
pendingai retro engines [OPTIONS]
```

***

#### **Options**

| Option (Short) | Option (Long) | Description                 | Default |
| -------------- | ------------- | --------------------------- | ------- |
|                | `--json`      | Render output as JSON.      | `false` |
|                | `--help`      | Show this message and exit. | `n/a`   |

#### <mark style="color:$primary;">`pendingai retro libraries`</mark>

List available building block libraries. Building block libraries are collections of structures used to facilitate terminating different reaction trees with purchasable information. It is required when submitting molecules for retrosynthesis to specific a list of library `id` parameters.

***

#### **Synopsis**

```bash
pendingai retro libraries [OPTIONS]
```

***

#### **Options**

| Option (Short) | Option (Long) | Description                 | Default |
| -------------- | ------------- | --------------------------- | ------- |
|                | `--json`      | Render output as JSON.      | `false` |
|                | `--help`      | Show this message and exit. | `n/a`   |

#### <mark style="color:$primary;">`pendingai retro job`</mark>

A set of commands supporting submitting and exploring individual Retrosynthesis jobs.

***

#### **Synopsis**

```bash
pendingai retro job [OPTIONS] COMMAND [ARGS]...
```

***

**Commands**:

* `submit`: Submit a job to a retrosynthesis engine.
* `status`: Get the status of a retrosynthesis job.
* `result`: Retrieve results for one or more jobs.
* `list`: Retrieve a list of retrosynthesis jobs.
* `delete`: Delete a retrosynthesis job.
* `routes`: Visualise generated routes from the Pending AI UI.
* `depict`: Visualise generated route from local HTML pages.

***

#### **Options**

| Option (Short) | Option (Long) | Description                 | Default |
| -------------- | ------------- | --------------------------- | ------- |
|                | `--help`      | Show this message and exit. | `n/a`   |

#### <mark style="color:$primary;">`pendingai retro job submit`</mark>

Submit a single query molecule `SMILES` retrosynthesis job. Provide additional optional parameters to control the synthesis process. More information about these parameters is available in the [PAI Retro](/api-reference/pai-retro/synthesis-jobs#post-jobs) documentation.

{% hint style="info" %}
To provide multiple values for a `<LIST>` option, it should be provide in the following format `--option [VALUE] --option [VALUE]`.
{% endhint %}

***

#### **Synopsis**

```bash
pendingai retro job submit [OPTIONS] SMILES
```

***

#### **Arguments**

* `<SMILES>`: A single query molecule in SMILES format to be submitted for retrosynthesis.

***

#### **Options**

| Option (Short) | Option (Long)                | Description                                                                               | Default                                 |
| -------------- | ---------------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------- |
|                | `--engine <TEXT>`            | The engine `id` to perform retrosynthesis on.                                             | Most recently active available engine.  |
|                | `--library <LIST>`           | All library `id`'s to be used for retrosynthesis.                                         | All available building block libraries. |
|                | `--num-routes <INTEGER>`     | Maximum number of routes to generate \[1-50].                                             | `20`                                    |
|                | `--time-limit <INTEGER>`     | Maximum processing time in seconds \[60-600].                                             | `300`                                   |
|                | `--reaction-limit <INTEGER>` | Maximum number of times a reaction can appear in generated routes \[1-20].                | `3`                                     |
|                | `--block-limit <INTEGER>`    | Maximum number of times a building block molecule can appear in generated routes \[1-20]. | `3`                                     |
|                | `--json`                     | Render output as JSON.                                                                    | `false`                                 |
|                | `--help`                     | Show this message and exit.                                                               | `n/a`                                   |

#### <mark style="color:$primary;">`pendingai retro job status`</mark>

Get the status of a retrosynthesis job.

***

#### **Synopsis**

```bash
pendingai retro job status [OPTIONS] [JOB_ID]
```

***

#### **Arguments**

* `<JOB_ID>`: An `id` for a retrosynthesis job.

***

#### **Options**

| Option (Short) | Option (Long) | Description                 | Default |
| -------------- | ------------- | --------------------------- | ------- |
|                | `--json`      | Render output as JSON.      | `false` |
|                | `--help`      | Show this message and exit. | `n/a`   |

#### <mark style="color:$primary;">`pendingai retro job result`</mark>

Retrieve results for one or more retrosynthesis jobs by a single `id` or line-delimited file of multiple job `id` values. Results return back a collection of JSON routes per query molecule. More information about the response model is available [here](/api-reference/pai-retro/synthesis-jobs#get-jobs-job_id).

{% hint style="info" %}
This command is slower than batch-based screening as it retrieves results individually. For simple molecule screening of synthetic accessibility, it is recommended to use batched Retrosynthesis.
{% endhint %}

***

#### **Synopsis**

```bash
pendingai retro job result [OPTIONS] [JOB_ID]
```

***

#### **Arguments**

* `<JOB_ID>`: An `id` for a retrosynthesis job.

***

#### **Options**

| Option (Short) | Option (Long)          | Description                                                | Default                                      |
| -------------- | ---------------------- | ---------------------------------------------------------- | -------------------------------------------- |
| `-o`           | `--output-file <FILE>` | Output filepath for writing results.                       | Auto-generated file in your local directory. |
| `-i`           | `--input-file <FILE>`  | Optional input filepath of line-delimited job `id` values. | `n/a`                                        |
|                | `--help`               | Show this message and exit.                                | `n/a`                                        |

#### <mark style="color:$primary;">`pendingai retro job list`</mark>

Retrieve a list of retrosynthesis jobs. A paged view is made available to retrieve jobs across individual result pages. Filtering results is made available with `--status`.

***

#### **Synopsis**

```bash
pendingai retro job list [OPTIONS]
```

***

#### **Options**

| Option (Short) | Option (Long)           | Description                                                                   | Default |
| -------------- | ----------------------- | ----------------------------------------------------------------------------- | ------- |
|                | `--page <INTEGER>`      | Page number being fetched.                                                    | `1`     |
|                | `--page-size <INTEGER>` | Number of results per page \[1-25].                                           | `25`    |
|                | `--status <TEXT>`       | Optional filter for status: `completed`, `failed`, `submitted`, `processing`. | `n/a`   |
|                | `--json`                | Render output as JSON.                                                        | `false` |
|                | `--help`                | Show this message and exit.                                                   | `n/a`   |

#### <mark style="color:$primary;">`pendingai retro job delete`</mark>

Delete a retrosynthesis job. The results will no longer be available and the action cannot be undone.

***

#### **Synopsis**

```bash
pendingai retro job delete [OPTIONS] [JOB_ID]
```

***

#### **Arguments**

* `<JOB_ID>`: An `id` for a retrosynthesis job.

***

#### **Options**

| Option (Short) | Option (Long) | Description                 | Default |
| -------------- | ------------- | --------------------------- | ------- |
|                | `--json`      | Render output as JSON.      | `false` |
|                | `--help`      | Show this message and exit. | `n/a`   |

#### <mark style="color:$primary;">`pendingai retro job routes`</mark>

Visualise generated routes in the Pending AI UI. You will be redirected to your web browser.

***

#### **Synopsis**

```bash
pendingai retro job routes [JOB_ID]
```

***

#### **Arguments**

* `<JOB_ID>`: An `id` for a retrosynthesis job.

#### <mark style="color:$primary;">`pendingai retro job depict`</mark>

Visualise generated routes in the locally generated HTML pages. Results will be retrieved and HTML pages will be generated containing visualisations for each route. Note that the depictions can take up significant storage space if retrieved in large batches.

***

#### **Synopsis**

```bash
pendingai retro job depict [OPTIONS] [JOB_ID]
```

***

#### **Arguments**

* `[JOB_ID]`: An `id` for a retrosynthesis job.

***

#### **Options**

| Option (Short) | Option (Long)              | Description                                                | Default                                           |
| -------------- | -------------------------- | ---------------------------------------------------------- | ------------------------------------------------- |
| `-o`           | `--output-dir <DIRECTORY>` | Directory to save generated HTML depiction files.          | Auto-generated directory in your local directory. |
| `-i`           | `--input-file <FILE>`      | Optional input filepath of line-delimited job `id` values. | `n/a`                                             |
|                | `--help`                   | Show this message and exit.                                | `n/a`                                             |

#### <mark style="color:$primary;">`pendingai retro batch`</mark>

A set of commands supporting large molecule library screening Retrosynthesis jobs.

***

#### **Synopsis**

```bash
pendingai retro batch [OPTIONS] COMMAND [ARGS]...
```

***

**Commands**:

* `submit`: Submit a batch of retrosynthesis jobs.
* `status`: Check the processing status of a batch.
* `result`: Retrieve results for all jobs in a batch.
* `list`: List all submitted retrosynthesis batches.
* `delete`: Delete a completed batch of jobs.

***

#### **Options**

| Option (Short) | Option (Long) | Description                 | Default |
| -------------- | ------------- | --------------------------- | ------- |
|                | `--help`      | Show this message and exit. | `n/a`   |

#### <mark style="color:$primary;">`pendingai retro batch submit`</mark>

Submit multiple retrosynthesis jobs as a single batch. Parameters that are provided will be shared across all retrosynthesis jobs in the batch. Any duplicate SMILES will also be removed to avoid running the same job multiple times.

{% hint style="info" %}
To provide multiple values for a `<LIST>` option, it should be provide in the following format `--option [VALUE] --option [VALUE]`.
{% endhint %}

***

#### **Synopsis**

```bash
pendingai retro batch submit [OPTIONS] SMILES_FILE
```

***

#### **Arguments**

* `<SMILES_FILE>`: An input filepath containing line-delimited molecules belonging to the batch.

***

#### **Options**

| Option (Short) | Option (Long)                | Description                                                                               | Default                                 |
| -------------- | ---------------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------- |
|                | `--engine <TEXT>`            | The engine `id` to perform retrosynthesis on.                                             | Most recently active available engine.  |
|                | `--library <LIST>`           | All library `id`'s to be used for retrosynthesis.                                         | All available building block libraries. |
|                | `--num-routes <INTEGER>`     | Maximum number of routes to generate \[1-50].                                             | `20`                                    |
|                | `--time-limit <INTEGER>`     | Maximum processing time in seconds \[60-600].                                             | `300`                                   |
|                | `--reaction-limit <INTEGER>` | Maximum number of times a reaction can appear in generated routes \[1-20].                | `3`                                     |
|                | `--block-limit <INTEGER>`    | Maximum number of times a building block molecule can appear in generated routes \[1-20]. | `3`                                     |
|                | `--help`                     | Show this message and exit.                                                               | `n/a`                                   |

#### <mark style="color:$primary;">`pendingai retro batch status`</mark>

Check the status of a retrosynthesis batch. The batch is considered complete once all of its jobs have finished processing.

***

#### **Synopsis**

```bash
pendingai retro batch status BATCH_ID
```

***

#### **Arguments**

* `<BATCH_ID>`: An `id` for a retrosynthesis batch.

#### <mark style="color:$primary;">`pendingai retro batch result`</mark>

Retrieve results for all retrosynthesis jobs in a batch. The batch returns a different result summary compared to `pendingai retro job result` containing a summary of the screening results for all targets in the batch. See the [documentation](/api-reference/pai-retro/batch-screening#get-batches-batch_id-result) for more information about the response data.

**Note**: Results can be retrieved while the batch is in progress with jobs yet to be processed with `completed=false`.&#x20;

***

#### **Synopsis**

```bash
pendingai retro batch result [OPTIONS] BATCH_ID
```

***

#### **Arguments**

* `<BATCH_ID>`: An `id` for a retrosynthesis batch.

***

#### **Options**

| Option (Short) | Option (Long)          | Description                                                           | Default                                      |
| -------------- | ---------------------- | --------------------------------------------------------------------- | -------------------------------------------- |
| `-o`           | `--output-file <FILE>` | Output filepath for writing results.                                  | Auto-generated file in your local directory. |
|                | `--summarise`          | Return a summary statistic to assess the overall result of the batch. | `false`                                      |
|                | `--help`               | Show this message and exit.                                           | `n/a`                                        |

#### <mark style="color:$primary;">`pendingai retro batch list`</mark>

List all submitted batches in a paginated format.

***

#### **Synopsis**

```bash
pendingai retro batch list [OPTIONS]
```

***

#### **Options**

| Option (Short) | Option (Long)      | Description                                                       | Default |
| -------------- | ------------------ | ----------------------------------------------------------------- | ------- |
|                | `--before <TEXT>`  | An optional batch `id` value to retrieve those created before it. | `n/a`   |
|                | `--after <TEXT>`   | An optional batch `id` value to retrieve those created after it.  | `n/a`   |
| `-s`           | `--size <INTEGER>` | Number of results returned by the list \[1-100].                  | `50`    |
|                | `--help`           | Show this message and exit.                                       | `n/a`   |

#### <mark style="color:$primary;">`pendingai retro batch delete`</mark>

Delete a batch and all of its attached retrosynthesis jobs.

***

#### **Synopsis**

```bash
pendingai retro batch delete BATCH_ID
```

***

#### **Arguments**

* `<BATCH_ID>`: An `id` for a retrosynthesis batch.

### <mark style="color:$primary;">`pendingai generator`</mark>

Interface with the [PAI Generator](/pai-generator/cli-reference) service. Use Generative AI models for sample novel and diverse drug-like molecules to explore new chemical spaces efficiently and quickly.

***

#### **Synopsis**

```bash
pendingai generator [OPTIONS] COMMAND [ARGS] ...
```

***

#### **Description**

**Commands**:

* `models`: List the available Generative AI models for sampling molecules.
* `sample`: Generate samples of molecules from a model.

***

#### **Options**

| Option (Short) | Option (Long) | Description                 | Default |
| -------------- | ------------- | --------------------------- | ------- |
|                | `--help`      | Show this message and exit. | `n/a`   |

#### <mark style="color:$primary;">`pendingai generator models`</mark>

List the available Generative AI models for sampling molecules. The model `id` must be specified when sampling from a particular model. The returned data from the service can be limited to the first `--limit` results of paged data to avoid waiting for the server to respond.

***

#### **Synopsis**

```bash
pendingai generator models [OPTIONS]
```

***

#### **Options**

| Option (Short) | Option (Long)       | Description                               | Default |
| -------------- | ------------------- | ----------------------------------------- | ------- |
| `-l`           | `--limit <INTEGER>` | Limit the number of returned models. $$$$ | `100`   |
|                | `--json`            | Render output as JSON.                    | `false` |
|                | `--help`            | Show this message and exit.               | `n/a`   |

#### <mark style="color:$primary;">`pendingai generator sample`</mark>

Generate samples of molecules from a model. Output from the CLI is directed to a file for convenience. You can specify an output file and append to an existing one. Specify the particular model for sampling if necessary.

**Note**: When the `--model` option is not provided, the first available model will be used.

***

#### **Synopsis**

```bash
pendingai generator sample [OPTIONS]
```

***

#### **Options**

| Option (Short) | Option (Long)             | Description                                  | Default            |
| -------------- | ------------------------- | -------------------------------------------- | ------------------ |
| `-o`           | `--output-file <FILE>`    | Output filepath to store sampled SMILES.     | `pendingai_...smi` |
| `-n`           | `--num-samples <INTEGER>` | Number of samples to generate \[1-1000000].  | `500`              |
| `-m`           | `--model <TEXT>`          | Model `id` to use for sampling.              | `n/a`              |
| `-a`           | `--append`                | Append to the output file without prompting. | `false`            |
|                | `--help`                  | Show this message and exit.                  | `n/a`              |


# SDKs


# Python


# Guides

A collection of guides and examples to help with complex use-cases


# Setting up a Authentication

This guide gives a short introduction to authentication for the different developer tools and how to keep good practice across the platform services.

{% hint style="info" %}
If there is a guide missing or tool information that is more relevant for your use-case, contact us at `support@pending.ai` and the information will be added promptly.
{% endhint %}

## Prerequisities&#x20;

1. Setting up an account
2. Having a valid installation of the Pending AI CLI and Python SDK


# Submitting a molecule for Retrosynthesis


# Submitting a screening campaign


# Building a synthetically accessible compound library


# Perform a similarity search on sampled molecules


# Assess molecular characteristics from sampled molecules


# CLI Manual

Command-line interface for accessing Pending AI's retrosynthesis service.

## Getting Started

Usage of the Pending AI CLI requires

* an account for the **Pending AI Platform** and
* a locally installed Python version `>=3.9`.

The Pending AI CLI is available from the [Python Package Index](https://pypi.org/), the official third-party software repository for Python and can thus be easily installed using the package management system [pip](https://pip.pypa.io/):

{% code fullWidth="false" %}

```sh
pip install pendingai
```

{% endcode %}

Successful installation can be verified with

```bash
pendingai --version
```

which is expected to output the name and version of the Pending AI CLI.

<figure><img src="/files/2Nk2S6N9oVpWU7598YgH" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
Jobs including their results will automatically be deleted **30 days** after completion. It is your responsibility to retrieve any results before this time.
{% endhint %}

## Authentication

Using the Pending AI services via the CLI requires an authenticated session. The `pendingai auth` command provides several subcommands to manage your authentication status.

### Logging In

To initiate the login process, use the `login` subcommand:

```bash
pendingai auth login
```

This command uses device authorization, which will automatically open a web browser window. Follow the prompts in your browser to enter your Pending AI Platform credentials and authorize the CLI session.

For any account problems, contact Pending AI via email at `support@pending.ai`.

### Checking Session Status

You can check the status of your current authenticated session, including details like the associated user and expiry time:

```bash
pendingai auth status
```

### Refreshing a Session

Authenticated sessions have a limited lifetime for security reasons. If your session is close to expiring or has already expired, you can attempt to refresh it without needing to fully log in again:

```bash
pendingai auth refresh
```

This will extend the lifetime of your current session if it's still valid for refreshing.

### Retrieving the Access Token

Successful authentication stores an access token locally on your machine. You can retrieve the current access token using:

```bash
pendingai auth token
```

{% hint style="info" %}
The access token retrieved via `pendingai auth token` can be used as a Bearer token for direct [API](broken://pages/79SanmFt6Ukc91gX4WUo) access by including it in the `Authorization` header of each API request (e.g., `Authorization: Bearer <your_token>`).
{% endhint %}

### Logging Out

To end your authenticated session and remove the locally cached authentication details, use the `logout` subcommand:

```bash
pendingai auth logout
```

This ensures that your credentials are no longer stored by the CLI on the current machine.

<figure><img src="/files/TwT8OJtK1JqNr0STOuLy" alt=""><figcaption></figcaption></figure>

## Explore Available Engines and Libraries

Before submitting compounds, you might want to know which retrosynthesis engines and building block libraries are available to your account. You can list them using these commands:

```bash
# Display available retrosynthesis engines
pendingai retro engines

# Display available building block libraries
pendingai retro libraries
```

{% hint style="info" %}
The specific engines and libraries available depend on your Pending AI Platform account configuration. Please contact support at `support@pending.ai` if you want discuss generally available and customized engines and building block libraries.
{% endhint %}

## Guide: Submitting Batch Retrosynthesis Jobs

The CLI supports submitting multiple retrosynthesis queries together as a single **batch**. This is ideal for running large-scale synthetic feasibility campaigns efficiently. Each query molecule within the batch is processed as an individual job, but all jobs within a batch share the same search parameters.

A synthetic accessibility summary can be obtained for all queries of a batch with a single command. The summary also contains Job IDs of individual queries of the batch. These Job IDs can then be used to retrieve detailed results including route information in JSON format and route depictions in PDF format for select queries of interest.

{% stepper %}
{% step %}
**1. Prepare Input File & Submit Batch**

Input files for batch jobs require line-delimited query molecules encoded as SMILES. Each line should contain a single valid SMILES string. Any repeated SMILES strings within the file will be automatically removed (deduplicated) before submission.

Here is an exemplary input file, `molecules_batch_1.smi` :

{% code title="molecules\_batch\_1.smi" %}

```
n1nc(n(c1)C)[C@@]1(C(=O)O)CC[C@@H]1CC
C1[C@@H](Br)CCCS([C@@H](C)C(=O)O)(=O)=O
C(C1CCN(CC1)c1ncc(Cl)cn1)N(C)C
[C@H]12C[C@@H](C[C@@H]2CCC1)C[C@@H](CC1(CCCCC1)OCC)N
[C@@H](NC[C@@H](c1occc1)C)(O)c1ccccc1OC(F)F
```

{% endcode %}

{% file src="/files/FvnuAnV9dCshCOUJJrLk" %}

To submit the batch, use the `pendingai retro batch submit` command, providing the path to your SMILES file as an argument:

```bash
pendingai retro batch submit molecules_batch_1.smi
```

Upon successful submission, the command will output a unique **Batch ID** (e.g., `bat_aa512a2`). You will need this ID to track the batch status and retrieve results.

You can customize the search parameters (like engine, libraries, time limits) for all jobs in the batch using options with the `submit` command. See the [Batch Submission Parameters](#batch-submission-parameters) section below for details. If no options are provided, sensible defaults will be used.

<figure><img src="/files/Zsrrr971GWFbdJWb0zWQ" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**2. Track Batch Status**

You can monitor the overall progress of the batch using the `pendingai retro batch status` command and the Batch ID obtained in the previous step:

```bash
# Check status using the actual Batch ID
pendingai retro batch status bat_aa512a2
```

This command reports the status of the batch as a whole (e.g., `PENDING`, `RUNNING`, `COMPLETED`, `FAILED`). The batch is considered completed only when all individual jobs within it have finished processing.
{% endstep %}

{% step %}
**3. Retrieve Batch Results**

Once the batch status is `COMPLETED`, you can retrieve the results for all jobs within that batch using the `pendingai retro batch result` command:

```bash
# Retrieve results using the actual Batch ID
pendingai retro batch result bat_aa512a2
```

Results are saved to a file in JSON format. If the `--output-file` option is not provided, a default filename is generated that starts with the Batch ID and includes a timestamp (e.g., `bat_aa512a2_results_2025-05-04T16-31-47.json`) in the current directory.

Use the `-o` or `--output-file` option to specify a filename:

```bash
# Retrieve results and save to a specific file
pendingai retro batch result bat_aa512a2 -o molecules_batch_1_results.json
```

The results include synthesizability assessments and individual job IDs which can be used with other CLI commands for more detailed route analysis.

<figure><img src="/files/jZGvtbIczsbZFCz8acKi" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**4. Retrieve Detailed Job Results**

Taking the Job IDs of compounds of interest from the batch detailed results for multiple jobs can be retrieved by providing a file containing one Job ID per line using the `-i` or `--input-file` option:

```bash
# Create a file with Job IDs (e.g., specific_jobs.ids)
# 6800a125c14660367f058a90
# 6800a125c14660367f058aa0

# Retrieve results for jobs listed in the file
pendingai retro job result -i specific_jobs.ids
```

Results are returned in JSON format and by default saved to an automatically generated timestamped filename in the current working directory. Use the `-o` or `--output-file` option to optionally specify a path and filename:

```bash
# Retrieve multiple job results from file and save to another file
pendingai retro job result -i specific_jobs.ids -o specific_jobs_results.json
```

{% endstep %}

{% step %}
**5. Depict Routes**

Routes can be depicted for multiple jobs listed in an input file:

```bash
# Generate depictions for jobs listed in specific_jobs.ids
pendingai retro job depict -i specific_jobs.ids
```

By default, PDF files named `job_<job_id>.pdf` are created in the current directory. You can optionally specify a different output directory using `-o` or `--output-dir`:

```bash
# Save depictions to a specific directory
pendingai retro job depict 6800a125c14660367f058a90 -o ./depictions/
```

Use `--force` to overwrite existing PDF files without prompting.

{% hint style="info" %}
Route depiction is an experimental feature. Feedback is welcome via `support@pending.ai`. This command can also be used effectively with Job IDs extracted from a `batch result` output to visualize routes for specific molecules of interest within a large campaign.
{% endhint %}
{% endstep %}

{% step %}
**6. List Submitted Batches**

To view a list of batches you have previously submitted, use the `pendingai retro batch list` command:

```bash
pendingai retro batch list
```

This provides a paginated overview including Batch IDs, creation times, and the number of jobs in each batch.

{% code title="Example Output" %}

```
┌─────────────┬───────────────────────────┬──────────────┬───────┐
│ Batch ID    │ Created                   │ Filename     │  Jobs │
├─────────────┼───────────────────────────┼──────────────┼───────┤
│ bat_aa512a2 │ 2025-04-30 16:59:52+10:00 │ targets_smi  │ 10000 │
│ bat_cd0db05 │ 2025-04-30 16:59:45+10:00 │ targets_smi  │ 10000 │
│ bat_41ddb92 │ 2025-04-30 16:59:39+10:00 │ targets_smi  │ 10000 │
└─────────────┴───────────────────────────┴──────────────┴───────┘
                          Page 1 of N
```

{% endcode %}

You can navigate through the list using the `--page` and `--page-size` options:

```bash
# Show page 2, with 10 batches per page
pendingai retro batch list --page 2 --page-size 10
```

{% endstep %}

{% step %}
**7. Delete a Batch**

If you no longer need a batch and its associated job data, you can delete it using the `pendingai retro batch delete` command, provided it has completed processing:

```bash
# Delete a completed batch using its actual Batch ID
pendingai retro batch delete bat_aa512a2
```

{% hint style="warning" %}
Batches that are still `PENDING` or `PROCESSING` cannot be deleted. Deleting a batch permanently removes all associated job results from the platform. This action cannot be undone.
{% endhint %}

<figure><img src="/files/flsElIHgBO6onIoJkG0z" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

## Batch Submission Parameters

The command `pendingai retro batch submit SMILES_FILE` is used to submit a batch of retrosynthesis jobs, where `SMILES_FILE` is the mandatory path to your input file.

If no other options are provided, **sensible default values** are used for the job parameters applied to all jobs within the batch.

{% hint style="success" %}
For most use cases, the **default parameter values** are expected to yield good results. We encourage users to start with these defaults.
{% endhint %}

Customizable parameters for the `submit` command are explained below. A concise description of all options can also be printed to the terminal with:

```bash
pendingai retro batch submit --help
```

### Input File (Positional Argument)

**Argument:** `SMILES_FILE`

This is a **mandatory** positional argument specifying the path to the input file. The file must contain one molecule SMILES per line. SMARTS features are not supported.

### Engine

**Option:** `--engine TEXT`

Specifies the identifier (`TEXT`) of the retrosynthesis engine to be used for executing all jobs in the batch.

You can list the names and identifiers of available retrosynthesis engines using:

```bash
pendingai retro engines
```

{% hint style="info" %}
If there is only one engine available for your Pending AI Platform account it will automatically be used if the `--engine` option is not specified during batch submission. If your account has access to more than one engine this option is mandatory.
{% endhint %}

### Building Block Library

**Option:** `--library TEXT`

Specifies the identifier (`TEXT`) of a building block library to be used for the jobs in this batch. This option can be repeated to include multiple specific libraries.

```bash
# Example using two specific libraries
pendingai retro batch submit mols.smi --library library_A --library library_B
```

{% hint style="info" %}
If no `--library` option is provided, **all building block libraries** available to the user will be used by default.
{% endhint %}

### Number of Routes

**Option:** `--num-routes INTEGER`

**Default:** 20

**Range:** \[1, 50]

Controls the maximum number of potential retrosynthetic routes the software will attempt to generate for each job in the batch. The actual number of returned routes for any given job might be lower due to factors like target molecule complexity, building block availability, processing time limits, etc.

### Processing Time Limit

**Option:** `--time-limit INTEGER`

**Default:** 300

**Range:** \[60, 600]

Specifies the maximum processing time in seconds that the retrosynthesis engine will spend on each individual job within the batch. The actual time spent might be lower, even if fewer routes than requested are found.

### Reaction Limit

**Option:** `--reaction-limit INTEGER`

**Default:** 3

**Range:** \[1, 20]

Specifies the maximum number of times a particular reaction template can appear across all generated retrosynthetic routes for a single job in the batch.

### Building Block Limit

**Option:** `--block-limit INTEGER`

**Default:** 3

**Range:** \[1, 20]

Specifies the maximum number of times a particular building block molecule can appear within a single generated retrosynthetic route for any job in the batch.

## Guide: Managing Individual Retrosynthesis Jobs

While batch submission (`pendingai retro batch`) is recommended for synthetic accessibility campaigns, the CLI also provides commands under `pendingai retro job` to operate on individual retrosynthesis jobs.

{% hint style="success" %}
These `job` commands are primarily intended for testing, demonstration purposes, or **retrieving detailed results** **for specific jobs identified from a batch analysis**. For processing multiple molecules, using the `batch` commands is strongly recommended.
{% endhint %}

{% stepper %}
{% step %}
**1. Submit a Single Job**

To submit a single molecule for retrosynthesis, use the `pendingai retro job submit` command, providing the molecule's SMILES string as a mandatory argument.

```bash
# Submit a job with default parameters
pendingai retro job submit "CN(C(=O)C(Cl)Cl)c1ccc(O)cc1"
```

Upon successful submission, the command will output a unique **Job ID** (e.g., `6800a125c14660367f058a90`). You need this ID for subsequent steps like checking status or retrieving results.

You can customize the search parameters (engine, libraries, limits, etc.) using options. See the [Single Job Submission Parameters](#single-job-submission-parameters) section below for details. If only the SMILES is provided, sensible defaults are used.

{% hint style="warning" %}
Remember that jobs and their results are automatically deleted **30 days** after completion.
{% endhint %}
{% endstep %}

{% step %}
**2. Check Job Status**

Use the `pendingai retro job status` command along with the Job ID to track the progress of an individual job:

```bash
# Check status using the actual Job ID
pendingai retro job status 6800a125c14660367f058a90
```

This will display the current status (e.g., `SUBMITTED`, `PROCESSING`, `COMPLETED`, `FAILED`). You can also request the output in JSON format using the `--json` flag.
{% endstep %}

{% step %}
**3. Retrieve Detailed Job Results**

Once a job's status is `COMPLETED`, you can retrieve its detailed results, including the generated retrosynthetic routes, using the `pendingai retro job result` command.

You can retrieve results for a single job by providing its ID:

```bash
# Retrieve results for a single job ID
pendingai retro job result 6800a125c14660367f058a90
```

Alternatively, you can retrieve results for multiple jobs by providing a file containing one Job ID per line using the `-i` or `--input-file` option:

```bash
# Create a file with Job IDs (e.g., specific_jobs.ids)
# 6800a125c14660367f058a90
# 6800a125c14660367f058aa5

# Retrieve results for jobs listed in the file
pendingai retro job result -i specific_jobs.ids
```

Results are returned in JSON format. Use the `-o` or `--output-file` option to save them directly to a file:

```bash
# Retrieve single job result and save to file
pendingai retro job result 6800a125c14660367f058a90 -o single_job_result.json

# Retrieve multiple job results from file and save to another file
pendingai retro job result -i specific_jobs.ids -o multiple_job_results.json
```

{% hint style="info" %}
The `pendingai retro job result` command is particularly useful for getting detailed route information for specific jobs identified from a batch result file by their Job ID.
{% endhint %}
{% endstep %}

{% step %}
**4. Depict Routes**

For completed jobs, you can generate visual depictions of the found retrosynthetic routes as PDF files using the `pendingai retro job depict` command.

Similar to retrieving detailed results, you can depict routes for a single Job ID:

```bash
# Generate route depiction for a single job
pendingai retro job depict 6800a125c14660367f058a90
```

Or for multiple jobs listed in an input file:

```bash
# Generate depictions for jobs listed in specific_jobs.ids
pendingai retro job depict -i specific_jobs.ids
```

By default, PDF files named `job_<job_id>.pdf` are created in the current directory. You can specify a different output directory using `-o` or `--output-dir`:

```bash
# Save depictions to a specific directory
pendingai retro job depict 6800a125c14660367f058a90 -o ./depictions/
```

Use `--force` to overwrite existing PDF files without prompting.

{% hint style="info" %}
Route depiction is an **experimental feature**. Feedback is welcome via `support@pending.ai`. This command can also be used effectively with Job IDs extracted from a `batch result` output to visualize routes for specific molecules of interest within a large campaign.
{% endhint %}
{% endstep %}

{% step %}
**5. List Submitted Jobs**

To view a paginated list of your individual job submissions, use `pendingai retro job list`:

```bash
pendingai retro job list
```

This command displays key information, including Job ID, status, and basic parameters. You can filter by status and control pagination:

```bash
# List only completed jobs, 10 per page
pendingai retro job list --status completed --page-size 10
```

Use `pendingai retro job result` to get the full route details for completed jobs.
{% endstep %}

{% step %}
**6. Delete a Job**

If you no longer need an individual job and its results, you can delete it using `pendingai retro job delete` and its Job ID:

```bash
# Delete a specific job
pendingai retro job delete 6800a125c14660367f058a90
```

{% hint style="warning" %}
Deleting a job permanently removes it and its results from the platform. This action cannot be undone.
{% endhint %}
{% endstep %}
{% endstepper %}

## Single Job Submission Parameters

The command `pendingai retro job submit SMILES` is used to submit a single retrosynthesis job, where `SMILES` is the mandatory SMILES string of the query molecule.

If no other options are provided, **sensible default values** are used for the job parameters.

{% hint style="success" %}
For most single job tests or demonstrations, the **default parameter values** are suitable.
{% endhint %}

Customizable parameters for the `submit` command are explained below. A concise description of all options can also be printed to the terminal with:

```bash
pendingai retro job submit --help
```

### Query Molecule (Positional Argument)

**Argument:** `SMILES`

This is a **mandatory** positional argument specifying the SMILES string of the single query molecule for the job. SMARTS features are not supported.

### Engine

**Option:** `--engine TEXT`

Specifies the identifier of the retrosynthesis engine to execute this job. If only one engine is available for your account, it will be used automatically, making this parameter optional. You can list available engine IDs using `pendingai retro engines`.

### Building Block Library

**Option:** `--library TEXT`

Specifies the identifier (`TEXT`) of a building block library to be used for this job. This option can be repeated to include multiple specific libraries. Defaults to using all available libraries if not specified. See `pendingai retro libraries` for available IDs.

```bash
# Example using two specific libraries for a single job
pendingai retro job submit "CCO" --library library_A --library library_B
```

### Number of Routes

**Option:** `--num-routes INTEGER`

**Default:** 20

**Range:** \[1, 50]

Controls the maximum number of potential retrosynthetic routes the software will attempt to generate for this job.

### Processing Time Limit

**Option:** `--time-limit INTEGER`

**Default:** 300

**Range:** \[60, 600]

Specifies the maximum processing time in seconds that the retrosynthesis engine will spend on this job.

### Reaction Limit

**Option:** `--reaction-limit INTEGER`

**Default:** 3

**Range:** \[1, 20]

Specifies the maximum number of times a particular reaction template can appear across all generated retrosynthetic routes for this job.

### Building Block Limit

**Option:** `--block-limit INTEGER`

**Default:** 3

**Range:** \[1, 20]

Specifies the maximum number of times a particular building block molecule can appear within a single generated retrosynthetic route for this job.

### JSON Output

**Option:** `--json`

When submitting a job, using this flag will render the confirmation output (including the Job ID) in JSON format instead of the default text format.

## FAQs

### I set `--num-routes 50` when submitting a job or batch, but get significantly fewer than 50 routes in my results. Why?

The `--num-routes` option sets the *maximum* number of retrosynthetic routes the engine will attempt to generate per job. It acts as an upper limit. The actual number of routes found can be lower due to several factors, including:

* The complexity of the target molecule (some molecules are inherently harder to find routes for).
* The contents of the selected building block library/libraries.
* The processing time limit (`--time-limit`) being reached before the maximum number of routes is found.
* Internal algorithm constraints or heuristics designed to prioritize diverse or high-quality routes.

### What's the difference between a Batch ID (`bat_...`) and a Job ID ?

* A **Batch ID** refers to the entire collection of jobs submitted together using `pendingai retro batch submit`. You use the Batch ID to check the overall status (`batch status`), retrieve summarized results for all jobs in the batch (`batch result`), list batches (`batch list`), or delete the entire batch (`batch delete`).
* A **Job ID** refers to a single retrosynthesis calculation for one specific molecule, whether submitted individually (`retro job submit`) or as part of a batch. You typically obtain Job IDs from the output of `pendingai retro batch result`. These Job IDs are then used to get detailed results including route information (`job result`) or route depictions (`job depict`) for that specific molecule.

### How do I get the detailed routes for specific molecules after running a batch?

1. Run `pendingai retro batch result <your_batch_id> -o batch_results.json` to get the results for the entire batch, saving them to a file.
2. Inspect the `batch_results.json` file. Each entry will contain information about a specific molecule from your input file, including its corresponding Job ID `<job_id>`.
3. Identify the Job IDs for the molecules you are interested in.
4. Use `pendingai retro job result <job_id>` (for one job) or `pendingai retro job result -i <file_with_job_ids>` (for multiple jobs) to retrieve the detailed results, including the routes, for those specific jobs.
5. Alternatively, use `pendingai retro job depict <job_id>` or `pendingai retro job depict -i <file_with_job_ids>` to generate PDF depictions of the routes.

### What happens if one job fails within a batch?

The batch processing system is designed to be robust. If an individual job within a batch fails (e.g., due to an invalid input SMILES or an unexpected engine error for that specific molecule), it typically does not stop the entire batch. Other jobs in the batch will continue to process.\
When you retrieve the batch results using `pendingai retro batch result`, the status or result entry for the failed job should indicate the failure. The overall batch status might still eventually become `COMPLETED` if all other jobs finish, but you should check the individual job statuses within the batch result file for any failures.

### My batch submission failed immediately. What should I check?

Common reasons for immediate batch submission failure include:

* **Authentication:** Ensure you are logged in (`pendingai auth status`). Try refreshing your session (`pendingai auth refresh`) or logging in again (`pendingai auth login`).
* **Input File:** Verify the path to your SMILES file is correct and that the file exists and is readable. Check that the file contains valid SMILES strings, one per line. Invalid characters or formatting can cause errors.
* **Invalid Parameters:** Double-check any options you provided (e.g., `--engine`, `--library`, numeric limits) to ensure the values are valid and available to your account. Use `pendingai retro engines` and `pendingai retro libraries` to confirm IDs.
* **Permissions:** Ensure your account has permission to use the selected engine and libraries. Contact support if you suspect a permissions issue.

### How many SMILES can my input file contain for a batch submission?

The number of SMILES per input file is limited to 100,000. Please reach out to our support at `support@pending.ai` to discuss options to increase this limit.


# CLI Manual

Command-line interface for accessing Pending AI's retrosynthesis service.

### Getting Started

Usage of the Pending AI CLI requires

* an account for the **Pending AI Platform** and
* a locally installed Python version `>=3.9`.

The Pending AI CLI is available from the [Python Package Index](https://pypi.org/), the official third-party software repository for Python and can thus be easily installed using the package management system [pip](https://pip.pypa.io/):

{% code fullWidth="false" %}

```sh
pip install pendingai
```

{% endcode %}

Successful installation can be verified with

```bash
pendingai --version
```

which is expected to output the name and version of the Pending AI CLI.

### Authentication

Using the Pending AI services via the CLI requires an authenticated session. The `pendingai auth` command provides several subcommands to manage your authentication status.

#### Logging In

To initiate the login process, use the `login` subcommand:

```bash
pendingai auth login
```

This command uses device authorization, which will automatically open a web browser window. Follow the prompts in your browser to enter your Pending AI Platform credentials and authorize the CLI session.

For any account problems, contact Pending AI via email at `support@pending.ai`.

#### Checking Session Status

You can check the status of your current authenticated session, including details like the associated user and expiry time:

```bash
pendingai auth status
```

#### Refreshing a Session

Authenticated sessions have a limited lifetime for security reasons. If your session is close to expiring or has already expired, you can attempt to refresh it without needing to fully log in again:

```bash
pendingai auth refresh
```

This will extend the lifetime of your current session if it's still valid for refreshing.

#### Retrieving the Access Token

Successful authentication stores an access token locally on your machine. You can retrieve the current access token using:

```bash
pendingai auth token
```

{% hint style="info" %}
The access token retrieved via `pendingai auth token` can be used as a Bearer token for direct API access by including it in the `Authorization` header of each API request (e.g., `Authorization: Bearer <your_token>`).
{% endhint %}

#### Logging Out

To end your authenticated session and remove the locally cached authentication details, use the `logout` subcommand:

```bash
pendingai auth logout
```

This ensures that your credentials are no longer stored by the CLI on the current machine.

### Exploring Available Generative Models

{% hint style="info" %}
An overview of Pending AI's generative models and their characteristics can be found [here](broken://pages/ziuETMbI2dhFCzSib1wh). Please note that your account might have access to select models only. Reach out to our support at `support@pending.ai` if you want discuss your generative model options.
{% endhint %}

Before generating molecules, you might want to know which generative models are available to your account. Each model has a unique ID that can be provided to the `generator sample` command to select a model.

To list all available models, use the `models` command:

```bash
pendingai generator models
```

The output will be a table listing the available models, their version, and their current status. Only models with an `Online` status can be used for sampling.

**Example Output:**

```
┌─────────────────────────────────┬────────────────────────────┬───────────────┬─────────┐
│ ID                              │ Name                       │ Version       │ Status  │
├─────────────────────────────────┼────────────────────────────┼───────────────┼─────────┤
│ mod_2XF0UlNC3yWGLVhklkoYAS3vky0 │ diverse small transformer  │ 0.0.0-alpha.0 │ Online  │
│ mod_2XF0Y4tJrHbHxpWwppyfJFAiHJM │ docking tiny transformer   │ 0.0.0-alpha.0 │ Online  │
│ mod_2XEGInBPVsqDsW25vSvaNRcIfxs │ docking small transformer  │ 0.0.0-alpha.0 │ Online  │
│ mod_2XEGInBPVsqDsW25vSvaNRcIfxc │ docking medium transformer │ 0.0.0-alpha.0 │ Offline │
└─────────────────────────────────┴────────────────────────────┴───────────────┴─────────┘
```

You can also get this list in a machine-readable format using the `--json` flag.

### Guide: Sampling Molecules

To sample molecules from a generative model, use the `sample` command. You can specify the number of molecules to generate and the model to use.

**1. Basic Sampling**

To generate 1,000 molecules using any available online model and save them to a file named `samples.smi`:

```bash
pendingai generator sample --num-samples 1000 --output-file "samples.smi"
```

If an output file is not specified with `--output-file`, the results will be saved to a default file that follows the pattern `endingai_generator_sample_XXX.smi` with `XXX` starting at 001 and being incremented in steps of 1.

**2. Targeted Sampling with a Specific Model**

To generate 5,000 molecules specifically from the `diverse small transformer` model (using its ID from the `models` command), run:

```bash
pendingai generator sample --model "mod_2XF0UlNC3yWGLVhklkoYAS3vky0" --num-samples 5000 --output-file "samples.smi"
```

{% hint style="warning" %}
If you don't specify a model, the service will pick any model is available to your account and is online to generate the samples. It is **highly recommended** to always specify a model ID so that the generated molecules are suitable to the requirements of your specific task.
{% endhint %}

**3. Appending to an Existing File**

If you want to add more samples to an existing file without being prompted to overwrite it, use the `--append` flag:

```bash
pendingai generator sample --num-samples 2500 --output-file "samples.smi" --append
```

### Molecule Sampling Parameters

The following parameters can be used with the `pendingai generator sample` command:

* `-o, --output-file <FILE>`
  * Specifies the file path for storing the output SMILES molecules.
  * If not provided, it defaults to `pendingai_generator_sample_XXX.smi` in the current directory.
* `-n, --num-samples <INTEGER>`
  * The number of molecules you want to generate.
  * Must be an integer between 1 and 1,000,000.
  * Defaults to 500 if not specified.
* `-m, --model <TEXT>`
  * The unique ID of the model you want to use for sampling.
  * Use the `pendingai generator models` command to find available model IDs.
  * If not specified, the system will use any available online generator model.
* `-a, --append`
  * A flag to indicate that the generated molecules should be appended to the output file if it already exists.
  * This also suppresses the prompt that asks for confirmation before overwriting a file.