Batch Screening

Screen large batches of molecules using our high-throughput retrosynthesis

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 for more information on our Retrosynthesis capability.

List batches

get

Retrieve a list of batches.

Required scopes

This endpoint requires the following scopes:

Authorizations

oauth & token

OAuth2implicitRequired

OAuth2 authentication.

Authorization URL: Refresh URL:

AuthorizationstringRequired

Provide a valid Pending AI authentication token. Generating tokens can be done through the Pending AI CLI. Ensure you have an existing account or register for a new one.

pending auth login
pendingai auth token

Query parameters

created-beforeany ofOptional

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.

Example: bat_32ALvrkANBUzVixmK2J2BrApeyc

string · min: 1 · max: 255OptionalPattern: ^\w+$

or

nullOptional

created-afterany ofOptional

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.

Example: bat_32ALvrkANBUzVixmK2J2BrApeyc

string · min: 1 · max: 255OptionalPattern: ^\w+$

or

nullOptional

sizeinteger · min: 1 · max: 100Optional

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.

Default: 50Example: 50

Responses

200

Returns a list of batches.

application/json

has_morebooleanRequired

A boolean flag that indicates whether there are more items available to be fetched on subsequent pages. Used for pagination control.

objectstringOptional

The type of resource.

Default: listPattern: ^\w+$

422

Request validation failed.

application/json

get

/batches

HTTPcURLJavaScriptPython

GET /retro/v2/batches HTTP/1.1
Host: api.pending.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": [
    {
      "created": "2000-01-01T00:00:00Z",
      "description": "Screening of targets for inhibitor 42.",
      "filename": "experiment_042_smi",
      "id": "id_32ALvrkANBUzVixmK2J2BrApeyc",
      "name": "experiment_042",
      "number_of_jobs": 100,
      "object": "object",
      "parameters": {
        "building_block_libraries": [
          "lib_32ALvrkANBUzVixmK2J2BrApeyc"
        ],
        "building_block_limit": 3,
        "number_of_routes": 25,
        "processing_time": 300,
        "reaction_limit": 3,
        "retrosynthesis_engine": "eng_32ALvrkANBUzVixmK2J2BrApeyc"
      },
      "updated": "2000-01-01T00:00:00Z"
    }
  ],
  "has_more": true,
  "object": "list"
}

Create a batch

post

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.

Required scopes

This endpoint requires the following scopes:

Authorizations

oauth & token

OAuth2implicitRequired

OAuth2 authentication.

Authorization URL: Refresh URL:

AuthorizationstringRequired

Provide a valid Pending AI authentication token. Generating tokens can be done through the Pending AI CLI. Ensure you have an existing account or register for a new one.

pending auth login
pendingai auth token

Body

application/json

Request data for creating a new batch.

descriptionany ofOptional

An optional name for the batch. The name provides a human- readable identifier for the batch and is not required to be unique.

string · max: 2048Optional

or

nullOptional

filenameany ofOptional

An optional filename to help identify the batch and ideal for when a batch is submitted via file.

string · max: 2048Optional

or

nullOptional

nameany ofOptional

An optional name for the batch. The name provides a human- readable identifier for the batch and is not required to be unique.

string · max: 128Optional

or

nullOptional

smilesstring[] · min: 1 · max: 100000Required

A collection of target molecules in a SMILES format to perform retrosynthesis on. Each structure is submitted as an individual job and queued separately.

NOTE: Duplicate structures are removed automatically.

Example: ["CC(=O)OCC","CCN(CC)CC"]

Responses

200

Returns the batch.

application/json

Batches are collections of retrosynthesis jobs that share a common set of parameters. Batches allow for easy management of large sets of synthesis targets and provide a mechanism for tracking the status of multiple jobs as a single entity.

There is an upper limit of 100,000 jobs per batch which requires any further jobs to be submitted in a new batch. Multiple identifiers can be used to distinguish between them.

createdstring · date-timeOptional

Timestamp for when the batch was created.

Example: 2000-01-01T00:00:00Z

descriptionany ofOptional

An optional description for the batch. The description provides additional context about the batch to help with distinguishing between other batches.

Example: Screening of targets for inhibitor 42.

