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

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

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

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

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

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

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

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