> 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/tree-search.md).

# Tree Search

Search for synthetic routes to a target molecule

Run a retrosynthetic tree search for a single target molecule and receive every validated route found within the requested time budget, along with vendor pricing for the building blocks involved.

## Create a tree search

> Run a synchronous retrosynthetic tree search for a target molecule. The search runs for up to \`max\_seconds\`, exploring reaction steps to the configured \`max\_depth\`, and the response contains every validated route found together with pricing/lead-time annotations for the building blocks used.

````json
{"openapi":"3.1.0","info":{"title":"Pending AI Synth API","version":"0.0.1"},"tags":[{"name":"Tree Search","description":"Run a retrosynthetic tree search for a single target molecule and receive every validated route found within the requested time budget, along with vendor pricing for the building blocks involved."}],"servers":[{"url":"https://api.pending.ai/synth/v1","description":"Pending AI Server"}],"security":[{"oauth":[]},{"token":[]}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an OAuth2 authorization code 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":{"authorizationCode":{"authorizationUrl":"https://auth.pending.ai/authorize","tokenUrl":"https://auth.pending.ai/oauth/token","refreshUrl":"https://auth.pending.ai/oauth/token","scopes":{"openid":"Required for OpenID Connect sign-in","profile":"Access to the user's basic profile information","email":"Access to the user's email address","offline_access":"Request a refresh token"}}}},"token":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication.\n\nProvide a valid Pending AI authentication token. Generating tokens can be done manually through the Pending AI CLI. Ensure you have an existing account or [register now](https://lab.pending.ai/).\n\n```bash\npendingai auth login\npendingai auth token\n```"}},"schemas":{"CreateTreeSearch":{"type":"object","title":"CreateTreeSearch","description":"Request data for creating a tree search.","required":["search_smiles"],"properties":{"search_smiles":{"type":"string","title":"Search Smiles","description":"The SMILES string representing the target molecule to search for synthetic routes to."},"early_exit_first_solution":{"type":"boolean","title":"Early Exit First Solution","description":"If true, stop the search as soon as one validated solution route is found, rather than continuing to search for the full time budget.","default":true},"max_seconds":{"type":"number","title":"Max Seconds","description":"Maximum wall-clock time in seconds to run the tree search.","default":4},"max_depth":{"type":"integer","title":"Max Depth","description":"Maximum number of reaction steps (tree depth) to search.","minimum":1,"maximum":50,"default":5},"mask_trivial_solution":{"type":"boolean","title":"Mask Trivial Solution","description":"Exclude the trivial zero-step solution where the target molecule is itself a purchasable building block.","default":true},"mask_bblocks_mw_gte":{"type":["number","null"],"title":"Mask Bblocks Mw Gte","description":"Exclude building blocks with a molecular weight (daltons) greater than or equal to this value. Omit or set to null for no molecular weight limit.","default":null},"mask_usd_pricing_gte":{"type":["number","null"],"title":"Mask Usd Pricing Gte","description":"Exclude building blocks priced at or above this normalised USD-per-gram cost. Omit or set to null for no price limit.","default":10000},"ships_to":{"type":["string","null"],"title":"Ships To","description":"ISO country code used to scope pricing and lead-time annotations to a specific delivery region.","default":"US"},"mask_lead_times_gte":{"type":["number","null"],"title":"Mask Lead Times Gte","description":"Exclude building blocks with a lead time (days) to the `ships_to` region greater than or equal to this value. Omit or set to null for no lead-time limit.","default":null},"max_backbone_groups":{"type":"integer","title":"Max Backbone Groups","description":"Maximum number of distinct synthetic route backbones to return.","default":5},"max_backbone_group_size":{"type":"integer","title":"Max Backbone Group Size","description":"Maximum number of building-block variations to keep per backbone.","default":10},"limit_backbone_group_size_by_cost":{"type":"boolean","title":"Limit Backbone Group Size By Cost","description":"When true, keep the cheapest building-block variations first when truncating to `max_backbone_group_size`.","default":false}}},"TreeSearchResult":{"type":"object","title":"TreeSearchResult","description":"The result of a completed tree search.","properties":{"search_smiles":{"type":"string","description":"Canonicalised SMILES of the target molecule that was searched for."},"metadata":{"$ref":"#/components/schemas/TreeSearchMetadata"},"route_hierarchy":{"type":"object","description":"Every validated route found, keyed by the canonical SMILES of each intermediate/precursor molecule reached during the search, then by tree depth (as a string index), to a list of `RouteGraph` objects representing the distinct routes passing through that molecule at that depth. This is a dynamic, search-dependent structure -- consult `metadata.validated_routes` for the total route count rather than assuming a fixed shape.","additionalProperties":{"type":"object","additionalProperties":{"type":"array","items":{"type":"array","items":{"$ref":"#/components/schemas/RouteGraph"}}}}},"pricing_annotations":{"type":"array","description":"Pricing/availability annotations for every building block used across all returned routes.","items":{"$ref":"#/components/schemas/PricingAnnotation"}},"reagent_results":{"type":"object","description":"Supplementary reaction-level metadata, keyed by reaction SMILES/SMARTS to the list of graph edge `id`s that reaction corresponds to.","properties":{"reaction_to_edges":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}},"TreeSearchMetadata":{"type":"object","title":"TreeSearchMetadata","description":"Timing information and statistics about the search process.","properties":{"tree_search_elapsed":{"type":"number","description":"Time elapsed in seconds for the tree search phase."},"routes_extracted_elapsed":{"type":"number","description":"Time elapsed in seconds for the route extraction phase."},"routes_validated_elapsed":{"type":"number","description":"Time elapsed in seconds for the route validation phase."},"bblock_annotations_elapsed":{"type":"number","description":"Time elapsed in seconds for the building block annotation phase."},"total_elapsed":{"type":"number","description":"Total time elapsed in seconds for the entire search process."},"total_graph_nodes":{"type":"integer","description":"Total number of nodes in the synthesis graph generated during the search."},"unvalidated_routes":{"type":"integer","description":"Number of routes extracted from the synthesis graph that were not validated as successful synthetic routes."},"validated_routes":{"type":"integer","description":"Number of routes successfully validated as synthetic routes. 0 if no route was found within the search budget."},"total_bblocks":{"type":"integer","description":"Total number of unique building blocks considered during the search."}}},"RouteGraph":{"type":"object","title":"RouteGraph","description":"A single synthesis route represented as a directed graph of molecule and reaction template nodes.","properties":{"directed":{"type":"boolean"},"multigraph":{"type":"boolean"},"nodes":{"type":"array","items":{"$ref":"#/components/schemas/RouteGraphNode"}},"edges":{"type":"array","items":{"$ref":"#/components/schemas/RouteGraphEdge"}}}},"RouteGraphNode":{"type":"object","title":"RouteGraphNode","description":"A node in a synthesis route graph, representing either a molecule (including purchasable building blocks) or a reaction template. Node type is distinguished by which fields are present in `data`: a reaction template node has `template_id`; a molecule/building-block node has `smiles`.","properties":{"id":{"type":"string","description":"Unique identifier for the node within the synthesis graph, referenced by `edges`."},"data":{"type":"object","description":"Node-specific data; shape depends on whether this is a molecule or a reaction template node."}}},"RouteGraphEdge":{"type":"object","title":"RouteGraphEdge","description":"A directed edge in a synthesis route graph, from a `source` node to a `target` node, connecting molecules to the reaction templates that produce or consume them.","properties":{"source":{"type":"string","description":"Node `id` of the edge's source."},"target":{"type":"string","description":"Node `id` of the edge's target."}}},"PricingAnnotation":{"type":"object","title":"PricingAnnotation","description":"Vendor pricing and availability annotation for a building block used in a route. Common laboratory chemicals (`vendor_name: \"Common Lab Chemicals\"`) carry only structural fields; chemicals sourced from Chemspace additionally carry pricing, pack size, and regional lead times.","properties":{"major_component_id":{"type":"integer","description":"Building block index this annotation applies to; links back to `building_block_idx` on route graph nodes."},"full_canonical":{"type":"string","description":"Full canonical SMILES for the annotated building block, including any minor components."},"major_component":{"type":"string","description":"The primary chemical structure within the building block."},"minor_components":{"type":["string","null"],"description":"Additional chemical structures within the building block, if any."},"mw":{"type":"number","description":"Molecular weight of `full_canonical`."},"vendor_name":{"type":"string","description":"Vendor supplying the chemical. `\"Common Lab Chemicals\"` indicates no pricing/availability data is included."},"cs_id":{"type":"string","description":"Chemspace identifier for the chemical. Only present for Chemspace-sourced annotations."},"cs_prefix":{"type":"string","description":"Chemspace category prefix. Only present for Chemspace-sourced annotations."},"cs_url":{"type":"string","description":"Direct link to the chemical's page on Chemspace. Only present for Chemspace-sourced annotations."},"pack":{"type":"number","description":"Pack size, in units of `uom`. Only present for Chemspace-sourced annotations."},"uom":{"type":"string","description":"Unit of measure for `pack` (e.g. `kg`, `g`). Only present for Chemspace-sourced annotations."},"price_usd":{"type":"number","description":"Price in USD for the given `pack`/`uom`. Only present for Chemspace-sourced annotations."},"normalised_usd":{"type":"number","description":"Price normalised to a standard per-gram USD metric, for comparing across pack sizes. Only present for Chemspace-sourced annotations."},"api_timestamp":{"type":"string","format":"date-time","description":"When this pricing information was retrieved. Only present for Chemspace-sourced annotations."},"lead_time_days_to_US":{"type":"integer","description":"Lead time in days to the United States. Only present for Chemspace-sourced annotations."},"lead_time_days_to_CA":{"type":"integer"},"lead_time_days_to_GB":{"type":"integer"},"lead_time_days_to_FR":{"type":"integer"},"lead_time_days_to_CH":{"type":"integer"},"lead_time_days_to_DE":{"type":"integer"},"lead_time_days_to_CN":{"type":"integer"},"lead_time_days_to_AU":{"type":"integer"}}},"HTTPValidationError":{"type":"object","title":"HTTPValidationError","properties":{"detail":{"type":"array","items":{"$ref":"#/components/schemas/ValidationError"}}}},"ValidationError":{"type":"object","title":"ValidationError","properties":{"loc":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"integer"}]}},"msg":{"type":"string"},"type":{"type":"string"}},"required":["loc","msg","type"]}}},"paths":{"/treesearch":{"post":{"operationId":"create_tree_search","summary":"Create a tree search","description":"Run a synchronous retrosynthetic tree search for a target molecule. The search runs for up to `max_seconds`, exploring reaction steps to the configured `max_depth`, and the response contains every validated route found together with pricing/lead-time annotations for the building blocks used.","tags":["Tree Search"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTreeSearch"}}}},"responses":{"200":{"description":"Returns the tree search result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TreeSearchResult"}}}},"400":{"description":"Request contained invalid data (e.g. an unparsable SMILES string).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing or invalid authentication credentials."},"422":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
````