string · max: 2048OptionalPattern: ^[\w\s\-\:]*$

or

nullOptional

filenameany ofOptional

An optional filename to help identify the batch and ideal for when a batch is submitted via file.

Example: experiment_042_smi

string · max: 2048OptionalPattern: ^[\w\-\:]*$

or

nullOptional

idstringRequired

The unique resource identifier.

Example: id_32ALvrkANBUzVixmK2J2BrApeycPattern: ^\w+$

nameany ofOptional

An optional name for the batch. The name provides a human-readable identifier for the batch and is not required to be unique.

Example: experiment_042

string · max: 256OptionalPattern: ^[\w\s\-\:]*$

or

nullOptional

number_of_jobsinteger · min: 1 · max: 100000Required

Total number of retrosynthesis jobs that belong to a batch. The value can change over time as new jobs are added to the batch.

Example: 100

objectstringRequired

The type of resource.

Example: objectPattern: ^\w+$

updatedstring · date-timeOptional

Timestamp for when the batch was last updated.

Example: 2000-01-01T00:00:00Z

402

Payment gateway failed.

application/json

413

Batch resource exceeded size limit.

application/json

422

Request validation failed.

application/json

post

/batches

HTTPcURLJavaScriptPython

POST /retro/v2/batches HTTP/1.1
Host: api.pending.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 313

{
  "description": "text",
  "filename": "text",
  "name": "text",
  "parameters": {
    "building_block_libraries": [
      "lib_32ALvrkANBUzVixmK2J2BrApeyc"
    ],
    "building_block_limit": 3,
    "number_of_routes": 25,
    "processing_time": 300,
    "reaction_limit": 3,
    "retrosynthesis_engine": "eng_32ALvrkANBUzVixmK2J2BrApeyc"
  },
  "smiles": [
    "CC(=O)OCC",
    "CCN(CC)CC"
  ]
}

{
  "created": "2000-01-01T00:00:00Z",
  "description": "Screening of targets for inhibitor 42.",
  "filename": "experiment_042_smi",
  "id": "id_32ALvrkANBUzVixmK2J2BrApeyc",
  "name": "experiment_042",
  "number_of_jobs": 100,
  "object": "object",
  "parameters": {
    "building_block_libraries": [
      "lib_32ALvrkANBUzVixmK2J2BrApeyc"
    ],
    "building_block_limit": 3,
    "number_of_routes": 25,
    "processing_time": 300,
    "reaction_limit": 3,
    "retrosynthesis_engine": "eng_32ALvrkANBUzVixmK2J2BrApeyc"
  },
  "updated": "2000-01-01T00:00:00Z"
}

Retrieve a batch

get

Retrieve a batch with attached metadata and job parameters.

Required scopes

This endpoint requires the following scopes:

Authorizations

oauth & token

OAuth2implicitRequired

OAuth2 authentication.

Authorization URL: Refresh URL:

AuthorizationstringRequired

Provide a valid Pending AI authentication token. Generating tokens can be done through the Pending AI CLI. Ensure you have an existing account or register for a new one.

pending auth login
pendingai auth token

Path parameters

batch_idstring · min: 1 · max: 255Required

A unique identifier for a batch resource.

Example: bat_32ALvrkANBUzVixmK2J2BrApeycPattern: ^\w+$

Responses

200

Returns the batch.

application/json

Batches are collections of retrosynthesis jobs that share a common set of parameters. Batches allow for easy management of large sets of synthesis targets and provide a mechanism for tracking the status of multiple jobs as a single entity.

There is an upper limit of 100,000 jobs per batch which requires any further jobs to be submitted in a new batch. Multiple identifiers can be used to distinguish between them.

createdstring · date-timeOptional

Timestamp for when the batch was created.

Example: 2000-01-01T00:00:00Z

descriptionany ofOptional

An optional description for the batch. The description provides additional context about the batch to help with distinguishing between other batches.

Example: Screening of targets for inhibitor 42.

string · max: 2048OptionalPattern: ^[\w\s\-\:]*$

or

nullOptional

filenameany ofOptional

An optional filename to help identify the batch and ideal for when a batch is submitted via file.

Example: experiment_042_smi

