---
title: AiZynthFinder API & automation
description: >-
  Submit AiZynthFinder retrosynthesis as a job over HTTP: the job type, the
  parameters the backend accepts, and the results and files a finished job
  returns.
---

You can run [AiZynthFinder](/docs/aizynthfinder) without chat by submitting it as a job. Send a target SMILES to the [Jobs API](/docs/api/rest-jobs), poll until it finishes, and you get back ranked retrosynthesis routes plus the JSON and ZIP files behind them. In chat, Ivy calls the same backend through the `aizynthfinder_retro` tool.

## Submit a job

AiZynthFinder uses the standard `POST /api/v1/jobs` shape. The job type is `aizynthfinder`, and the only required input is `smiles`.

```bash
curl -X POST https://www.ivybiosciences.com/api/v1/jobs \
  -H "Authorization: Bearer ivy_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "aizynthfinder",
    "tool_input_parameters": {"smiles": "CC(=O)OC1=CC=CC=C1C(=O)O"},
    "job_title": "Aspirin retrosynthesis"
  }'
```

The response carries the job `id` and its initial status. Poll `GET /api/v1/jobs/:jobId`, or follow the [SSE job stream](/docs/api/realtime-sse#job-event-proxy-sse) instead of polling. To run many targets with the same settings, use [Batch Jobs](/docs/api/rest-batch), where `aizynthfinder` is one of the batch-enabled job types.

## Parameters

| Parameter | Type | Default | Notes |
|---|---|---|---|
| `smiles` | string | required | Target molecule. It must be non-empty and at most 1000 characters. |
| `policy` | string[] | config default | Expansion policy names. Each name must match an expansion policy in the job's AiZynthFinder config. |
| `filter` | string[] | config default | Filter policy names, which must match the config. |
| `stocks` | string[] | config default | Stock names used to decide which precursors count as purchasable. The bundled config defines `zinc`. |
| `nproc` | integer | unset | Number of processes. The chat tool accepts 1–16. |
| `cluster` | boolean | `false` | Cluster similar routes. |
| `log_to_file` | boolean | `false` | Write a detailed search log. |
| `max_transforms` | integer | `6` | Maximum route depth, which must be at least 1. The backend caps it at 1000. |
| `iterations` | integer | `100` | MCTS iteration **ceiling**, from 1 to 5000. The search stops at whichever limit it reaches first, so iterations beyond the wall clock go unspent. |
| `time_limit` | integer | unset | Wall-clock budget for the search, in seconds, from 1 to 1800. Left unset, the config's own 120-second limit applies and the search stops there whatever the iteration ceiling says. |

`policy`, `filter` and `stocks` must be plain names. The backend rejects any item that looks like a command-line option. It does not honour a caller-supplied `config`, `output` or `checkpoint` path: results and checkpoints always go to the job's own directory.

In chat, `aizynthfinder_retro` accepts `smiles`, `policy`, `filter`, `stocks`, `nproc`, `cluster` and `log_to_file`. It does not forward `max_transforms`, `iterations` or `time_limit`, so chat runs use the defaults: depth 6, an iteration ceiling of 100, and the config's 120-second wall clock. Raising either limit means submitting the job directly.

## Results

`GET /api/v1/jobs/:jobId` returns a finished job's record with its result. The main result fields are:

| Field | Meaning |
|---|---|
| `target` | The SMILES you submitted |
| `is_solved` | `true` when at least one route was found |
| `number_of_routes` | Number of routes returned |
| `search_time` | Search time in seconds |
| `routes`, `trees` | The routes as synthesis trees, from the target down to its precursors |
| `search_configuration` | The `max_transforms`, `iterations`, the wall clock the search actually carried, and the config it used |
| `reactions_classified` | Number of route reactions that were given a reaction class |

[Outputs](/docs/aizynthfinder/outputs) explains how to read route scores and the purchasability of each precursor.

## Files

A finished job's record (`GET /api/v1/jobs/:jobId`) lists its files. Download them as described in [Artifacts & Storage](/docs/api/rest-artifacts).

| Artifact type | Contents |
|---|---|
| `aizynthfinder_unified_zip` | A ZIP bundle with the routes and their reaction classifications. Listed first when present. |
| `aizynthfinder_results` | The full result above as one JSON file |
| `aizynthfinder_routes_gz` | The raw AiZynthFinder output files, such as `output.json.gz` |

A job can finish without the ZIP bundle, because the backend treats that bundle as optional. In that case, read the JSON result instead.

## Failures

The backend fails the job when the SMILES is empty or too long, when `max_transforms` or `iterations` is out of range, when a list parameter contains an option-like token, when the AiZynthFinder run itself exits with an error, or when the search runs past one hour. A target with no route in the selected stocks is not a failure: the job completes with `is_solved: false` and `number_of_routes: 0`. See [Troubleshooting](/docs/aizynthfinder/troubleshooting) for what to change when no route is found.

Status codes and the error envelope follow the [Jobs API](/docs/api/rest-jobs) and [SDK errors](/docs/api/sdk-errors) pages. AiZynthFinder has no error codes of its own.