> 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 high-throughput retrosynthetic tree search
Pending AI's Synth capability performs a tree search over reaction templates to find synthetic routes from purchasable building blocks to a target molecule, in a single request. 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 or novelty.
***
## Workflow Summary
A single `POST /treesearch` request runs a complete tree search for one target molecule and returns every validated route found within the requested time budget, along with vendor pricing for the building blocks involved. There is no separate submit/poll/retrieve cycle — the search runs synchronously and the response contains the full result set.
```mermaid
stateDiagram-v2
a: Submit a target molecule for tree search
b: Search runs synchronously up to max_seconds
c: Receive validated routes, pricing, and search metadata
[*] --> a
a --> b
b --> c
c --> [*]
```
Search behaviour can be tuned per request:
* **Time and depth budget** (`max_seconds`, `max_depth`) control how long the search runs and how many reaction steps it will consider.
* **Pruning masks** (`mask_trivial_solution`, `mask_bblocks_mw_gte`, `mask_usd_pricing_gte`, `mask_lead_times_gte`) exclude routes that aren't practically useful — e.g. trivial one-step "solutions", overly large building blocks, or building blocks that are prohibitively expensive or slow to source.
* **Backbone grouping** (`max_backbone_groups`, `max_backbone_group_size`, `limit_backbone_group_size_by_cost`) controls how routes sharing a synthetic backbone are clustered and truncated in the response, to keep results manageable for backbones with many equivalent building block substitutions.
* **`ships_to`** scopes pricing/lead-time annotations to a specific delivery region.
See the available [Guides](/developer-tools/guides.md) for more implementation possibilities when integrating with existing drug discovery pipelines.
***
## Frequently Asked Questions
Q: Why did my search return no routes?
A: A search can complete within `max_seconds` without finding any validated route to the target molecule — this is reported via `metadata.validated_routes` (0) rather than as an error. Common causes are an overly restrictive `max_depth`, pruning masks (`mask_usd_pricing_gte`, `mask_bblocks_mw_gte`, `mask_lead_times_gte`) that exclude every candidate route found, or a target molecule that genuinely has no accessible synthetic route from the available building block inventory within the given depth.
Q: What does `mask_trivial_solution` do?
A: When enabled (the default), routes where the target molecule is itself a purchasable building block are excluded from the result, since a zero-step "route" is rarely useful in practice.
Q: How is a route's cost calculated?
A: Each building block used in a route is annotated with vendor pricing data via `pricing_annotations`, keyed by `major_component_id`, which links back to the building block nodes in the route. `mask_usd_pricing_gte` and `mask_lead_times_gte` prune candidate building blocks during the search before routes are constructed, rather than filtering completed routes afterwards.
Q: What's the difference between `max_backbone_groups` and `max_backbone_group_size`?
A: Many distinct routes can share the same reaction backbone and differ only in which interchangeable building block was used at one or more steps. `max_backbone_groups` limits how many distinct backbones are returned; `max_backbone_group_size` limits how many building-block variations are kept per backbone. `limit_backbone_group_size_by_cost` controls whether that per-backbone limit keeps the cheapest variations first.