string · max: 2048OptionalPattern: ^[\w\-\:]*$

or

nullOptional

idstringRequired

The unique resource identifier.

Example: id_32ALvrkANBUzVixmK2J2BrApeycPattern: ^\w+$

nameany ofOptional

An optional name for the batch. The name provides a human-readable identifier for the batch and is not required to be unique.

Example: experiment_042

string · max: 256OptionalPattern: ^[\w\s\-\:]*$

or

nullOptional

number_of_jobsinteger · min: 1 · max: 100000Required

Total number of retrosynthesis jobs that belong to a batch. The value can change over time as new jobs are added to the batch.

Example: 100

objectstringRequired

The type of resource.

Example: objectPattern: ^\w+$

updatedstring · date-timeOptional

Timestamp for when the batch was last updated.

Example: 2000-01-01T00:00:00Z

404

Batch resource not found.

application/json

422

Request validation failed.

application/json

get

/batches/{batch_id}

HTTPcURLJavaScriptPython

GET /retro/v2/batches/{batch_id} HTTP/1.1
Host: api.pending.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "created": "2000-01-01T00:00:00Z",
  "description": "Screening of targets for inhibitor 42.",
  "filename": "experiment_042_smi",
  "id": "id_32ALvrkANBUzVixmK2J2BrApeyc",
  "name": "experiment_042",
  "number_of_jobs": 100,
  "object": "object",
  "parameters": {
    "building_block_libraries": [
      "lib_32ALvrkANBUzVixmK2J2BrApeyc"
    ],
    "building_block_limit": 3,
    "number_of_routes": 25,
    "processing_time": 300,
    "reaction_limit": 3,
    "retrosynthesis_engine": "eng_32ALvrkANBUzVixmK2J2BrApeyc"
  },
  "updated": "2000-01-01T00:00:00Z"
}

Update a batch

put

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.

Required scopes

This endpoint requires the following scopes:

Authorizations

oauth & token

OAuth2implicitRequired

OAuth2 authentication.

Authorization URL: Refresh URL:

AuthorizationstringRequired

Provide a valid Pending AI authentication token. Generating tokens can be done through the Pending AI CLI. Ensure you have an existing account or register for a new one.

pending auth login
pendingai auth token

Path parameters

batch_idstring · min: 1 · max: 255Required

A unique identifier for a batch resource.

Example: bat_32ALvrkANBUzVixmK2J2BrApeycPattern: ^\w+$

Body

application/json

Request data for updating an existing batch.

smilesstring[] · min: 1 · max: 100000Required

A collection of target molecules in a SMILES format to perform retrosynthesis on. Each structure is submitted as an individual job and queued separately.

NOTE: Duplicate structures are removed automatically.

Example: ["CC(=O)OCC","CCN(CC)CC"]

Responses

200

Returns the updated batch.

application/json

Batches are collections of retrosynthesis jobs that share a common set of parameters. Batches allow for easy management of large sets of synthesis targets and provide a mechanism for tracking the status of multiple jobs as a single entity.

There is an upper limit of 100,000 jobs per batch which requires any further jobs to be submitted in a new batch. Multiple identifiers can be used to distinguish between them.

createdstring · date-timeOptional

Timestamp for when the batch was created.

Example: 2000-01-01T00:00:00Z

descriptionany ofOptional

An optional description for the batch. The description provides additional context about the batch to help with distinguishing between other batches.

Example: Screening of targets for inhibitor 42.

string · max: 2048OptionalPattern: ^[\w\s\-\:]*$

or

nullOptional

filenameany ofOptional

An optional filename to help identify the batch and ideal for when a batch is submitted via file.

Example: experiment_042_smi

string · max: 2048OptionalPattern: ^[\w\-\:]*$

or

nullOptional

idstringRequired

The unique resource identifier.

Example: id_32ALvrkANBUzVixmK2J2BrApeycPattern: ^\w+$

nameany ofOptional

An optional name for the batch. The name provides a human-readable identifier for the batch and is not required to be unique.

Example: experiment_042

string · max: 256OptionalPattern: ^[\w\s\-\:]*$

or

nullOptional

number_of_jobsinteger · min: 1 · max: 100000Required

