Protocol Data [GET] – CDD Support

DEPRECATION WARNING

This GET Protocol Data API endpoint is deprecated.

Instead, please use GET Readout_Rows to return readout data for any number of Protocols in an almost identical format. This new endpoint is faster, supports more options, and avoids the need to de-duplicate data. Please contact support if you would like help migrating to the new endpoint.

One of the main benefits is that the aggregate data is no longer repeated for every detail row (input data), but is presented separately for easier machine parsing and speed. Using the "type" parameter, a subset of readout data types can be returned.

This GET Readout_Rows API call also allows the retrieval of data across multiple Protocols via 1 API call.

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-DD)	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-DD)	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 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 PUT 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
    }
  } ]
}