# Batch Screening

A high-throughput screening campaign for large-scale chemical libraries can be achieved through submitting *batches* of **Retrosynthesis** jobs with shared `parameters`. Pending AI offers batch sizes of up to 100000 jobs which can be created and then appended to with additional API requests. Batch progress can be tracked with live updates to the number of completed jobs and a high-level screening overview can be retrieved.

Batch synthesis jobs impact the overall queue size for a given engine. Larger batches may lead to a longer wait time for it to complete. Additional metadata data can also be added to the batch submission to help distinguish results beyond an arbitrary batch `id` field.

See [here](https://docs.pending.ai/capabilities/synthetic-accessibility) for more information on our **Retrosynthesis** capability.

## List batches

> Retrieve a list of batches.

```json
{"openapi":"3.1.0","info":{"title":"PAI Retro","version":"v2"},"tags":[{"description":"\nA high-throughput screening campaign for large-scale chemical libraries can be achieved\nthrough submitting *batches* of **Retrosynthesis** jobs with shared `parameters`. Pending\nAI offers batch sizes of up to 100000 jobs which can be created and then appended to with\nadditional API requests. Batch progress can be tracked with live updates to the number of\ncompleted jobs and a high-level screening overview can be retrieved.\n\nBatch synthesis jobs impact the overall queue size for a given engine. Larger batches may\nlead to a longer wait time for it to complete. Additional metadata data can also be added\nto the batch submission to help distinguish results beyond an arbitrary batch `id` field.\n\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility)\nfor more information on our **Retrosynthesis** capability.\n                ","name":"Batches"}],"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_BatchResource_":{"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/BatchResource"},"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[BatchResource]","type":"object"},"BatchResource":{"description":"Batches are collections of retrosynthesis jobs that share a common\nset of parameters. Batches allow for easy management of large sets\nof synthesis targets and provide a mechanism for tracking the status\nof multiple jobs as a single entity.\n\nThere is an upper limit of 100,000 jobs per batch which requires any\nfurther jobs to be submitted in a new batch. Multiple identifiers\ncan be used to distinguish between them.","properties":{"created":{"description":"Timestamp for when the batch was created.","format":"date-time","title":"Created","type":"string"},"description":{"anyOf":[{"maxLength":2048,"pattern":"^[\\w\\s\\-\\:]*$","type":"string"},{"type":"null"}],"description":"An optional description for the batch. The description provides\nadditional context about the batch to help with distinguishing\nbetween other batches.","title":"Description"},"filename":{"anyOf":[{"maxLength":2048,"pattern":"^[\\w\\-\\:]*$","type":"string"},{"type":"null"}],"description":"An optional filename to help identify the batch and ideal for when a\nbatch is submitted via file.","title":"Filename"},"id":{"description":"The unique resource identifier.","pattern":"^\\w+$","title":"Resource Id","type":"string"},"name":{"anyOf":[{"maxLength":256,"pattern":"^[\\w\\s\\-\\:]*$","type":"string"},{"type":"null"}],"description":"An optional name for the batch. The name provides a human-readable\nidentifier for the batch and is not required to be unique.","title":"Name"},"number_of_jobs":{"description":"Total number of retrosynthesis jobs that belong to a batch. The\nvalue can change over time as new jobs are added to the batch.","maximum":100000,"minimum":1,"title":"Number Of Jobs","type":"integer"},"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. These\noptions are shared across all jobs that belong to the batch."},"updated":{"description":"Timestamp for when the batch was last updated.","format":"date-time","title":"Updated","type":"string"}},"required":["id","object","number_of_jobs","parameters"],"title":"Batch","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"},"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":{"/batches":{"get":{"description":"Retrieve a list of batches.","operationId":"retrieve_batches_batches_get","parameters":[{"description":"A pagination field for looking up items in the previous page of results from this resource `id`. Use the first item in the `data` field of the previous response.","in":"query","name":"created-before","required":false,"schema":{"anyOf":[{"maxLength":255,"minLength":1,"pattern":"^\\w+$","type":"string"},{"type":"null"}],"description":"A pagination field for looking up items in the previous page of results from this resource `id`. Use the first item in the `data` field of the previous response.","title":"Created-Before"}},{"description":"A pagination field for looking up items in the next page of results from this resource `id`. Use the final item in the `data` field of the previous response.","in":"query","name":"created-after","required":false,"schema":{"anyOf":[{"maxLength":255,"minLength":1,"pattern":"^\\w+$","type":"string"},{"type":"null"}],"description":"A pagination field for looking up items in the next page of results from this resource `id`. Use the final item in the `data` field of the previous response.","title":"Created-After"}},{"description":"Limit the number of results in the `data` field of the returned list. The number of items in the page can be fewer than the requested value.","in":"query","name":"size","required":false,"schema":{"default":50,"description":"Limit the number of results in the `data` field of the returned list. The number of items in the page can be fewer than the requested value.","maximum":100,"minimum":1,"title":"Size","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResourceList_BatchResource_"}}},"description":"Returns a list of batches."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}},"description":"Request validation failed."}},"summary":"List batches","tags":["Batches"]}}}}
```

## Create a batch

> Create a new batch of retrosynthesis jobs. Individual jobs are provided as a collection of molecules and share a set of \`parameters\` options for each.\
> \
> \- Provide additional metadata to tag and identify the batch.\
> \- The batch size limit is 10000 jobs, although for requests that timeout or fail can be updated with jobs after creation.

```json
{"openapi":"3.1.0","info":{"title":"PAI Retro","version":"v2"},"tags":[{"description":"\nA high-throughput screening campaign for large-scale chemical libraries can be achieved\nthrough submitting *batches* of **Retrosynthesis** jobs with shared `parameters`. Pending\nAI offers batch sizes of up to 100000 jobs which can be created and then appended to with\nadditional API requests. Batch progress can be tracked with live updates to the number of\ncompleted jobs and a high-level screening overview can be retrieved.\n\nBatch synthesis jobs impact the overall queue size for a given engine. Larger batches may\nlead to a longer wait time for it to complete. Additional metadata data can also be added\nto the batch submission to help distinguish results beyond an arbitrary batch `id` field.\n\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility)\nfor more information on our **Retrosynthesis** capability.\n                ","name":"Batches"}],"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__batches__Batch__CreateParams":{"description":"Request data for creating a new batch.","properties":{"description":{"anyOf":[{"maxLength":2048,"type":"string"},{"type":"null"}],"description":"An optional name for the batch. The name provides a human-\nreadable identifier for the batch and is not required to be \nunique.","title":"Description"},"filename":{"anyOf":[{"maxLength":2048,"type":"string"},{"type":"null"}],"description":"An optional filename to help identify the batch and ideal for \nwhen a batch is submitted via file.","title":"Filename"},"name":{"anyOf":[{"maxLength":128,"type":"string"},{"type":"null"}],"description":"An optional name for the batch. The name provides a human-\nreadable identifier for the batch and is not required to be \nunique.","title":"Name"},"parameters":{"$ref":"#/components/schemas/Parameters","description":"Parameters used for controlling the retrosynthesis process. \nThese options are shared across all jobs that belong to the \nbatch."},"smiles":{"description":"A collection of target molecules in a SMILES format to perform \nretrosynthesis on. Each structure is submitted as an individual \njob and queued separately.\n\n**NOTE**: Duplicate structures are removed automatically.","items":{"pattern":"^[a-zA-Z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*]+$","type":"string"},"maxItems":100000,"minItems":1,"title":"Smiles","type":"array"}},"required":["smiles","parameters"],"title":"BatchCreateParams","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"},"BatchResource":{"description":"Batches are collections of retrosynthesis jobs that share a common\nset of parameters. Batches allow for easy management of large sets\nof synthesis targets and provide a mechanism for tracking the status\nof multiple jobs as a single entity.\n\nThere is an upper limit of 100,000 jobs per batch which requires any\nfurther jobs to be submitted in a new batch. Multiple identifiers\ncan be used to distinguish between them.","properties":{"created":{"description":"Timestamp for when the batch was created.","format":"date-time","title":"Created","type":"string"},"description":{"anyOf":[{"maxLength":2048,"pattern":"^[\\w\\s\\-\\:]*$","type":"string"},{"type":"null"}],"description":"An optional description for the batch. The description provides\nadditional context about the batch to help with distinguishing\nbetween other batches.","title":"Description"},"filename":{"anyOf":[{"maxLength":2048,"pattern":"^[\\w\\-\\:]*$","type":"string"},{"type":"null"}],"description":"An optional filename to help identify the batch and ideal for when a\nbatch is submitted via file.","title":"Filename"},"id":{"description":"The unique resource identifier.","pattern":"^\\w+$","title":"Resource Id","type":"string"},"name":{"anyOf":[{"maxLength":256,"pattern":"^[\\w\\s\\-\\:]*$","type":"string"},{"type":"null"}],"description":"An optional name for the batch. The name provides a human-readable\nidentifier for the batch and is not required to be unique.","title":"Name"},"number_of_jobs":{"description":"Total number of retrosynthesis jobs that belong to a batch. The\nvalue can change over time as new jobs are added to the batch.","maximum":100000,"minimum":1,"title":"Number Of Jobs","type":"integer"},"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. These\noptions are shared across all jobs that belong to the batch."},"updated":{"description":"Timestamp for when the batch was last updated.","format":"date-time","title":"Updated","type":"string"}},"required":["id","object","number_of_jobs","parameters"],"title":"Batch","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":{"/batches":{"post":{"description":"Create a new batch of retrosynthesis jobs. Individual jobs are provided as a collection of molecules and share a set of `parameters` options for each.\n\n- Provide additional metadata to tag and identify the batch.\n- The batch size limit is 10000 jobs, although for requests that timeout or fail can be updated with jobs after creation.","operationId":"create_batch_batches_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/pai_retro__models__batches__Batch__CreateParams"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResource"}}},"description":"Returns the batch."},"402":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Payment gateway failed."},"413":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Batch resource exceeded size limit."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}},"description":"Request validation failed."}},"summary":"Create a batch","tags":["Batches"]}}}}
```

## Retrieve a batch

> Retrieve a batch with attached metadata and job parameters.

```json
{"openapi":"3.1.0","info":{"title":"PAI Retro","version":"v2"},"tags":[{"description":"\nA high-throughput screening campaign for large-scale chemical libraries can be achieved\nthrough submitting *batches* of **Retrosynthesis** jobs with shared `parameters`. Pending\nAI offers batch sizes of up to 100000 jobs which can be created and then appended to with\nadditional API requests. Batch progress can be tracked with live updates to the number of\ncompleted jobs and a high-level screening overview can be retrieved.\n\nBatch synthesis jobs impact the overall queue size for a given engine. Larger batches may\nlead to a longer wait time for it to complete. Additional metadata data can also be added\nto the batch submission to help distinguish results beyond an arbitrary batch `id` field.\n\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility)\nfor more information on our **Retrosynthesis** capability.\n                ","name":"Batches"}],"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":{"BatchResource":{"description":"Batches are collections of retrosynthesis jobs that share a common\nset of parameters. Batches allow for easy management of large sets\nof synthesis targets and provide a mechanism for tracking the status\nof multiple jobs as a single entity.\n\nThere is an upper limit of 100,000 jobs per batch which requires any\nfurther jobs to be submitted in a new batch. Multiple identifiers\ncan be used to distinguish between them.","properties":{"created":{"description":"Timestamp for when the batch was created.","format":"date-time","title":"Created","type":"string"},"description":{"anyOf":[{"maxLength":2048,"pattern":"^[\\w\\s\\-\\:]*$","type":"string"},{"type":"null"}],"description":"An optional description for the batch. The description provides\nadditional context about the batch to help with distinguishing\nbetween other batches.","title":"Description"},"filename":{"anyOf":[{"maxLength":2048,"pattern":"^[\\w\\-\\:]*$","type":"string"},{"type":"null"}],"description":"An optional filename to help identify the batch and ideal for when a\nbatch is submitted via file.","title":"Filename"},"id":{"description":"The unique resource identifier.","pattern":"^\\w+$","title":"Resource Id","type":"string"},"name":{"anyOf":[{"maxLength":256,"pattern":"^[\\w\\s\\-\\:]*$","type":"string"},{"type":"null"}],"description":"An optional name for the batch. The name provides a human-readable\nidentifier for the batch and is not required to be unique.","title":"Name"},"number_of_jobs":{"description":"Total number of retrosynthesis jobs that belong to a batch. The\nvalue can change over time as new jobs are added to the batch.","maximum":100000,"minimum":1,"title":"Number Of Jobs","type":"integer"},"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. These\noptions are shared across all jobs that belong to the batch."},"updated":{"description":"Timestamp for when the batch was last updated.","format":"date-time","title":"Updated","type":"string"}},"required":["id","object","number_of_jobs","parameters"],"title":"Batch","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"},"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":{"/batches/{batch_id}":{"get":{"description":"Retrieve a batch with attached metadata and job parameters.","operationId":"retrieve_batch_batches__batch_id__get","parameters":[{"description":"A unique identifier for a batch resource.","in":"path","name":"batch_id","required":true,"schema":{"description":"A unique identifier for a batch resource.","maxLength":255,"minLength":1,"pattern":"^\\w+$","title":"Batch Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResource"}}},"description":"Returns the batch."},"404":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Batch resource not found."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}},"description":"Request validation failed."}},"summary":"Retrieve a batch","tags":["Batches"]}}}}
```

## Update a batch

> Update a batch resource with more retrosynthesis jobs. The added jobs are queued but must not exceed the total batch limit for a batch resource.

```json
{"openapi":"3.1.0","info":{"title":"PAI Retro","version":"v2"},"tags":[{"description":"\nA high-throughput screening campaign for large-scale chemical libraries can be achieved\nthrough submitting *batches* of **Retrosynthesis** jobs with shared `parameters`. Pending\nAI offers batch sizes of up to 100000 jobs which can be created and then appended to with\nadditional API requests. Batch progress can be tracked with live updates to the number of\ncompleted jobs and a high-level screening overview can be retrieved.\n\nBatch synthesis jobs impact the overall queue size for a given engine. Larger batches may\nlead to a longer wait time for it to complete. Additional metadata data can also be added\nto the batch submission to help distinguish results beyond an arbitrary batch `id` field.\n\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility)\nfor more information on our **Retrosynthesis** capability.\n                ","name":"Batches"}],"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":{"UpdateParams":{"description":"Request data for updating an existing batch.","properties":{"smiles":{"description":"A collection of target molecules in a SMILES format to perform \nretrosynthesis on. Each structure is submitted as an individual \njob and queued separately.\n\n**NOTE**: Duplicate structures are removed automatically.","items":{"pattern":"^[a-zA-Z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*]+$","type":"string"},"maxItems":100000,"minItems":1,"title":"Smiles","type":"array"}},"required":["smiles"],"title":"BatchUpdateParams","type":"object"},"BatchResource":{"description":"Batches are collections of retrosynthesis jobs that share a common\nset of parameters. Batches allow for easy management of large sets\nof synthesis targets and provide a mechanism for tracking the status\nof multiple jobs as a single entity.\n\nThere is an upper limit of 100,000 jobs per batch which requires any\nfurther jobs to be submitted in a new batch. Multiple identifiers\ncan be used to distinguish between them.","properties":{"created":{"description":"Timestamp for when the batch was created.","format":"date-time","title":"Created","type":"string"},"description":{"anyOf":[{"maxLength":2048,"pattern":"^[\\w\\s\\-\\:]*$","type":"string"},{"type":"null"}],"description":"An optional description for the batch. The description provides\nadditional context about the batch to help with distinguishing\nbetween other batches.","title":"Description"},"filename":{"anyOf":[{"maxLength":2048,"pattern":"^[\\w\\-\\:]*$","type":"string"},{"type":"null"}],"description":"An optional filename to help identify the batch and ideal for when a\nbatch is submitted via file.","title":"Filename"},"id":{"description":"The unique resource identifier.","pattern":"^\\w+$","title":"Resource Id","type":"string"},"name":{"anyOf":[{"maxLength":256,"pattern":"^[\\w\\s\\-\\:]*$","type":"string"},{"type":"null"}],"description":"An optional name for the batch. The name provides a human-readable\nidentifier for the batch and is not required to be unique.","title":"Name"},"number_of_jobs":{"description":"Total number of retrosynthesis jobs that belong to a batch. The\nvalue can change over time as new jobs are added to the batch.","maximum":100000,"minimum":1,"title":"Number Of Jobs","type":"integer"},"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. These\noptions are shared across all jobs that belong to the batch."},"updated":{"description":"Timestamp for when the batch was last updated.","format":"date-time","title":"Updated","type":"string"}},"required":["id","object","number_of_jobs","parameters"],"title":"Batch","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"},"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":{"/batches/{batch_id}":{"put":{"description":"Update a batch resource with more retrosynthesis jobs. The added jobs are queued but must not exceed the total batch limit for a batch resource.","operationId":"update_batch_batches__batch_id__put","parameters":[{"description":"A unique identifier for a batch resource.","in":"path","name":"batch_id","required":true,"schema":{"description":"A unique identifier for a batch resource.","maxLength":255,"minLength":1,"pattern":"^\\w+$","title":"Batch Id","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateParams"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResource"}}},"description":"Returns the updated batch."},"402":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Payment gateway failed."},"404":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Batch resource not found."},"413":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Batch resource exceeded size limit."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}},"description":"Request validation failed."}},"summary":"Update a batch","tags":["Batches"]}}}}
```

## Delete a batch

> Delete a batch resource and all attached retrosynthesis jobs. When the request is made for a batch currently being processed, all queued jobs are cancelled.

```json
{"openapi":"3.1.0","info":{"title":"PAI Retro","version":"v2"},"tags":[{"description":"\nA high-throughput screening campaign for large-scale chemical libraries can be achieved\nthrough submitting *batches* of **Retrosynthesis** jobs with shared `parameters`. Pending\nAI offers batch sizes of up to 100000 jobs which can be created and then appended to with\nadditional API requests. Batch progress can be tracked with live updates to the number of\ncompleted jobs and a high-level screening overview can be retrieved.\n\nBatch synthesis jobs impact the overall queue size for a given engine. Larger batches may\nlead to a longer wait time for it to complete. Additional metadata data can also be added\nto the batch submission to help distinguish results beyond an arbitrary batch `id` field.\n\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility)\nfor more information on our **Retrosynthesis** capability.\n                ","name":"Batches"}],"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":{"BatchResource":{"description":"Batches are collections of retrosynthesis jobs that share a common\nset of parameters. Batches allow for easy management of large sets\nof synthesis targets and provide a mechanism for tracking the status\nof multiple jobs as a single entity.\n\nThere is an upper limit of 100,000 jobs per batch which requires any\nfurther jobs to be submitted in a new batch. Multiple identifiers\ncan be used to distinguish between them.","properties":{"created":{"description":"Timestamp for when the batch was created.","format":"date-time","title":"Created","type":"string"},"description":{"anyOf":[{"maxLength":2048,"pattern":"^[\\w\\s\\-\\:]*$","type":"string"},{"type":"null"}],"description":"An optional description for the batch. The description provides\nadditional context about the batch to help with distinguishing\nbetween other batches.","title":"Description"},"filename":{"anyOf":[{"maxLength":2048,"pattern":"^[\\w\\-\\:]*$","type":"string"},{"type":"null"}],"description":"An optional filename to help identify the batch and ideal for when a\nbatch is submitted via file.","title":"Filename"},"id":{"description":"The unique resource identifier.","pattern":"^\\w+$","title":"Resource Id","type":"string"},"name":{"anyOf":[{"maxLength":256,"pattern":"^[\\w\\s\\-\\:]*$","type":"string"},{"type":"null"}],"description":"An optional name for the batch. The name provides a human-readable\nidentifier for the batch and is not required to be unique.","title":"Name"},"number_of_jobs":{"description":"Total number of retrosynthesis jobs that belong to a batch. The\nvalue can change over time as new jobs are added to the batch.","maximum":100000,"minimum":1,"title":"Number Of Jobs","type":"integer"},"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. These\noptions are shared across all jobs that belong to the batch."},"updated":{"description":"Timestamp for when the batch was last updated.","format":"date-time","title":"Updated","type":"string"}},"required":["id","object","number_of_jobs","parameters"],"title":"Batch","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"},"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":{"/batches/{batch_id}":{"delete":{"description":"Delete a batch resource and all attached retrosynthesis jobs. When the request is made for a batch currently being processed, all queued jobs are cancelled.","operationId":"delete_batch_batches__batch_id__delete","parameters":[{"description":"A unique identifier for a batch resource.","in":"path","name":"batch_id","required":true,"schema":{"description":"A unique identifier for a batch resource.","maxLength":255,"minLength":1,"pattern":"^\\w+$","title":"Batch Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResource"}}},"description":"Returns the deleted batch."},"402":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Payment gateway failed."},"404":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Batch resource not found."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}},"description":"Request validation failed."}},"summary":"Delete a batch","tags":["Batches"]}}}}
```

## Retrieve a batch result

> Retrieve the collection of results from retrosynthesis jobs in the batch. The list contains information about the individual job \`id\`s used for retrieving synthetic routes and whether the molecules were synthesizable.

```json
{"openapi":"3.1.0","info":{"title":"PAI Retro","version":"v2"},"tags":[{"description":"\nA high-throughput screening campaign for large-scale chemical libraries can be achieved\nthrough submitting *batches* of **Retrosynthesis** jobs with shared `parameters`. Pending\nAI offers batch sizes of up to 100000 jobs which can be created and then appended to with\nadditional API requests. Batch progress can be tracked with live updates to the number of\ncompleted jobs and a high-level screening overview can be retrieved.\n\nBatch synthesis jobs impact the overall queue size for a given engine. Larger batches may\nlead to a longer wait time for it to complete. Additional metadata data can also be added\nto the batch submission to help distinguish results beyond an arbitrary batch `id` field.\n\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility)\nfor more information on our **Retrosynthesis** capability.\n                ","name":"Batches"}],"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":{"RetrieveResultOutputItem":{"description":"Summary result for an individual job in a batch. Provides an\noverview of the job status and if any retrosynthesis results\nwere found.","properties":{"completed":{"description":"A flag to indicate if the job is completed. Results retrieved\nbefore a batch has completed may contain incomplete jobs.","title":"Completed","type":"boolean"},"job_id":{"description":"A unique identifier for the retrosynthesis job. The value can be\nused to retrieve the full job resource with any results.","pattern":"^\\w+$","title":"Job Id","type":"string"},"smiles":{"description":"The retrosynthesis target structure in a SMILES format.","pattern":"^[a-zA-Z0-9\\(\\)+-=#%+@\\/\\\\\\[\\]\\*]+$","title":"Smiles","type":"string"},"synthesizable":{"description":"A flag to indicate if the structure is synthesizable. A\nstructure is considered synthesizable if at least one synthesis\nroute was found during retrosynthesis.","title":"Synthesizable","type":"boolean"}},"required":["job_id","smiles","completed","synthesizable"],"title":"BatchResult","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":{"/batches/{batch_id}/result":{"get":{"description":"Retrieve the collection of results from retrosynthesis jobs in the batch. The list contains information about the individual job `id`s used for retrieving synthetic routes and whether the molecules were synthesizable.","operationId":"retrieve_batch_result_batches__batch_id__result_get","parameters":[{"description":"A unique identifier for a batch resource.","in":"path","name":"batch_id","required":true,"schema":{"description":"A unique identifier for a batch resource.","maxLength":255,"minLength":1,"pattern":"^\\w+$","title":"Batch Id","type":"string"}},{"description":"Providing this header and the value `gzip` yields results from the endpoint as gzipped plaintext with a base64 encoding.","in":"header","name":"accept-encoding","required":false,"schema":{"anyOf":[{"const":"gzip","type":"string"},{"type":"null"}],"description":"Providing this header and the value `gzip` yields results from the endpoint as gzipped plaintext with a base64 encoding.","title":"Accept-Encoding"}}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/RetrieveResultOutputItem"},"title":"Return","type":"array"}}},"description":"Returns the batch result."},"404":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Batch resource not found."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}},"description":"Request validation failed."}},"summary":"Retrieve a batch result","tags":["Batches"]}}}}
```

## Retrieve a batch status

> Retrieve the current status of a batch. The batch status relies on the individual status of all retrosynthesis jobs and can take longer to process. Poll the route with spaced requests compared to the individual retrosynthesis jobs.

```json
{"openapi":"3.1.0","info":{"title":"PAI Retro","version":"v2"},"tags":[{"description":"\nA high-throughput screening campaign for large-scale chemical libraries can be achieved\nthrough submitting *batches* of **Retrosynthesis** jobs with shared `parameters`. Pending\nAI offers batch sizes of up to 100000 jobs which can be created and then appended to with\nadditional API requests. Batch progress can be tracked with live updates to the number of\ncompleted jobs and a high-level screening overview can be retrieved.\n\nBatch synthesis jobs impact the overall queue size for a given engine. Larger batches may\nlead to a longer wait time for it to complete. Additional metadata data can also be added\nto the batch submission to help distinguish results beyond an arbitrary batch `id` field.\n\nSee [here](https://docs.pending.ai/capabilities/synthetic-accessibility)\nfor more information on our **Retrosynthesis** capability.\n                ","name":"Batches"}],"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":{"RetrieveStatusOutput":{"description":"Status information for a batch. Batches require routine polling\nto determine when all jobs have been completed. A batch will be\ncompleted once the `status` transitions to `completed` and the\n`number_of_jobs` matches the `completed_jobs`.","properties":{"completed_jobs":{"description":"The total number of jobs that have completed in the batch.","maximum":100000,"minimum":0,"title":"Completed Jobs","type":"integer"},"number_of_jobs":{"description":"The total number of jobs that have been submitted in the batch.","maximum":100000,"minimum":1,"title":"Number Of Jobs","type":"integer"},"status":{"description":"Current status of the batch.","enum":["submitted","processing","completed"],"title":"Status","type":"string"}},"required":["status","number_of_jobs","completed_jobs"],"title":"BatchStatus","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":{"/batches/{batch_id}/status":{"get":{"description":"Retrieve the current status of a batch. The batch status relies on the individual status of all retrosynthesis jobs and can take longer to process. Poll the route with spaced requests compared to the individual retrosynthesis jobs.","operationId":"retrieve_batch_status_batches__batch_id__status_get","parameters":[{"description":"A unique identifier for a batch resource.","in":"path","name":"batch_id","required":true,"schema":{"description":"A unique identifier for a batch resource.","maxLength":255,"minLength":1,"pattern":"^\\w+$","title":"Batch Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrieveStatusOutput"}}},"description":"Returns the batch status."},"404":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Batch resource not found."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestValidationErrorContent"}}},"description":"Request validation failed."}},"summary":"Retrieve a batch status","tags":["Batches"]}}}}
```


---

# 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/batch-screening.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.