Total number of retrosynthesis jobs that belong to a batch. The value can change over time as new jobs are added to the batch.

Example: 100

objectstringRequired

The type of resource.

Example: objectPattern: ^\w+$

updatedstring · date-timeOptional

Timestamp for when the batch was last updated.

Example: 2000-01-01T00:00:00Z

402

Payment gateway failed.

application/json

404

Batch resource not found.

application/json

413

Batch resource exceeded size limit.

application/json

422

Request validation failed.

application/json

put

/batches/{batch_id}

HTTPcURLJavaScriptPython

PUT /retro/v2/batches/{batch_id} HTTP/1.1
Host: api.pending.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 36

{
  "smiles": [
    "CC(=O)OCC",
    "CCN(CC)CC"
  ]
}

{
  "created": "2000-01-01T00:00:00Z",
  "description": "Screening of targets for inhibitor 42.",
  "filename": "experiment_042_smi",
  "id": "id_32ALvrkANBUzVixmK2J2BrApeyc",
  "name": "experiment_042",
  "number_of_jobs": 100,
  "object": "object",
  "parameters": {
    "building_block_libraries": [
      "lib_32ALvrkANBUzVixmK2J2BrApeyc"
    ],
    "building_block_limit": 3,
    "number_of_routes": 25,
    "processing_time": 300,
    "reaction_limit": 3,
    "retrosynthesis_engine": "eng_32ALvrkANBUzVixmK2J2BrApeyc"
  },
  "updated": "2000-01-01T00:00:00Z"
}

Delete a batch

delete

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.

Required scopes

This endpoint requires the following scopes:

Authorizations

oauth & token

OAuth2implicitRequired

OAuth2 authentication.

Authorization URL: Refresh URL:

AuthorizationstringRequired

Provide a valid Pending AI authentication token. Generating tokens can be done through the Pending AI CLI. Ensure you have an existing account or register for a new one.

pending auth login
pendingai auth token

Path parameters

batch_idstring · min: 1 · max: 255Required

A unique identifier for a batch resource.

Example: bat_32ALvrkANBUzVixmK2J2BrApeycPattern: ^\w+$

Responses

200

Returns the deleted batch.

application/json

Batches are collections of retrosynthesis jobs that share a common set of parameters. Batches allow for easy management of large sets of synthesis targets and provide a mechanism for tracking the status of multiple jobs as a single entity.

There is an upper limit of 100,000 jobs per batch which requires any further jobs to be submitted in a new batch. Multiple identifiers can be used to distinguish between them.

createdstring · date-timeOptional

Timestamp for when the batch was created.

Example: 2000-01-01T00:00:00Z

descriptionany ofOptional

An optional description for the batch. The description provides additional context about the batch to help with distinguishing between other batches.

Example: Screening of targets for inhibitor 42.

string · max: 2048OptionalPattern: ^[\w\s\-\:]*$

or

nullOptional

filenameany ofOptional

An optional filename to help identify the batch and ideal for when a batch is submitted via file.

Example: experiment_042_smi

string · max: 2048OptionalPattern: ^[\w\-\:]*$

or

nullOptional

idstringRequired

The unique resource identifier.

Example: id_32ALvrkANBUzVixmK2J2BrApeycPattern: ^\w+$

nameany ofOptional

An optional name for the batch. The name provides a human-readable identifier for the batch and is not required to be unique.

Example: experiment_042

string · max: 256OptionalPattern: ^[\w\s\-\:]*$

or

nullOptional

number_of_jobsinteger · min: 1 · max: 100000Required

Total number of retrosynthesis jobs that belong to a batch. The value can change over time as new jobs are added to the batch.

Example: 100

objectstringRequired

The type of resource.

Example: objectPattern: ^\w+$

updatedstring · date-timeOptional

Timestamp for when the batch was last updated.

Example: 2000-01-01T00:00:00Z

402

Payment gateway failed.

application/json

404

Batch resource not found.

application/json

422

Request validation failed.

application/json

delete

/batches/{batch_id}

HTTPcURLJavaScriptPython

