# Synthesis Jobs

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"]}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pending.ai/api-reference/pai-retro/synthesis-jobs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.