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?

To get started with R, RStudio and RShiny, see also: Introduction to R, RStudio and RShiny - Create your own dashboards 

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. In the code below we store the credentials in environment variables. If you share your code with collaborators, you won't have to worry about removing your credentials before sharing the code. See here to see how you can create use environment variables.
    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