DELETE /retro/v2/batches/{batch_id} HTTP/1.1
Host: api.pending.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "created": "2000-01-01T00:00:00Z",
  "description": "Screening of targets for inhibitor 42.",
  "filename": "experiment_042_smi",
  "id": "id_32ALvrkANBUzVixmK2J2BrApeyc",
  "name": "experiment_042",
  "number_of_jobs": 100,
  "object": "object",
  "parameters": {
    "building_block_libraries": [
      "lib_32ALvrkANBUzVixmK2J2BrApeyc"
    ],
    "building_block_limit": 3,
    "number_of_routes": 25,
    "processing_time": 300,
    "reaction_limit": 3,
    "retrosynthesis_engine": "eng_32ALvrkANBUzVixmK2J2BrApeyc"
  },
  "updated": "2000-01-01T00:00:00Z"
}

Retrieve a batch result

get

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

Required scopes

This endpoint requires the following scopes:

Authorizations

oauth & token

OAuth2implicitRequired

OAuth2 authentication.

Authorization URL: Refresh URL:

AuthorizationstringRequired

Provide a valid Pending AI authentication token. Generating tokens can be done through the Pending AI CLI. Ensure you have an existing account or register for a new one.

pending auth login
pendingai auth token

Path parameters

batch_idstring · min: 1 · max: 255Required

A unique identifier for a batch resource.

Example: bat_32ALvrkANBUzVixmK2J2BrApeycPattern: ^\w+$

Header parameters

accept-encodingany ofOptional

Providing this header and the value gzip yields results from the endpoint as gzipped plaintext with a base64 encoding.

const: gzipOptional

or

nullOptional

Responses

200

Returns the batch result.

application/json

Summary result for an individual job in a batch. Provides an overview of the job status and if any retrosynthesis results were found.

completedbooleanRequired

A flag to indicate if the job is completed. Results retrieved before a batch has completed may contain incomplete jobs.

job_idstringRequired

A unique identifier for the retrosynthesis job. The value can be used to retrieve the full job resource with any results.

Example: job_32ALvrkANBUzVixmK2J2BrApeycPattern: ^\w+$

smilesstringRequired

The retrosynthesis target structure in a SMILES format.

Example: CC(=O)OCCPattern: ^[a-zA-Z0-9\(\)+-=#%+@\/\\\[\]\*]+$

synthesizablebooleanRequired

A flag to indicate if the structure is synthesizable. A structure is considered synthesizable if at least one synthesis route was found during retrosynthesis.

404

Batch resource not found.

application/json

422

Request validation failed.

application/json

get

/batches/{batch_id}/result

HTTPcURLJavaScriptPython

GET /retro/v2/batches/{batch_id}/result HTTP/1.1
Host: api.pending.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "completed": true,
    "job_id": "job_32ALvrkANBUzVixmK2J2BrApeyc",
    "smiles": "CC(=O)OCC",
    "synthesizable": true
  }
]

Retrieve a batch status

get

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.

Required scopes

This endpoint requires the following scopes:

Authorizations

oauth & token

OAuth2implicitRequired

OAuth2 authentication.

Authorization URL: Refresh URL:

AuthorizationstringRequired

Provide a valid Pending AI authentication token. Generating tokens can be done through the Pending AI CLI. Ensure you have an existing account or register for a new one.

pending auth login
pendingai auth token

Path parameters

batch_idstring · min: 1 · max: 255Required

A unique identifier for a batch resource.

Example: bat_32ALvrkANBUzVixmK2J2BrApeycPattern: ^\w+$

Responses

200

Returns the batch status.

application/json

Status information for a batch. Batches require routine polling to determine when all jobs have been completed. A batch will be completed once the status transitions to completed and the number_of_jobs matches the completed_jobs.

completed_jobsinteger · max: 100000Required

The total number of jobs that have completed in the batch.

number_of_jobsinteger · min: 1 · max: 100000Required

The total number of jobs that have been submitted in the batch.

statusstring · enumRequired

Current status of the batch.

Possible values:

404

Batch resource not found.

application/json

422

Request validation failed.

application/json

get

/batches/{batch_id}/status

HTTPcURLJavaScriptPython

GET /retro/v2/batches/{batch_id}/status HTTP/1.1
Host: api.pending.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "completed_jobs": 1,
  "number_of_jobs": 1,
  "status": "submitted"
}