> For the complete documentation index, see [llms.txt](https://docs.pending.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pending.ai/api-reference/pai-synth.md).

# PAI Synth

Access Pending AI's fast retrosynthesis search, one molecule at a time or in batches of up to 100,000

Pending AI's fast retrosynthesis search finds synthetic routes from purchasable building blocks to a target molecule within a short time limit. Each result includes pricing and lead-time annotations for the building blocks used, so routes can be ranked by cost and sourcing feasibility as well as by length.

PAI Synth is served at `https://api.pending.ai/synth/v1` by the same backend as [PAI Retro](https://docs.pending.ai/api-reference/pai-retro.md), so jobs, batches and routes share one schema. See the **capability** page for more information:

{% content-ref url="/pages/1h5TxpTFc56h802JWFzt" %}
[Retrosynthesis](https://docs.pending.ai/capabilities/retrosynthesis.md)
{% endcontent-ref %}

{% hint style="warning" %}
The `synth-batches/v1` API and the `/treesearch` endpoint of `synth/v1` have been retired, with no alias. Use `POST /jobs` for a single search and `POST /batches` for many molecules, as described below.
{% endhint %}

***

## Workflow Summary

A synth **engine** must be provided, or the default synth engine is used, when submitting a query. Building block libraries are not needed: synth engines price their own building blocks, so leave out `building_block_libraries`. Passing a PAI Retro engine to `synth/v1` is refused with `422`.

On submission, a **job** `id` is provided. `POST /jobs` accepts `?wait=<seconds>` (0 to 25) to hold the response open until the job finishes, so a search that completes in time comes back with its routes in the same request. If it doesn't, poll `GET /jobs/{job_id}` (which also accepts `wait`) until its `status` is `completed` or `failed`, at which point the routes should be retrieved and saved per query. A similar workflow is made available through **batch-based** submission to provide a faster screening interface on larger collections of query molecules:

* `POST /batches` returns the batch at once. Its jobs are created in the background, and `jobs_created` turns `true` once they all exist.
* `GET /batches` and `GET /batches/{batch_id}` include each batch's `status` (`submitted`, `processing` or `completed`) and `completed_jobs`, so you can follow progress without fetching every job.
* `GET /batches/{batch_id}/result` lists every job in the batch with whether its query was `synthesizable`.
* `GET /batches/{batch_id}/jobs` and `GET /batches/{batch_id}/jobs/{job_id}` return the jobs of a batch, with their routes once completed.

`GET /engines` includes each engine's `queue_length`, the approximate number of jobs queued or running on it, to help pick a less busy engine.

### Search parameters

A job's `parameters` select the `retrosynthesis_engine` and tune the search through `synth_options`. Every job in a batch shares one set of `parameters`.

| `synth_options` | Description                                                                        |
| --------------- | ---------------------------------------------------------------------------------- |
| `max_price`     | Leave out building blocks dearer than this, in USD per gram (1 to 50,000).         |
| `max_depth`     | The most reaction steps a route may have (1 to 20).                                |
| `timeout`       | The time limit for each search, in seconds (2 to 15).                              |
| `early_exit`    | Stop each search at the first route found, rather than using the full `timeout`.   |
| `max_routes`    | The most routes to keep for each molecule (1 to 50). Every route found if omitted. |

```mermaid
stateDiagram-v2
  a: Inspect Synth Engines
  c: Submit a Query Molecule
  d: Retrieve a Status for the Query
  e: Retrieve Synthesis Routes for the Query
  note right of c: Select an engine and search options as configuration parameters.
  note right of d: Repeat until status changes to **completed**.
  [*] --> a
  [*] --> c
  a --> c
  c --> d
  d --> e
  e --> [*]: Further Processing

```

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

***

## Frequently Asked Questions

<details>

<summary>Q: Why did my search return no routes?</summary>

A: A search can finish within its `timeout` without finding a route to the target molecule. This is reported as a completed job with no routes rather than as an error. Common causes are an overly restrictive `max_depth` or `max_price`, or a molecule that is hard to make from purchasable building blocks. A longer `timeout`, or turning `early_exit` off, gives the search more time to look.

</details>

<details>

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

A: `max_routes` is a *maximum*. With `early_exit` on (the default), each search stops at the first route found. Results are also limited by the `timeout`, by `max_depth` and `max_price`, and by the existence of chemically viable routes from purchasable building blocks.

</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 retrieved with 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 result data. Use multiple batches if a screening campaign contains more query molecules.

</details>

<details>

<summary>Q: Why was my request refused with <code>402</code> or <code>403</code>?</summary>

A: Each job is a **PAI Synth request** on your team's plan, drawn from the same allowance as PAI Retro.

* `402 Payment Required`: creating a job or a batch (or adding jobs with `PUT /batches/{batch_id}`) is refused if your team has no plan (`NoPlan`), or can't start that many jobs this billing period (`UsageLimit`). A batch is refused whole.
* `403 Forbidden` with `Organization resources are not available.`: your team's workspace hasn't been set up yet. Teams are set up from the account portal.

See [Accounts, teams and billing](https://docs.pending.ai/getting-started/accounts-and-billing.md) for how plans, allowances and overage work.

</details>

<details>

<summary>Q: What happens when I delete a job or a batch?</summary>

A: Deleting removes it from the API straight away: it's no longer listed or retrievable. Deleting a batch cancels its queued jobs, and its jobs are archived in the background shortly afterwards. A job that is currently being processed can't be deleted: the API answers `409 Conflict` with `Location` and `Retry-After` headers, so retry after the given number of seconds. Deleted jobs and batches are removed permanently 30 days after they were deleted.

</details>
