Skip to content

Export Metadata

Export Metadata (Data Dictionary) API

Article ID RC-API-07 — Export Metadata (Data Dictionary) API
Domain API
Applies To All REDCap projects
Prerequisite RC-API-01 — REDCap API
Version 1.1
Last Updated 2026
Author See KB-SOURCE-ATTESTATION.md
Source REDCap API v16.1.3 official documentation examples
Related Topics RC-API-01 — REDCap API; RC-API-06 — Export Field Names API; RC-API-08 — Import Metadata (Data Dictionary) API

1. Overview

The Export Metadata API method retrieves the complete data dictionary (metadata) for a REDCap project. The data dictionary defines the structure of your project — all fields, instruments, field types, validation rules, branching logic, and other configuration details. This is the most comprehensive way to programmatically understand your project's structure.

When to use this method: When you need to understand the complete structure of a project, document the data dictionary, migrate a project, validate field configurations, or programmatically access field labels, validation rules, and other metadata attributes.

2. Parameters

Parameter Required Description
token Required Your project API token. Requires API Export right.
content Required Always 'metadata' for this method.
format Required Response format: 'csv', 'json', or 'xml' (default).
fields Optional Array of field names to pull. By default, all fields are returned.
forms Optional Array of form names (unique instrument names from Column B of the data dictionary — not the display labels) to pull. By default, all forms are returned.
returnFormat Optional Format for error messages: 'csv', 'json', or 'xml'. Defaults to match format if omitted; defaults to 'xml' if neither is passed. Does not apply when using a background process.

3. Request Examples

3.1 Python

#!/usr/bin/env python

from config import config
import requests

fields = {
    'token': config['api_token'],
    'content': 'metadata',
    'format': 'json'
}

r = requests.post(config['api_url'],data=fields)
print('HTTP Status: ' + str(r.status_code))
print(r.text)

3.2 R

#!/usr/bin/env Rscript

source('config.R')
library(RCurl)

result <- postForm(
    api_url,
    token=api_token,
    content='metadata',
    format='json'
)
print(result)

3.3 cURL

#!/bin/sh

. ./config

DATA="token=$API_TOKEN&content=metadata&format=json"

$CURL -H "Content-Type: application/x-www-form-urlencoded" \
      -H "Accept: application/json" \
      -X POST \
      -d $DATA \
      $API_URL

3.4 PHP

<?php

include 'config.php';

$fields = array(
    'token'   => $GLOBALS['api_token'],
    'content' => 'metadata',
    'format'  => 'json'
);

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $GLOBALS['api_url']);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($fields, '', '&'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE); // Set to TRUE for production use
curl_setopt($ch, CURLOPT_VERBOSE, 0);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($ch, CURLOPT_AUTOREFERER, true);
curl_setopt($ch, CURLOPT_MAXREDIRS, 10);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_FRESH_CONNECT, 1);

$output = curl_exec($ch);
print $output;
?>

Note: In PHP examples, CURLOPT_SSL_VERIFYPEER is shown as FALSE for compatibility. Set it to TRUE in production. See RC-API-01 — REDCap API for why SSL certificate validation matters.

4. Response

The method returns the complete data dictionary in the requested format. Each row represents one field definition. The response includes all Data Dictionary columns such as field name, form name, field type, field label, validation rules, branching logic, and more.

JSON format (excerpt):

[
  {
    "field_name": "record_id",
    "form_name": "demographics",
    "section_header": "",
    "field_type": "text",
    "field_label": "Record ID",
    "select_choices_or_calculations": "",
    "field_note": "",
    "text_validation_type_or_show_slider_number": "",
    "text_validation_min": "",
    "text_validation_max": "",
    "identifier": "y",
    "branching_logic": "",
    "required_field": "y",
    "custom_alignment": "",
    "question_number": "",
    "matrix_group_name": "",
    "matrix_ranking": "",
    "field_annotation": ""
  },
  {
    "field_name": "first_name",
    "form_name": "demographics",
    "section_header": "",
    "field_type": "text",
    "field_label": "First Name",
    "select_choices_or_calculations": "",
    "field_note": "",
    "text_validation_type_or_show_slider_number": "",
    "text_validation_min": "",
    "text_validation_max": "",
    "identifier": "",
    "branching_logic": "",
    "required_field": "",
    "custom_alignment": "",
    "question_number": "",
    "matrix_group_name": "",
    "matrix_ranking": "",
    "field_annotation": ""
  }
]

CSV format: The response is the raw data dictionary CSV with all standard columns.

5. Common Questions

Q: What's included in the metadata response?

A: The response includes all columns from the Data Dictionary: field_name, form_name, section_header, field_type, field_label, select_choices_or_calculations, field_note, text_validation rules, identifier, branching_logic, required_field, custom_alignment, question_number, matrix settings, and field_annotation.

Q: Can I export metadata for only certain instruments or fields?

A: Yes. Use the optional forms parameter to pass an array of instrument names, and/or the fields parameter to pass an array of field names. Only the matching metadata will be returned. Note that forms takes the unique instrument name (Column B of the data dictionary), not the display label you see in the UI.

Q: What format is best for metadata export?

A: JSON is easiest to parse programmatically and preserves structure. CSV is the native REDCap format and can be imported back (see RC-API-08 — Import Metadata (Data Dictionary) API). XML works but is more verbose.

Q: Does the metadata include calculated fields and matrices?

A: Yes, all field types are included: text, choice, calculated, checkbox, radio, matrix, file upload, and custom fields. All field properties are returned.

Q: Can I use this to audit project structure changes?

A: Yes. By periodically exporting metadata and comparing versions, you can track when fields, forms, or validation rules change. This is useful for data governance and compliance auditing.

Q: Does the metadata include project-level settings?

A: No. This method returns only field and instrument definitions. To get project settings (title, purpose, etc.), use other metadata endpoints. See RC-API-01 — REDCap API for additional project-level API methods.

6. Common Mistakes & Gotchas

Passing the form display label instead of the form name in the forms parameter. The forms parameter takes the unique instrument name as it appears in Column B of the data dictionary (e.g., baseline_survey), not the human-readable label shown in the UI (e.g., Baseline Survey). Passing the label will return no results without an error.

Assuming metadata is lightweight. For large projects with hundreds of fields and instruments, the metadata response can be large (megabytes). Plan accordingly in your code, especially for network-constrained environments.

Not properly handling the JSON structure. The JSON response is an array of objects, not a single object. Each field is a separate object in the array. Always iterate through the array.

Missing field properties. Some optional field properties may be empty strings in the response. Don't assume all fields have values for all columns. Use defensive programming to check for empty values.

Forgetting to update on project changes. Metadata is static at the time you request it. If fields are added or modified after you export, your local copy is outdated. If you need fresh data, re-export.

Using metadata for data validation without refreshing. If you use exported metadata to validate incoming data (e.g., checking which fields are required), be aware that project structure may change. Refresh metadata periodically in production systems.