Running Your Study

When your study design is ready, publishing creates an immutable version that participants can access:

1. Validate — Click the "Validate" button in the builder toolbar. Fix any errors (red). Warnings are recommended but not required.
2. Publish — Click the "Publish" button. This creates a new published version with a version number.
3. What happens: The published version is frozen — it cannot be edited. Your draft automatically increments to the next version and remains editable for future changes.
4. Why immutable? — Immutability ensures that every participant who starts a published version completes the exact same study. This is critical for controlled experiments.

After publishing, you need to create an invitation to let participants access your study.

After publishing, create invitations to control participant access:

1. Create an invitation — Go to the study's invitation settings and create a new access code.
2. Configure limits:
   • Max participants — Set a cap on how many participants can join through this code
   • Source label — Tag invitations by recruitment source (e.g., "Prolific", "MTurk", "Lab")
   • Stale participant hours — Automatically flag inactive sessions after a set period
3. Share the link — Each invitation generates a unique join link. Share this with your participants.
4. Multiple invitations — Create separate invitations for different recruitment batches or sources. Each tracks its own participant count.

Participants join by visiting the link, entering any required identifiers, and proceeding through the study.

The Participants tab in the dashboard provides a real-time view of all participant activity:

Episode tracking — Each participant session is an "episode" with a status:

• In progress — Participant is currently going through the study
• Completed — Participant has finished the entire study
• Terminated — Session was ended early (timeout, error, or manual stop)

What you can see:

• Current position in the study flow (which node they're on)
• Start time and completion time
• Full event log with timestamps
• All variable values (dataStore) at any point in the session
• Chat transcripts and survey responses

Session replay — Walk through a participant's journey step by step, seeing exactly what they saw and how they responded.

Studies support a versioning workflow for iterative improvement:

• Each study has a lineage ID that stays constant across all versions
• Publishing increments the version number (v1, v2, v3...)
• Published versions are immutable — participants on v1 stay on v1
• The draft is always the next version, ready for editing
• You can have only one published version active at a time — publishing a new version automatically replaces the old one for new participants
• Existing participants continue on the version they started

This design lets you iterate on your study design while maintaining the integrity of in-progress sessions.

Gricea supports open science through its community features:

Making a study public — Go to study settings and toggle visibility. Public studies appear in the Community gallery where other researchers can:

• View your study design and methodology
• Use your study as a template (fork it)
• See your research paper link and description

Data visibility controls:

• isPublic — Whether the study design is visible in the Community
• isDataPublic — Whether raw participant data is accessible
• isAggregatePublic — Whether aggregate statistics are shared

You control what gets shared. You can make the study design public while keeping all data private, or share aggregate results without raw data.

By default, Gricea uses a shared OpenAI API key. For production studies, you can bring your own:

API Key Hierarchy (checked in order):

1. Study-level key — Set on a specific study for dedicated billing
2. Organization-level key — Set in your API Keys dashboard for all studies
3. Platform default — Falls back to the shared platform key

Setting up:

1. Go to API Keys in the dashboard sidebar
2. Enter your OpenAI API key
3. Click "Test" to verify the key works
4. Save — the key is encrypted before storage

Your key is stored encrypted and never exposed in the client. You can also override the key at the study level for specific experiments.

For researchers who need data in their own infrastructure, Gricea supports external MongoDB databases:

Setup:

1. Open study settings
2. Enter your MongoDB connection URI and database name
3. Click "Test Connection" to verify
4. Save — the URI is encrypted before storage

How it works:

• When configured, participant data (events and episode records) is written to your external database instead of the platform database
• The connection URI is encrypted using server-side encryption
• You maintain full control over your data and can query it directly

Use cases:

• Institutional data governance requirements
• Custom analytics pipelines
• Large-scale studies needing dedicated database resources
• Data sovereignty compliance