How to Export Study Data Using the API

soroosh · February 9, 2026, 3:12pm

This guide walks you through exporting your study data programmatically using Avicenna’s Data Export API. You can export both sensor data and survey responses, which is useful for automating data retrieval, integrating with external tools, or building custom data pipelines.

The Situation

You have an active study collecting sensor data and survey responses from participants. Instead of manually downloading exports through the Researcher Dashboard each time, you want to automate the process using API calls. For example, to regularly pull new data into your analysis pipeline or integrate with external tools.

What to Do?

Obtain your API key.
- Contact Avicenna Support to request an API key for your researcher account.
- Note your username (the email address associated with your Avicenna researcher account) and your API key.
- All API requests must include the following header:
```
Authorization: ApiKey USERNAME:API_KEY
```
[!note]
The API key must correspond to the username. Using a mismatched key will result in authentication failure.
Export sensor data.

To export raw data from data sources such as GPS, Accelerometer, Fitbit, or others, follow these three sub-steps:
- Create an export entry by sending a POST request to:
```
POST https://avicennaresearch.com/api/study/export/create/
```
  Include the following form fields:
  - study_id: The ID of your study.
  - data_source: The ID of the data source (see the Data Source ID Reference.
  - start_date: Start time in milliseconds (UTC).
  - end_date: End time in milliseconds (UTC).
  - participant_ids: A comma-separated list of participant IDs (AIDs).
  Example:
```
curl 'https://avicennaresearch.com/api/study/export/create/' \
    -H 'Authorization: ApiKey foo@avicennaresearch.com:44e55475e9b1010eab5e' \
    -F "study_id=1234" \
    -F "data_source=99" \
    -F "start_date=1744662600000" \
    -F "end_date=1738873800000" \
    -F "participant_ids=1,2,3"
```
- Check the export status by sending a GET request to:
```
GET https://avicennaresearch.com/api/v1/filter/export/?study_id=STUDY_ID
```
  When the status.label field becomes Success, the content field will contain a download URL.
- Download the export file using the URL from the content field:
```
curl -O 'DOWNLOAD_URL' -H 'Authorization: ApiKey USERNAME:API_KEY'
```
[!note]
Each data export is available for download for up to 7 days. After that, Avicenna automatically deletes the file. If you need the data again, you must create a new export.
Export survey responses.

To export responses from Survey activities with advanced filtering and column selection, send a POST request to:
```
POST https://avicennaresearch.com/api/v1/filter/export/
```
The request body should be a JSON object with the following fields:
- study_id: The ID of your study.
- activity_id: The ID of the Survey activity. This must be a published Survey activity.
- filter: Set to "ACTIVITY_RESPONSE".
- site_ssid: Optional. Use null for all sites.
- export_version: Use "v2" for the recommended format.
- rule_set: A JSON object defining columns, filters, and sort order.
Example:
```
curl -X POST https://avicennaresearch.com/api/v1/filter/export/ \
    -H "Authorization: ApiKey YOUR_USERNAME:YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "study_id": STUDY_ID,
        "site_ssid": null,
        "filter": "ACTIVITY_RESPONSE",
        "rule_set": {
            "columns": [
                "Q2", "Q3", "uuid", "prompt_time", "record_time",
                "status_id", "device.id", "device.model",
                "participant.start_time", "participant.status_id"
            ],
            "query": {
                "AND": [
                    {"field_name": "participant.status_id", "op": "=", "value": 1}
                ]
            },
            "sort_by": [
                {"field_name": "session.uuid", "sort_order": "asc"}
            ]
        },
        "activity_id": ACTIVITY_ID,
        "export_version": "v2"
    }'
```
- The columns array controls which fields appear in the exported CSV, including session fields (uuid, prompt_time, record_time), device fields (device.id, device.model), participant fields (participant.start_time, participant.status_id), and survey question responses (Q2, Q3, etc.).
- The query object filters results using conditions with operators like =, !=, >, >=, <, <=, in, not_in, contains, starts_with, and more. You can nest AND and OR groups for complex filters.
- The sort_by array controls the row ordering in the exported CSV.
[!note]
When using export version v2, selecting Q{n} automatically includes a corresponding metadata column named mQ{n}_metadata.
Monitor and download your survey export.
- Use the same status endpoint from step 2 to check when your survey export is ready:
```
GET https://avicennaresearch.com/api/v1/filter/export/?study_id=STUDY_ID
```
- Once the status shows Success, download the file from the content URL:
```
curl -O 'DOWNLOAD_URL' -H 'Authorization: ApiKey USERNAME:API_KEY'
```

Pro Tip

For large studies, break your sensor data exports into smaller requests by reducing the date range or the number of participants per request. This helps avoid long processing times and timeouts. You can also automate the entire workflow — create, poll, and download — using a simple script that runs on a schedule to keep your data pipeline up to date.