Protocol Data [GET]

GET /api/v1/vaults/<vault_id>/protocols/<id>/data

Returns (a subset of) the readout data for a single protocol.

Query Parameters (all optional):

 

async	Boolean If true, do an asynchronous export (see Async Export) Use for large data sets. This is recommended any time you want to download more than page_size results.	Note: any page_size parameter used in an API GET call that also uses the async=true parameter will be ignored. The GET call will return all valid data for the given GET call.
plates	Comma-separated list of plate ids	Include only data for the specified plates
molecules	Comma-separated list of molecule ids	Include only data for the specified molecules
runs_before	Date (YYYY-MM-DDThh:mm:ss±hh:mm)	Include only data for runs on or before the date (note: the full timestamp syntax should not be used with this parameter)
runs_after	Date (YYYY-MM-DDThh:mm:ss±hh:mm)	Include only data for runs on or after the date (note: the full timestamp syntax should not be used with this parameter)
runs	Comma-separated list of run ids for the given protocol	Include only data for runs listed
offset	The index of the first object actually returned. Defaults to 0.
page_size	The maximum number of objects to return in this call. Default is 50, maximum is 1000.	If the response exceeds the page_size, we strongly recommend using the async option instead of downloading multiple chunks. Note: any page_size parameter used in an API GET call that also uses the async=true parameter will be ignored. The GET call will return all valid data for the given GET call.
projects	Comma-separated list of project ids Defaults to all available projects Limits scope of query
format	csv	Generates a csv file which mimics the file generated when you choose the "Export readouts" button from the Run-level "Run Details" tab within the CDD Vault web interface
data_sets	Comma-separated list of public dataset ids Defaults to no data sets Limits scope of query

  

Notes on Using the Format Parameter

Using the “format=csv” parameter converts the API call into an async call so you must use the GET Exports API call to download the resulting csv file. The csv file is a report that includes exactly what you get via the application when you choose the "Export readouts" button from the Run-level "Run Details" tab within the CDD Vault web interface. So, data like the Control State and Z’ factor are included.

The only additional parameter allowed when you use the “format=csv” parameter is the “runs” parameter but if you do, you may only pass 1 run id.

GET /api/v1/vaults/<vault_id>/protocols/<id>/data?format=csv&runs=<run_id>

 

Notes on Date/Time Formats

The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like "created_after=2020-05-20".

You may also specify a date + timestamp, like "created_after= 2020-05-20 14:53:12", to indicate "20 May 2020 14:53:12 PDT" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like "created_after= 2020-05-27T14:48:40-07:00" which indicates that the time specified is -7 hours from the UTC time.

 

Notes on modifying rows of Protocol/Run/Readout data

The CDD Vault API also provides the ability to update/delete existing readout rows (including the ability to flag an existing readout row as an outlier) by using the GET Readout_Rows API function.

Example

To retrieve from protocol with ID 537677966 the data from plate ID 1, use:

curl -H "X-CDD-Token: $TOKEN" https://app.collaborativedrug.com/api/v1/vaults/489978881/protocols/537677966/data?plates=1

Returns:

{
  "count": 7,
  "offset": 0,
  "page_size": 50,
  "objects": [
  {
    "id": 1,
    "molecule": 1,
    "batch": 700861902,
    "run": 1,
    "well":
    {
      "row": 0,
      "col": 0,
      "plate": 1,
      "batch": 700861902
    },
    "readouts":
    {
      "1": 86.7,
      "3": 10.0
    }
  },
  {
    "id": 2,
    "molecule": 2,
    "batch": 787637732,
    "run": 2,
    "well":
    {
      "row": 0,
      "col": 1,
      "plate": 1,
      "batch": 787637732
    },
    "readouts":
    {
      "1": 133.7,
      "2": "insoluble",
      "3": 1.0
    }
  },
  {
    "id": 3,
    "molecule": 3,
    "batch": 618771089,
    "run": 2,
    "well":
    {
      "row": 0,
      "col": 2,
      "plate": 1,
      "batch": 618771089
    },
    "readouts":
    {
      "1": 123.4,
      "2": "amalgam turned bold red"
    }
  },
  {
    "id": 4,
    "molecule": 1,
    "batch": 700861902,
    "run": 2,
    "well":
    {
      "row": 0,
      "col": 3,
      "plate": 1,
      "batch": 700861902
    },
    "readouts":
    {
      "1": 1234.0
    }
  },
  {
    "id": 5,
    "molecule": 1,
    "batch": 700861902,
    "run": 2,
    "well":
    {
      "row": 0,
      "col": 10,
      "plate": 1,
      "batch": 700861902
    },
    "readouts":
    {
      "1": 18000.0
    }
  },
  {
    "id": 6,
    "molecule": 2,
    "batch": 787637732,
    "run": 2,
    "well":
    {
      "row": 1,
      "col": 1,
      "plate": 1,
      "batch": 787637732
    },
    "readouts":
    {
      "1": 114.0
    }
  },
  {
    "id": 7,
    "molecule": 1,
    "batch": 858251680,
    "run": 2,
    "well":
    {
      "row": 1,
      "col": 10,
      "plate": 1,
      "batch": 858251680
    },
    "readouts":
    {
      "1": 19340.0,
      "3": 10.0
    }
  } ]
}