Start a conversation

Using the Castor API R package for data analysis

You can use the Castor API R package to access study data in Castor via R.  Please note that the 'castoRedc' project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms. For a simple data export and/or study and report data  merge, see: How can I export and merge data in R?

Package Structure

There are three ways to access data through the API:

  1. Access to individual items (getStudyDataPoint, getStudy, getRecord, etc.)
  2. Access to pages of items in a list (getStudies, getRecords, etc.)
  3. Processed into a data frame for straightforward analysis (getStudyData)


# install.packages("remotes")


  1. Generate your Castor credentials, see: Application Programming Interface (API). Please note that the Client ID and Secret grant the same access to your data as your own username and password. Please treat them as such and do not hand them out to others (including us at Castor). We recommend reading about securely managing your credentials.
  2. Authenticate using your Castor credentials:
    castor_api <- CastorData$new(key = Sys.getenv("CASTOR_KEY"), 
                                 secret = Sys.getenv("CASTOR_SECRET"), 
                                 base_url = "")
  3. Get a list of the studies you have access to with:       
    studies <- castor_api$getStudies()
  4. Subsequently, get a study ID, for example:
    (example_study_id <- studies[["study_id"]][1])
    #> [1] "012A3A45-6ABB-7890-1234-567A8AB90A12"
  5. You can use the study ID to get the study's records, data, fields, steps, and phases, etc.      
    1. Get a list of records with:
      records <- castor_api$getRecords("YOUR_STUDY_ID")
    2. Get the study data with:
      studydata <- castor_api$getStudyData("YOUR_STUDY_ID")
    3. Get the report data with:
      reportdata <- castor_api$getReportInstancesBulk("YOUR_STUDY_ID")
    4. Get the fields with:
      fields <- castor_api$getFields("YOUR_STUDY_ID")
    5. Get the steps with:
      steps <- castor_api$getSteps("YOUR_STUDY_ID")
    6. Get the phases with:
      phases <- castor_api$getPhases("YOUR_STUDY_ID")
Choose files or drag and drop files
Was this article helpful?
  1. Castor Support Team

  2. Posted
  3. Updated