# FAQs
Source: https://docs.usefusion.ai/FAQs

Frequently asked questions about NeuroFusion.

## General

<AccordionGroup>
  <Accordion title="What is NeuroFusion?">
    NeuroFusion is a research platform for designing studies, collecting behavioral and brain data, and analyzing results. It supports prompts (recurring surveys), jsPsych experiments, wearable integrations, and EEG recordings — all managed through organizations with built-in billing.
  </Accordion>

  <Accordion title="Who is NeuroFusion for?">
    Researchers, clinicians, and study administrators in cognitive neuroscience, behavioral science, psychology, health research, education, and social sciences.
  </Accordion>

  <Accordion title="Is NeuroFusion free?">
    Signing up and creating organizations is free. New organizations receive bonus starter credits. Certain actions — publishing quests, participant joins, data submissions — consume credits. See [Billing & Credits](/billing/overview) and the [Pricing page](https://usefusion.ai/pricing) for details.
  </Accordion>
</AccordionGroup>

## Prompts

<AccordionGroup>
  <Accordion title="What response types are available for prompts?">
    There are 5 response types: **Yes/No**, **Text**, **Number**, **Number Range** (with configurable min/max), and **Custom Options** (semicolon-separated, single or multi-select). See [Response Types](/prompts/response-types) for details.
  </Accordion>

  <Accordion title="How do I schedule prompts?">
    Each prompt has three scheduling dimensions: **active days** (which days of the week), **time window** (start and end time, defaults 8 AM–10 PM), and **frequency** (once, every 30 min, hourly, every 2/3/4 hours). See [Scheduling](/prompts/scheduling).
  </Accordion>

  <Accordion title="What are conditional notifications?">
    You can configure a prompt to only send notifications if a participant's answer to a previous prompt or onboarding question meets a condition. For example, "Only ask about caffeine if they reported poor sleep." See [Conditional Notifications](/prompts/conditional-notifications).
  </Accordion>

  <Accordion title="How many prompts can a quest have?">
    There is no hard limit on the number of prompts, and prompts are no longer required to save a quest. You can create a quest with zero prompts or add as many prompts as your study design needs.
  </Accordion>
</AccordionGroup>

## Onboarding & Consent

<AccordionGroup>
  <Accordion title="What are question guards?">
    Question guards are server-side validation rules on onboarding questions that determine whether a participant is eligible to join a quest. For example, you can block participants under 18 by setting a guard: `operator: gte, value: 18`. See [Question Guards](/onboarding/question-guards).
  </Accordion>

  <Accordion title="Can I block ineligible participants?">
    Yes. Configure question guards on your onboarding questions. If a participant's answer fails validation, they see a rejection message and cannot join the quest. This is enforced server-side.
  </Accordion>

  <Accordion title="What is kiosk mode?">
    Kiosk mode re-shows the onboarding flow (consent overview + questions) every session, even for participants who have already joined. This is useful for shared devices in labs, clinics, or events. See [Kiosk Mode](/onboarding/kiosk-mode).
  </Accordion>

  <Accordion title="Is the full-text overview required?">
    No. Both the full-text overview and onboarding questions are optional. A quest can have neither, one, or both.
  </Accordion>
</AccordionGroup>

## Experiments

<AccordionGroup>
  <Accordion title="What experiment frameworks are supported?">
    The experiment editor provides a default **jsPsych 8.0.3** template with 13 pre-loaded plugins. You can write any HTML/JavaScript experiment that calls `jatos.endStudy()` to submit data. See [Experiment Editor](/experiments/experiment-editor).
  </Accordion>

  <Accordion title="Can I upload images, audio, and video for my experiments?">
    Yes. The media uploader supports JPEG, PNG, GIF, WebP, SVG (images), MP3, WAV, OGG (audio), and MP4, WebM, OGG (video). Maximum file size is **25 MB** per file. See [Media Uploads](/experiments/media-uploads).
  </Accordion>

  <Accordion title="Can participants run experiments on mobile?">
    Yes. The Fusion mobile app (iOS and Android) supports running experiments in a WebView with automatic landscape orientation lock. Data is saved locally first and synced to the server. See [Running on Mobile](/experiments/running-on-mobile).
  </Accordion>

  <Accordion title="Can a quest have multiple experiments?">
    Yes. A quest can hold multiple experiments with defined ordering. Participants see a horizontal list of experiment cards and can complete them sequentially. See [Ordering & Assignment](/experiments/ordering-and-assignment).
  </Accordion>
</AccordionGroup>

## Organizations

<AccordionGroup>
  <Accordion title="Who can create an organization?">
    Any NeuroFusion user can create an organization. The creator automatically becomes the admin.
  </Accordion>

  <Accordion title="Can I be in multiple organizations?">
    Yes. You can be a member of multiple organizations with different permission levels in each.
  </Accordion>

  <Accordion title="How do I transfer a quest between organizations?">
    You need appropriate permissions on both the source and target organizations. Use the quest transfer feature in the org dashboard. See [Managing Quests](/organizations/managing-quests).
  </Accordion>

  <Accordion title="What permissions are available?">
    There are 18 granular permissions across 5 categories: Admin, Organization, Quest, Credits, and Data. See [Members & Permissions](/organizations/members-and-permissions) for the full reference table.
  </Accordion>
</AccordionGroup>

## Billing & Pricing

<AccordionGroup>
  <Accordion title="What do credits cost?">
    You can purchase credits in preset packages or enter a custom amount. Payment is via Stripe. See the [Pricing page](https://usefusion.ai/pricing) for current packages and the [Purchasing Credits](/billing/purchasing-credits) guide.
  </Accordion>

  <Accordion title="What actions are billable?">
    Publishing a quest, participant joins, prompt responses, experiment submissions, brain recordings, health data syncs, dataset storage, and data analysis. Quest creation and onboarding responses are **free**. See the [Pricing page](https://usefusion.ai/pricing) for current costs, or [Expense Breakdown](/billing/expense-breakdown) for per-quest tracking.
  </Accordion>

  <Accordion title="Can I fund another organization's credits?">
    Yes. You can transfer credits to another org with an optional note. This requires the `credits:transfer` permission. See [Funding Other Orgs](/billing/funding-other-orgs).
  </Accordion>
</AccordionGroup>

## Data & Privacy

<AccordionGroup>
  <Accordion title="Where is my data stored?">
    Data is stored on Azure Blob Storage. Experiment data and brain recordings are stored as files in blob storage. Prompt responses and onboarding responses are stored in the platform database.
  </Accordion>

  <Accordion title="Is NeuroFusion compliant with data privacy regulations?">
    Yes. NeuroFusion adheres to GDPR, HIPAA, and other global standards. Researchers retain full control over dataset access and sharing permissions.
  </Accordion>

  <Accordion title="Can I export my data?">
    Yes. Data can be exported from the platform for analysis in external tools (e.g., R, Python, SPSS). On mobile, participants can export experiment data as JSON files.
  </Accordion>
</AccordionGroup>

## Prolific

<AccordionGroup>
  <Accordion title="How do I connect my quest to Prolific?">
    Use your quest's run URL as the study URL in Prolific. No special configuration is needed — NeuroFusion automatically captures Prolific URL parameters (`PROLIFIC_PID`, `STUDY_ID`, `SESSION_ID`). See [Prolific Integration](/integrations/prolific).
  </Accordion>

  <Accordion title="Are Prolific participant IDs captured?">
    Yes. All URL parameters are automatically passed to experiments via `jatos.urlQueryParameters`, so `PROLIFIC_PID` is included in your experiment data.
  </Accordion>
</AccordionGroup>

## Mobile

<AccordionGroup>
  <Accordion title="Which platforms does the mobile app support?">
    The Fusion mobile app is available on both iOS and Android.
  </Accordion>

  <Accordion title="Can participants run experiments on mobile?">
    Yes. Experiments run in a WebView with landscape orientation lock. Data is saved locally and synced to the server. See [Running on Mobile](/experiments/running-on-mobile).
  </Accordion>

  <Accordion title="Can I integrate wearable data?">
    Yes. NeuroFusion integrates with wearables for health data collection (steps, sleep, heart rate) and EEG devices like Neurosity Crown and Muse. See [Brain Interfaces](/integrations/brain-interfaces) and [Wearables](/integrations/wearables).
  </Accordion>
</AccordionGroup>


# Expense Breakdown
Source: https://docs.usefusion.ai/billing/expense-breakdown

Track your organization's spending per quest and per billable item type.

The expense breakdown gives you visibility into exactly where your credits are going — broken down by quest, item type, participant count, and source (web or mobile).

## Viewing Expenses

Navigate to your organization's **Billing** page to see:

* **Current balance** — your available credits in dollars
* **Total spent** — cumulative spending across all quests
* **Per-quest breakdown** — expenses grouped by quest

## Expense Categories

All charges fall into one of four categories:

### Quest & Experiments

| Item           | When Charged                    |
| -------------- | ------------------------------- |
| Publish Quest  | First time a quest is published |
| Quest Join     | Each time a participant joins   |
| Experiment Run | Each experiment data submission |

### Data Collection

| Item                  | When Charged                |
| --------------------- | --------------------------- |
| Brain Recording (EEG) | Each EEG session uploaded   |
| Prompt Response       | Each prompt response stored |
| Health Data Sync      | Each wearable data sync     |

### Storage

| Item            | When Charged                |
| --------------- | --------------------------- |
| Dataset Storage | Monthly for stored datasets |

### Analysis & AI

| Item          | When Charged         |
| ------------- | -------------------- |
| Data Analysis | Each AI analysis run |

For current per-item costs, see the **[Pricing page](https://usefusion.ai/pricing)**.

## Per-Quest Billing

The per-quest breakdown shows:

* **Quest name** and identifier
* **Item type breakdown** — how many of each billable action occurred
* **Participant count** — total participants who incurred charges
* **Source breakdown** — charges from web vs. mobile

This helps you understand which quests are consuming the most credits and where your budget is going.

## Transaction History

Every credit deduction creates a transaction record with:

| Field           | Description                                           |
| --------------- | ----------------------------------------------------- |
| **Type**        | `usage`, `purchase`, `refund`, `bonus`, or `transfer` |
| **Amount**      | Negative for charges, positive for additions          |
| **Description** | Human-readable description of the charge              |
| **Quest ID**    | Which quest triggered the charge                      |
| **Item type**   | The specific billable action                          |
| **Source**      | `web` or `mobile`                                     |
| **Timestamp**   | When the charge occurred                              |

## Budget Planning

Use the **[interactive price calculator](https://usefusion.ai/pricing)** to estimate your total study cost. Enter your participant count, number of prompts, experiments, and data types, and the calculator will show a detailed cost breakdown.

<Tip>
  Your organization starts with free starter credits. For a small pilot study (10-20 participants with a single experiment), the starter credits may be sufficient.
</Tip>


# Funding Other Organizations
Source: https://docs.usefusion.ai/billing/funding-other-orgs

Transfer credits between organizations to fund collaborators or sub-teams.

You can transfer credits from one organization to another. This is useful for funding collaborators, sub-teams, or partner labs that are running studies on your behalf.

## Requirements

* You must have the `credits:transfer` permission (or be an admin) in the **sending** organization
* The **receiving** organization must already exist
* You need to know the receiving organization's name (searchable, minimum 3 characters)

## Transfer Limits

Minimum and maximum transfer amounts apply. See the **[Pricing page](https://usefusion.ai/pricing)** for current limits.

<Warning>
  You cannot transfer credits to the **same** organization. The source and destination must be different orgs.
</Warning>

## How to Transfer

1. Navigate to your organization's **Billing** page
2. Click **Transfer Credits**
3. Search for the destination organization (type at least 3 characters)
4. Enter the amount to transfer
5. Optionally add a **note** describing the purpose (up to 280 characters)
6. Click **Transfer**

## What Happens

When you complete a transfer:

| Side              | Effect                                                                                               |
| ----------------- | ---------------------------------------------------------------------------------------------------- |
| **Sending org**   | Balance decreases by the transfer amount. A transaction record is created with direction `outgoing`. |
| **Receiving org** | Balance increases by the transfer amount. A transaction record is created with direction `incoming`. |

Both organizations can see the transfer in their transaction history, including:

* The transfer amount
* The other organization's name
* The note (if provided)
* The direction (incoming/outgoing)
* The timestamp

## Use Cases

| Scenario                   | Example                                                                  |
| -------------------------- | ------------------------------------------------------------------------ |
| **Funding a collaborator** | A PI transfers \$100 to a partner lab running a sub-study                |
| **Departmental budgeting** | A department org funds individual lab orgs at the start of the semester  |
| **Splitting costs**        | Two labs co-running a study split the budget via transfer                |
| **Student research**       | A supervisor transfers credits to a student's org for their thesis study |

## Tips

* Transfers are **instant** — credits appear in the receiving org immediately
* Both parties can see the full transfer details in their transaction history
* Use the **note** field to document the purpose (e.g., "Funding for Spring 2026 attention study")
* You can make multiple transfers — there's no limit on the number of transfers, only per-transfer amount limits


# Billing & Credits Overview
Source: https://docs.usefusion.ai/billing/overview

Understand the Fusion credit system — how credits work, what costs what, and how to manage spending.

Fusion uses a **credit-based billing system**. Credits are the currency for all platform actions — publishing quests, storing data, running experiments, and more.

## How Credits Work

| Concept           | Value                                   |
| ----------------- | --------------------------------------- |
| **1 credit**      | 1 cent                                  |
| **Starter bonus** | Free credits for every new organization |

Credits are managed at the **organization level**. Every action that costs credits is charged to the organization that owns the quest. See the **[Pricing page](https://usefusion.ai/pricing)** for current credit values and costs.

## What Costs Credits

The following actions consume credits from your organization's balance:

| Action                      | Category            |
| --------------------------- | ------------------- |
| Publish a quest             | Quest & Experiments |
| Participant joins a quest   | Quest & Experiments |
| Experiment data submission  | Quest & Experiments |
| Brain recording (EEG)       | Data Collection     |
| Prompt response stored      | Data Collection     |
| Health data sync (wearable) | Data Collection     |
| Dataset storage             | Storage             |
| AI data analysis            | Analysis & AI       |
| Analysis script execution   | Analysis & AI       |

For current prices, see the **[Pricing page](https://usefusion.ai/pricing)**.

### Free Actions

These actions are **free** and do not consume credits:

* Creating a quest (draft)
* Editing a quest
* Adding prompts and experiments
* Configuring onboarding
* Onboarding responses (no charge)
* Viewing data in the dashboard
* Adding organization members

## Re-Publishing Is Free

The first time you publish a quest, it costs credits. **Re-publishing** the same quest (after unpublishing and making changes) is free — the system checks for a prior publish transaction.

## Debt Tolerance

Some operations allow a small amount of debt to prevent data loss:

| Action                                          | Debt Allowed                                          |
| ----------------------------------------------- | ----------------------------------------------------- |
| Publishing a quest                              | ❌ No — strict check, returns error if balance too low |
| Data collection (experiment, prompt, EEG, etc.) | ✅ Yes — small debt allowed                            |

<Info>
  Data collection actions never fail due to insufficient credits. The system allows a small amount of debt so participant data is never lost. Publishing, however, requires a sufficient balance.
</Info>

## Low Balance Warning

When your organization's credit balance is running low, an amber warning appears on the dashboard:

> *"Your credit balance is running low. Add credits to continue using premium features."*

## Price Calculator

Use the **interactive price calculator** at [usefusion.ai/pricing](https://usefusion.ai/pricing) to estimate costs for your study based on participant count, prompts, experiments, and data types.

## Explore

<CardGroup>
  <Card title="Purchasing Credits" icon="cart-shopping" href="/billing/purchasing-credits">
    Buy credits with Stripe.
  </Card>

  <Card title="Expense Breakdown" icon="chart-pie" href="/billing/expense-breakdown">
    Track spending per quest and item type.
  </Card>

  <Card title="Funding Other Orgs" icon="arrow-right-arrow-left" href="/billing/funding-other-orgs">
    Transfer credits between organizations.
  </Card>
</CardGroup>


# Purchasing Credits
Source: https://docs.usefusion.ai/billing/purchasing-credits

Buy credits via Stripe to fund your organization's quests and data collection.

Credits can be purchased using a credit or debit card through **Stripe**. Payments are processed securely and credits are added to your organization immediately upon successful payment.

## Requirements

* You must have the `credits:purchase` permission in the organization (or be an admin)
* A valid credit or debit card

## Credit Packages

Choose from preset packages or enter a custom amount. See the **[Pricing page](https://usefusion.ai/pricing)** for current package details and amounts.

<Frame>
  <img alt="Pricing page with free Build and Design plan, pay-as-you-go plan, and study cost estimator" />
</Frame>

## How to Purchase

1. Navigate to your organization's **Billing** page
2. Click **Add Credits**
3. Select a preset package or enter a custom amount
4. Click **Purchase** — you'll be redirected to Stripe Checkout
5. Complete payment with your card
6. Credits are added to your organization's balance automatically

## Payment Processing

| Step             | What Happens                                   |
| ---------------- | ---------------------------------------------- |
| Checkout started | A pending transaction is created               |
| Payment succeeds | Transaction marked as completed, credits added |
| Payment fails    | Transaction marked as failed, no credits added |
| Session expires  | Transaction marked as expired                  |

<Info>
  A Stripe customer is automatically created for your organization the first time you make a purchase. Subsequent purchases use the same Stripe customer.
</Info>

## Purchase Limits

Minimum and maximum purchase amounts apply. See the **[Pricing page](https://usefusion.ai/pricing)** for current limits.

## Receipts

Stripe provides receipts for all purchases. You can access them through your Stripe payment confirmation email.


# Data Audit Trail
Source: https://docs.usefusion.ai/data/audit-trail

Track who accessed, downloaded, or modified research data in your organization.

The data audit trail provides a complete record of data-related actions within your organization. Every time someone views, downloads, deletes, or runs AI analysis on quest data, an entry is logged in the **Audit Log**.

## Why Audit Trails Matter

For research compliance (IRB, GDPR, HIPAA), you may need to demonstrate:

* **Who** accessed participant data and **when**
* What **actions** were taken on the data
* Which specific **datasets** were involved

NeuroFusion's audit trail captures all of this automatically.

## Tracked Actions

| Action        | Description                                     |
| ------------- | ----------------------------------------------- |
| `view`        | A user viewed a dataset or participant response |
| `download`    | A user downloaded dataset files                 |
| `delete`      | A user deleted a dataset                        |
| `ai_analysis` | AI-powered analysis was run on the data         |

## Viewing the Audit Trail

1. Navigate to your **Organization** settings
2. Select the **Audit Log** tab
3. Browse the log entries, which show:
   * **Timestamp** — When the action occurred
   * **User** — Who performed the action
   * **Action** — What was done (view, download, delete, AI analysis)
   * **Quest** — Which quest the data belongs to
   * **Details** — Additional metadata (file names, dataset IDs, etc.)

## Availability

The data audit trail is available for **organization-owned quests**. Personal quests (not associated with an organization) do not generate audit entries.

<Info>
  Audit trail data is retained indefinitely and cannot be modified or deleted. This ensures the integrity of the compliance record.
</Info>


# Viewing Your Datasets
Source: https://docs.usefusion.ai/data/viewing-your-datasets

Browse your personal datasets and data from organizations you belong to.

NeuroFusion gives you access to two categories of datasets: **your own data** (submitted across any quest) and **organization data** (collected by quests belonging to organizations you're a member of).

## Your Personal Datasets

Navigate to **Datasets** from the main menu to see everything you've personally submitted. The page has two tabs:

* **Quest Datasets** — Data you've submitted to quests (experiments, prompts, onboarding, health data)
* **Local Recordings** — Brain recordings stored locally on your device

### Dataset Types

Your data is grouped by type:

| Type                  | Icon | What It Includes                                                    |
| --------------------- | ---- | ------------------------------------------------------------------- |
| **Brain Recordings**  | 🧠   | EEG data from Muse or Neurosity headbands                           |
| **Experiment Trials** | 🧪   | Responses from jsPsych cognitive tasks (grouped by experiment name) |
| **Self-Reports**      | 📝   | Prompt responses (mood, productivity, wellbeing, etc.)              |
| **Questionnaires**    | 📋   | Onboarding and survey responses                                     |
| **Health Data**       | ❤️   | Steps, sleep, heart rate from Apple Health / Health Connect         |

Each entry shows the **quest name**, **submission timestamp**, and **type-specific details** (e.g., experiment name for trial data).

## Organization Datasets

If you belong to an organization, you can also access data collected by that organization's quests — not just your own submissions, but data from all participants.

### How to Access Organization Data

1. Go to **Organizations** and select your organization
2. Navigate to the **Quests** tab to see all quests owned by the organization
3. Click on a quest to open its detail page
4. The **Data** section shows all collected datasets from all participants

<Info>
  To view organization quest data, you need the `data.view` permission (or higher) within that organization. Contact your organization admin if you don't see the data tab.
</Info>

### What Organization Members Can See

| Data View                                  | What's Shown                                | Where                     |
| ------------------------------------------ | ------------------------------------------- | ------------------------- |
| **Personal datasets**                      | Only your own submissions across all quests | `/datasets` page          |
| **Quest detail (as creator/collaborator)** | All participants' data for that quest       | Quest detail page         |
| **Quest detail (as participant)**          | Only your own submissions for that quest    | Quest detail page         |
| **Organization quests**                    | All quests owned by the org                 | Organization → Quests tab |

### Organization Quest Data Includes

When viewing an organization's quest data, you can see:

* **Participant count** — How many people have joined the quest
* **All submitted datasets** — Grouped by data type (experiments, prompts, recordings, etc.)
* **Individual responses** — Browse specific participant submissions
* **Aggregated insights** — AI-powered analysis across all collected data

## AI-Powered Insights

You can ask AI questions about datasets from both the personal Datasets page and organization quest detail pages:

1. **Ask about all data** — Get a holistic summary across datasets
2. **Ask about specific datasets** — Select one or more entries using checkboxes, then ask a focused question
3. **Follow-up questions** — After each AI response, suggested follow-up questions are provided for deeper exploration

AI insights stream in real-time. For brain recordings, the AI understands EEG frequency bands (delta, theta, alpha, beta, gamma) and what they indicate.

## Permissions Summary

| Capability                    | Participant | Org Member (data.view) | Quest Creator / Admin |
| ----------------------------- | ----------- | ---------------------- | --------------------- |
| View own datasets             | ✅           | ✅                      | ✅                     |
| View other participants' data | ❌           | ✅ (org quests)         | ✅                     |
| AI insights on own data       | ✅           | ✅                      | ✅                     |
| AI insights on all quest data | ❌           | ✅ (org quests)         | ✅                     |
| Download datasets             | ✅ (own)     | ✅ (org quests)         | ✅                     |
| Delete datasets               | ❌           | ❌                      | ✅                     |

## Privacy

* On the **Datasets page**, you only see your own submissions — other participants' data is never visible there
* **Organization quest data** is only accessible to org members with appropriate permissions
* All data access by organization members is logged in the [Data Audit Trail](/data/audit-trail)
* Quests that are not published (private) are only accessible to the creator and organization members


# Experiment Editor
Source: https://docs.usefusion.ai/experiments/experiment-editor

Write and preview jsPsych experiments with the built-in Monaco code editor.

The experiment editor is a **full-screen modal** where you write, edit, and preview your experiment code. It includes a code editor with a default jsPsych template, a live preview for testing, and an AI generator for creating experiments from natural-language descriptions.

## AI Experiment Generator

Instead of writing experiment code from scratch, you can describe what you want in plain English and let AI generate the full jsPsych experiment for you.

1. Open the experiment editor (click **Add Experiment** or edit an existing one)
2. Click the **Generate with AI** button
3. Describe your experiment in the text field (e.g., "Create a Stroop color-word interference task with 20 congruent and 20 incongruent trials, recording reaction time")
4. Click **Generate** — the AI produces a complete jsPsych HTML/JavaScript experiment
5. The generated code is loaded into the editor where you can review, modify, and preview it

<Info>
  The AI generator uses your description to create a working jsPsych 8 experiment with appropriate plugins, trial configurations, and data collection. More complex experiments produce more code — review the output carefully and test with the live preview before saving.
</Info>

## Editor Layout

The editor has three main sections:

1. **Metadata fields** — Name (required), description, and image URL
2. **Media uploader** — drag-and-drop component for uploading images, audio, and video (see [Media Uploads](/experiments/media-uploads))
3. **Code editor** — Monaco editor (the same editor used in VS Code) for writing HTML/JavaScript
4. **Live preview** — toggleable side-by-side preview to test your experiment

## Default jsPsych Template

When you create a new experiment, the editor starts with a **jsPsych 8.0.3** template that includes a complete HTML document with the following plugins pre-loaded:

| Plugin                    | Description                                          |
| ------------------------- | ---------------------------------------------------- |
| `html-button-response`    | Display HTML content, respond with a button click    |
| `html-keyboard-response`  | Display HTML content, respond with a keypress        |
| `image-keyboard-response` | Display an image, respond with a keypress            |
| `image-button-response`   | Display an image, respond with a button click        |
| `instructions`            | Multi-page instruction screens with navigation       |
| `survey-text`             | Free-text survey questions                           |
| `audio-keyboard-response` | Play audio, respond with a keypress                  |
| `video-keyboard-response` | Play video, respond with a keypress                  |
| `video-button-response`   | Play video, respond with a button click              |
| `html-slider-response`    | Display HTML content, respond with a slider          |
| `call-function`           | Run arbitrary JavaScript at a point in the timeline  |
| `fullscreen`              | Enter or exit fullscreen mode                        |
| `preload`                 | Preload images, audio, and video before trials begin |

You can modify the template, remove plugins you don't need, or add additional jsPsych plugins via CDN.

## Writing Your Experiment

The experiment code is a complete HTML document. A minimal jsPsych experiment looks like:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <script src="https://unpkg.com/jspsych@8.0.3"></script>
  <script src="https://unpkg.com/@jspsych/plugin-html-keyboard-response@2.0.0"></script>
  <link rel="stylesheet" href="https://unpkg.com/jspsych@8.0.3/css/jspsych.css">
</head>
<body>
  <script>
    const jsPsych = initJsPsych({
      on_finish: function() {
        jatos.endStudy(jsPsych.data.get().json());
      }
    });

    const trial = {
      type: jsPsychHtmlKeyboardResponse,
      stimulus: '<p>Press any key to continue.</p>'
    };

    jsPsych.run([trial]);
  </script>
</body>
</html>
```

<Warning>
  Your experiment **must** call `jatos.endStudy(data)` when it finishes. This is how NeuroFusion captures the experiment data. Without this call, no data will be saved.
</Warning>

## Using Uploaded Media

After uploading media files (see [Media Uploads](/experiments/media-uploads)), you can reference them in your experiment code using their URLs:

```javascript theme={null}
const trial = {
  type: jsPsychImageKeyboardResponse,
  stimulus: 'https://your-uploaded-image-url.blob.core.windows.net/image.png',
  choices: ['f', 'j']
};
```

Use the **Copy URL** button in the media uploader to grab the URL for each file.

## Live Preview

Toggle the **live preview** to see your experiment running side-by-side with the code editor. This lets you:

* Test your experiment without publishing the quest
* Verify that stimuli display correctly
* Check the flow of trials
* Debug timing and response issues

## Validation

Both **name** and **code** are required to save an experiment. The editor will prevent saving if either is empty.

## Tips

<Tip>
  Use the `preload` plugin to load all images, audio, and video before the experiment starts. This prevents delays during trials.
</Tip>

* Start with the default template and modify it — it has all the common plugins ready to use
* Test with the live preview frequently as you build
* Use `jsPsych.data.get().json()` to pass all trial data to `jatos.endStudy()`
* If you need plugins not in the default template, add them via CDN `<script>` tags


# Media Uploads
Source: https://docs.usefusion.ai/experiments/media-uploads

Upload images, audio, and video to use as stimuli in your experiments.

The media uploader lets you upload files to use as stimuli in your jsPsych experiments. Files are stored in Azure Blob Storage and accessible via public URLs.

## Supported File Types

| Type       | Formats                   |
| ---------- | ------------------------- |
| **Images** | JPEG, PNG, GIF, WebP, SVG |
| **Audio**  | MP3, WAV, OGG             |
| **Video**  | MP4, WebM, OGG            |

## Limits

* Maximum file size: **25 MB** per file
* No limit on the number of files

## How to Upload

1. Open your quest in the editor and navigate to an experiment
2. In the experiment editor, find the **media uploader** section
3. **Drag and drop** files onto the upload area, or **click** to browse and select files
4. Files upload immediately and appear in the media gallery below

<Warning>
  Media upload is only available **after the quest is saved for the first time**. The quest needs a GUID to associate uploaded files with. Save the quest first, then add media.
</Warning>

## Using Uploaded Files in Experiments

After uploading, each file gets a public URL. To use it in your experiment:

1. Find the file in the media gallery
2. Click the **Copy URL** button
3. Paste the URL into your experiment code as a stimulus:

```javascript theme={null}
// Image stimulus
const trial = {
  type: jsPsychImageKeyboardResponse,
  stimulus: 'https://your-storage.blob.core.windows.net/uploads/face_01.png',
  choices: ['f', 'j'],
  prompt: '<p>Press F for happy, J for sad</p>'
};

// Audio stimulus
const audioTrial = {
  type: jsPsychAudioKeyboardResponse,
  stimulus: 'https://your-storage.blob.core.windows.net/uploads/tone_500hz.mp3',
  choices: ['y', 'n']
};

// Video stimulus
const videoTrial = {
  type: jsPsychVideoButtonResponse,
  stimulus: ['https://your-storage.blob.core.windows.net/uploads/clip.mp4'],
  choices: ['Continue']
};
```

<Tip>
  Use the `preload` plugin to load all media before the experiment starts. This prevents buffering delays during trials.

  ```javascript theme={null}
  const preload = {
    type: jsPsychPreload,
    images: ['https://...face_01.png', 'https://...face_02.png'],
    audio: ['https://...tone_500hz.mp3']
  };
  ```
</Tip>

## Managing Uploads

* **View**: All uploaded files appear in a gallery below the upload area
* **Delete**: Click the delete button on any file to remove it from storage
* Deleting a file **does not** automatically update experiment code that references it — update your code manually

## Example Workflow

Building a face-recognition experiment:

1. Create and save your quest
2. Add an experiment called "Face Recognition Task"
3. Upload your face images (e.g., `happy_01.png`, `sad_01.png`, `neutral_01.png`)
4. Copy each image URL
5. Reference the URLs in your jsPsych timeline:

```javascript theme={null}
const faces = [
  { stimulus: 'https://.../happy_01.png', correct_response: 'h' },
  { stimulus: 'https://.../sad_01.png', correct_response: 's' },
  { stimulus: 'https://.../neutral_01.png', correct_response: 'n' }
];

const trial = {
  type: jsPsychImageKeyboardResponse,
  stimulus: jsPsych.timelineVariable('stimulus'),
  choices: ['h', 's', 'n'],
  data: { correct_response: jsPsych.timelineVariable('correct_response') }
};

const procedure = {
  timeline: [trial],
  timeline_variables: faces,
  randomize_order: true
};
```


# Ordering & Assignment
Source: https://docs.usefusion.ai/experiments/ordering-and-assignment

Reorder experiments, set up dependencies between them, and use assignment scripts for counterbalancing.

When a quest has multiple experiments, you can control the **order** participants see them, set **dependencies** between experiments, enable **auto-trigger** to advance automatically, and use **assignment scripts** for counterbalancing.

## Experiment Ordering

Experiments in a quest are displayed in the order they appear in the quest editor. You can reorder them using the **up/down arrow buttons** on each experiment card.

<Frame>
  <img alt="Experiment cards showing numbered badges and up/down reorder buttons" />
</Frame>

* Each experiment card shows a **numbered badge** indicating its position
* Use the **up arrow** (˄) and **down arrow** (˅) to move an experiment earlier or later in the sequence
* Participants see experiments as **horizontally scrollable cards** on the run page
* The **active experiment** is highlighted and clicking a card selects it

<Info>
  Reordering experiments may remove invalid dependencies. If experiment B depends on experiment A and you move B before A, that dependency is automatically cleaned up.
</Info>

## Dependencies

Dependencies let you **lock** an experiment until one or more prerequisite experiments have been completed. This is useful for sequential protocols where later experiments rely on earlier ones.

### Setting Dependencies

1. Click **Edit** on an experiment card
2. Open the **Ordering Options** disclosure at the bottom of the editor
3. Under **Required Experiments (Dependencies)**, check the experiments that must be completed first
4. Only experiments that come **before** the current one in the list can be selected as dependencies

<Frame>
  <img alt="Experiment editor showing the Ordering Options disclosure with dependency checkboxes and auto-trigger" />
</Frame>

### How Dependencies Work at Runtime

When a participant opens a quest with dependencies configured:

* Experiments with **unmet dependencies** show a **lock icon** and cannot be selected
* A locked experiment displays the message *"Complete the required experiments first"*
* Once all required experiments are completed, the lock is removed and the experiment becomes clickable
* Experiments with **no dependencies** are always available

### Validation Rules

The editor enforces several rules to keep dependencies valid:

| Rule                         | Description                                                                                                     |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Order-aware**              | You can only depend on experiments that come before the current one in the list                                 |
| **No circular dependencies** | If A depends on B, then B cannot depend on A (detected automatically)                                           |
| **Cleanup on delete**        | If a dependency experiment is deleted, it is automatically removed from all other experiments' dependency lists |
| **Cleanup on reorder**       | If reordering causes a dependency to now come after the dependent, it is automatically removed                  |

## Auto-Trigger

When **Auto-trigger next experiment** is enabled on an experiment, the system will automatically advance the participant to the next available experiment as soon as the current one is completed.

To enable it:

1. Click **Edit** on an experiment card
2. Open the **Ordering Options** disclosure
3. Check **Auto-trigger next experiment**

This is useful for guided protocols where participants should move through experiments in a fixed sequence without having to manually select the next one.

<Tip>
  Combine dependencies with auto-trigger for a fully guided, linear experiment flow — participants are automatically advanced through a locked sequence.
</Tip>

## Completion Tracking

Experiment completion is tracked **per session**. When a participant reloads the quest run page, all completion state resets and experiments start fresh. Within a single session:

* Completing an experiment marks it with a **green checkmark**
* Dependent experiments are unlocked as their prerequisites are met
* Auto-trigger fires immediately after completion if enabled

## Assignment Editor

The assignment editor is an advanced feature for **counterbalancing**, **conditional assignment**, or **randomization**. It lets you write a script that determines which experiment a participant gets assigned to.

### How It Works

1. You write a **Python script** in the assignment editor
2. You **map onboarding question responses** to script input variables
3. When a participant joins, the script runs with their onboarding answers as inputs
4. The script output determines which experiment the participant sees

### Configuration

The assignment configuration has:

| Field                | Description                                                            |
| -------------------- | ---------------------------------------------------------------------- |
| **Script**           | Python code to execute                                                 |
| **Language**         | Script language (`python` or `javascript`)                             |
| **Variable Mapping** | Maps an onboarding question (source ID) to a placeholder variable name |

### Variable Mapping

For each variable:

1. Select a **source** — an onboarding question
2. Enter a **placeholder name** — the variable name used in the script
3. The participant's answer to that question is injected as the variable's value when the script runs

### Example: Random Assignment

Randomly assign participants to one of two experiment conditions:

```python theme={null}
import random

# No variables needed — purely random
condition = random.choice(["control", "treatment"])
print(condition)
```

### Example: Age-Based Assignment

Assign different experiments based on participant age (collected during onboarding):

```python theme={null}
# Variable mapping: onboarding question "How old are you?" → age
age = int(age)  # injected from onboarding response

if age < 25:
    print("young_adult_protocol")
elif age < 65:
    print("adult_protocol")
else:
    print("older_adult_protocol")
```

### Example: Counterbalancing

Assign participants to alternating conditions:

```python theme={null}
import hashlib

# Variable mapping: onboarding question "participant ID" → participant_id
hash_val = int(hashlib.md5(participant_id.encode()).hexdigest(), 16)
condition = "A" if hash_val % 2 == 0 else "B"
print(condition)
```

## How Assignment Data Is Used

The assignment script output is stored alongside the quest's assignment configuration. The server fetches onboarding responses for assignment scripts via the dataset API with type `onboarding_responses`.

<Info>
  Assignment scripts currently support **Python** and **JavaScript**. Python is the most common choice.
</Info>

## Tips

* Use the **up/down arrows** to set experiment order, then add **dependencies** to enforce that order at runtime
* Enable **auto-trigger** on sequential experiments to create a guided flow
* Experiments without any ordering options configured behave exactly as before — all are available, no locks
* Use assignment scripts for between-subjects designs where different groups see different experiments
* Combine with [onboarding questions](/onboarding/questions) to collect the variables your assignment script needs
* Test your assignment script thoroughly before publishing — incorrect assignment logic can compromise your study design


# Experiments Overview
Source: https://docs.usefusion.ai/experiments/overview

Add interactive jsPsych experiments to your quests — with multi-experiment support, media uploads, and mobile compatibility.

Experiments are **interactive tasks** — typically built with jsPsych — that participants complete as part of a quest. A quest can hold multiple experiments with defined ordering, and participants can run them on both web and mobile.

## What Is an Experiment?

Each experiment in a quest has:

| Field                  | Required? | Description                                   |
| ---------------------- | --------- | --------------------------------------------- |
| **Name**               | ✅ Yes     | Display name shown on the experiment card     |
| **Description**        | Optional  | Short description shown below the name        |
| **Image URL**          | Optional  | Thumbnail image for the experiment card       |
| **Code**               | ✅ Yes     | HTML/JavaScript code (typically jsPsych)      |
| **Duration (minutes)** | Optional  | Estimated time shown to participants          |
| **Category**           | Optional  | Category tag                                  |
| **Instructions**       | Optional  | HTML instructions shown before the experiment |

## Multi-Experiment Quests

A quest can have **multiple experiments**. When participants view the quest:

* Experiments are displayed as **horizontally scrollable cards** with thumbnail, name, description, and duration
* The active experiment is **highlighted**
* Clicking a card selects that experiment
* Participants can complete experiments in sequence
* Experiments can have **dependencies** — locking them until prerequisites are completed
* **Auto-trigger** can automatically advance to the next experiment after completion

## Data Flow

When a participant completes an experiment:

1. The jsPsych experiment calls `jatos.endStudy(data)` to submit results
2. Data is captured by the NeuroFusion runner
3. Saved locally first (for offline resilience on mobile)
4. Synced to the server and stored in Azure Blob Storage
5. Recorded as an `experiment_data` dataset

## Billing

Each experiment data submission is billed as `quest_experiment` to the quest's organization. See the **[Pricing page](https://usefusion.ai/pricing)** for current costs.

## Backward Compatibility

Older quests with a single `experimentUrl` string (the legacy format) continue to work. The system automatically treats them as a single-experiment quest.

## Explore

<CardGroup>
  <Card title="Experiment Editor" icon="code" href="/experiments/experiment-editor">
    Monaco code editor, jsPsych template, and live preview.
  </Card>

  <Card title="Media Uploads" icon="image" href="/experiments/media-uploads">
    Upload images, audio, and video for your experiments.
  </Card>

  <Card title="Ordering & Assignment" icon="list-ol" href="/experiments/ordering-and-assignment">
    Order experiments and use assignment scripts for counterbalancing.
  </Card>

  <Card title="Running on Mobile" icon="mobile" href="/experiments/running-on-mobile">
    Run experiments in the Fusion mobile app.
  </Card>
</CardGroup>


# Running Experiments on Mobile
Source: https://docs.usefusion.ai/experiments/running-on-mobile

Participants can complete experiments in the Fusion mobile app on iOS and Android.

The Fusion mobile app supports running jsPsych experiments directly on participants' phones and tablets. Experiments render in a WebView with automatic orientation handling and local-first data storage.

## How It Works

1. Participant opens the quest in the Fusion mobile app
2. Taps on an experiment card to start
3. The experiment loads in a **full-screen WebView**
4. Screen **locks to landscape orientation** for the duration of the experiment
5. When the experiment calls `jatos.endStudy(data)`, the data is captured
6. Screen returns to **portrait orientation**
7. A completion alert shows the number of trials recorded

## Data Flow

| Step               | What Happens                                                        |
| ------------------ | ------------------------------------------------------------------- |
| **Capture**        | `jatos.endStudy()` is intercepted by the React Native bridge        |
| **Local save**     | Data is saved to AsyncStorage immediately (offline-safe)            |
| **Server sync**    | Data is uploaded to Azure Blob Storage when connection is available |
| **Dataset record** | Saved as `experiment_data` with source `mobile`                     |

<Info>
  Data is saved **locally first**, so experiment data is not lost if the participant loses connectivity during or after the experiment. It syncs to the server automatically when a connection is available.
</Info>

## Differences from Web

| Feature            | Web                      | Mobile                                                            |
| ------------------ | ------------------------ | ----------------------------------------------------------------- |
| **Orientation**    | No forced orientation    | Locks to landscape during experiments                             |
| **Data storage**   | Direct server upload     | Local-first with background sync                                  |
| **CORS/CSP**       | Browser-handled          | Auto-injected by the app                                          |
| **Error handling** | Standard browser console | Captures `console.error`, unhandled rejections, and global errors |
| **Export**         | Download from dashboard  | Share as JSON file via device share sheet                         |

## Export on Mobile

Participants can export their experiment data directly from the mobile app:

1. Navigate to the completed experiment
2. Use the **export** option
3. Data is saved as a JSON file and shared via the device's share sheet (AirDrop, email, Files, etc.)

This uses `expo-file-system` and `expo-sharing` under the hood.

## When to Use Mobile vs. Web

| Use Case                                   | Recommended                                  |
| ------------------------------------------ | -------------------------------------------- |
| In-field / take-home studies               | ✅ Mobile                                     |
| Prolific recruitment                       | ✅ Web                                        |
| EEG sessions with mobile app               | ✅ Mobile                                     |
| Large-screen experiments (complex layouts) | ✅ Web                                        |
| Studies requiring precise keyboard input   | ✅ Web                                        |
| Participants without computer access       | ✅ Mobile                                     |
| Lab-based with shared computers            | ✅ Web + [Kiosk Mode](/onboarding/kiosk-mode) |

## Tips

<Tip>
  Design your experiment layout to work well in **landscape orientation** on phone-sized screens. Test on actual devices before launching.
</Tip>

* Experiments run on both iOS and Android through the Fusion app
* The same experiment code works on both web and mobile — no separate version needed
* Mobile data is tagged with source `mobile` so you can distinguish it from web data in your analysis
* If your experiment uses touch input instead of keyboard, it will work naturally on mobile
* Benign CORS "Script error." messages are automatically filtered on mobile


# Brain Interfaces / Mobile EEG
Source: https://docs.usefusion.ai/integrations/brain-interfaces

Record EEG brain data during experiments using Neurosity Crown or Muse headsets.

Fusion supports consumer-grade **mobile EEG headsets** for recording brain activity during experiments. Data is captured in real-time, saved locally, and uploaded to Azure Blob Storage.

## Supported Devices

<Frame>
  <img alt="Integrations page listing Neurosity Crown and Muse EEG devices with Connect buttons" />
</Frame>

| Device    | Manufacturer                               | Connection          | Status            |
| --------- | ------------------------------------------ | ------------------- | ----------------- |
| **Crown** | [Neurosity](https://neurosity.co)          | Bluetooth + OAuth   | ✅ Fully supported |
| **Muse**  | [Muse (Interaxon)](https://choosemuse.com) | Bluetooth (muse-js) | ✅ Supported       |

## Connecting Your Device

### Neurosity Crown — OAuth Authentication

1. Navigate to the **Devices** section in the Fusion dashboard
2. Click **Connect Neurosity Crown**
3. You'll be redirected to Neurosity's OAuth page at [neurosity.co](https://neurosity.co)
4. Sign in with your Neurosity account and authorize Fusion
5. After authorization, you're redirected back to Fusion with an access token
6. Select your device from the list of available Neurosity devices

Your device selection is saved and persists across sessions.

### Muse — Bluetooth Pairing

1. Ensure your Muse headset is powered on and in pairing mode
2. Navigate to the **Devices** section in the Fusion dashboard or mobile app
3. Click **Connect Muse**
4. Select your Muse device from the Bluetooth list
5. The connection is established via the [muse-js](https://github.com/urish/muse-js) library

## Recording a Session (Neurosity Crown)

When you start a recording with a Neurosity Crown, Fusion captures **8 simultaneous data streams**:

| Stream                           | Description                                        | File Name                       |
| -------------------------------- | -------------------------------------------------- | ------------------------------- |
| **Raw Brainwaves**               | Voltage readings per channel per timestamp         | `rawBrainwaves_{timestamp}.csv` |
| **Power by Band**                | Alpha, beta, delta, gamma, theta power per channel | `powerByBand_{timestamp}.csv`   |
| **Signal Quality**               | Standard deviation and status per channel          | `signalQuality_{timestamp}.csv` |
| **PSD (Power Spectral Density)** | Frequency-domain analysis per channel              | `psd_{timestamp}.csv`           |
| **Accelerometer**                | Head movement (x, y, z)                            | `accelerometer_{timestamp}.csv` |
| **Focus**                        | Neurosity's focus prediction score                 | `focus_{timestamp}.csv`         |
| **Calm**                         | Neurosity's calm prediction score                  | `calm_{timestamp}.csv`          |
| **Events**                       | Experiment markers and annotations                 | `events_{timestamp}.csv`        |

### Data Format

* **Raw brainwaves**: Each row contains a `timestamp`, `unixTimestamp`, and one column per EEG channel (e.g., `CP3`, `C3`, `F5`, etc.)
* **Power by band**: Each row contains a `timestamp` and columns like `{channel}_alpha`, `{channel}_beta`, `{channel}_delta`, `{channel}_gamma`, `{channel}_theta`
* **Signal quality**: Each row has a `timestamp`, `{channel}_value` (standard deviation), and `{channel}_status`
* **PSD**: Each row has a `timestamp` and one column per channel with semicolon-separated frequency values

## Recording a Session (Muse)

When you start a recording with a Muse headset, Fusion captures **2 data streams**:

| Stream             | Description                            | File Name                       |
| ------------------ | -------------------------------------- | ------------------------------- |
| **Raw Brainwaves** | Voltage readings across 4 EEG channels | `rawBrainwaves_{timestamp}.csv` |
| **Events**         | Experiment markers and annotations     | `events_{timestamp}.csv`        |

### Muse Specifications

| Spec                          | Value                                                      |
| ----------------------------- | ---------------------------------------------------------- |
| **Channels**                  | TP9, AF7, AF8, TP10                                        |
| **Sampling Rate**             | 256 Hz                                                     |
| **Signal Quality Indicators** | Great (green), OK (yellow), Bad (red), Disconnected (grey) |

### Data Format

* **Raw brainwaves**: Each row contains an `index`, `unixTimestamp`, and one column per channel (`TP9`, `AF7`, `AF8`, `TP10`)
* **Events**: Each row contains a `startTimestamp`, `duration`, and `data` (JSON-encoded experiment metadata)

### Neurosity Crown vs. Muse — Data Comparison

| Data Stream       | Neurosity Crown | Muse |
| ----------------- | --------------- | ---- |
| Raw brainwaves    | ✅               | ✅    |
| Power by band     | ✅               | ❌    |
| Signal quality    | ✅               | ❌    |
| PSD / FFT         | ✅               | ❌    |
| Accelerometer     | ✅               | ❌    |
| Focus predictions | ✅               | ❌    |
| Calm predictions  | ✅               | ❌    |
| Events / markers  | ✅               | ✅    |

## Data Storage

Recordings are handled in two ways:

1. **Local download** — a ZIP file containing all 8 CSV files is always downloaded to your computer
2. **Server upload** — if the recording is part of a quest, each data stream is also uploaded to Azure Blob Storage as a separate dataset

<Info>
  Local downloads always happen, ensuring you never lose data even if the upload fails.
</Info>

## Billing

Each brain recording is billed as `brain_recording` to the quest's organization. See the **[Pricing page](https://usefusion.ai/pricing)** for current costs.

## Use Cases

| Scenario                  | Setup                                                            |
| ------------------------- | ---------------------------------------------------------------- |
| **Resting-state EEG**     | Record brain activity while participant views a fixation cross   |
| **Task-related EEG**      | Record during a jsPsych experiment and align with event markers  |
| **Meditation study**      | Record during a calm/focus session using Neurosity's predictions |
| **Longitudinal tracking** | Repeated recordings over days/weeks via mobile app               |

## Tips

* Check **signal quality** before starting a recording — look for "good" status across all channels
* Use the **events** stream to mark experiment phases for later alignment
* Ensure a stable Bluetooth connection between the EEG device and the computer
* For mobile recordings, the Fusion app handles device connectivity through the same flow
* The Neurosity Crown streams additional data (focus, calm predictions) that the Muse does not provide


# Prolific Integration
Source: https://docs.usefusion.ai/integrations/prolific

Recruit participants from Prolific and automatically capture their IDs in your experiment data.

Fusion integrates with **Prolific** through URL parameter pass-through. When a Prolific participant clicks through to your quest, their Prolific identifiers are automatically captured and included in your experiment data.

## How It Works

1. You set up a study on Prolific with your quest URL
2. Prolific appends participant identifiers to the URL as query parameters
3. Fusion captures **all URL query parameters** and passes them to your experiments
4. Experiment data is saved with the Prolific IDs in the metadata

## Prolific URL Parameters

Prolific appends three standard parameters to your study URL:

| Parameter      | Description                                |
| -------------- | ------------------------------------------ |
| `PROLIFIC_PID` | The participant's unique Prolific ID       |
| `STUDY_ID`     | Your Prolific study ID                     |
| `SESSION_ID`   | The session ID for this particular attempt |

## Setting Up a Prolific Study

### Step 1: Get Your Quest URL

1. Create and publish your quest on Fusion
2. Copy the quest's public URL (e.g., `https://usefusion.ai/quests/your-quest-guid/run`)

### Step 2: Configure Prolific

1. Create a new study on Prolific
2. Set the **study URL** to your quest URL with Prolific's parameter placeholders:

```
https://usefusion.ai/quests/your-quest-guid/run?PROLIFIC_PID={{%PROLIFIC_PID%}}&STUDY_ID={{%STUDY_ID%}}&SESSION_ID={{%SESSION_ID%}}
```

Prolific will replace the placeholders with actual values when participants click through.

### Step 3: Access Parameters in Your Experiment

URL parameters are injected into your experiment as global JavaScript variables. In your jsPsych code:

```javascript theme={null}
// Access Prolific IDs directly as global variables
const prolificPid = typeof PROLIFIC_PID !== 'undefined' ? PROLIFIC_PID : null;
const studyId = typeof STUDY_ID !== 'undefined' ? STUDY_ID : null;
const sessionId = typeof SESSION_ID !== 'undefined' ? SESSION_ID : null;

// Or access all URL params via the urlParams object
const allParams = typeof urlParams !== 'undefined' ? urlParams : {};
console.log(allParams.PROLIFIC_PID);

// Include in your data
const jsPsych = initJsPsych({
  on_finish: function() {
    const data = jsPsych.data.get().json();
    jatos.endStudy(data);
  }
});
```

<Info>
  All URL parameters with valid JavaScript identifier names are automatically set as `window` properties. You can also access them via the global `urlParams` object which contains all parameters. Each parameter value is limited to 10KB.
</Info>

## How Prolific Data Appears in Exports

When experiment data is saved, the URL parameters (including Prolific IDs) are included in the dataset metadata:

```json theme={null}
{
  "urlParams": {
    "PROLIFIC_PID": "5f1a2b3c4d5e6f",
    "STUDY_ID": "abc123def456",
    "SESSION_ID": "xyz789"
  }
}
```

This makes it easy to match experiment data back to participants in Prolific.

## Additional URL Parameters

You can append **any custom URL parameters** beyond the standard Prolific ones. They'll all be captured and passed through:

```
https://usefusion.ai/quests/guid/run?PROLIFIC_PID={{%PROLIFIC_PID%}}&condition=treatment&group=A
```

In this example, `condition` and `group` would also be available as global variables in your experiment.

## Tips

* Test your study URL by appending fake parameters and verifying they appear in the experiment
* Use [onboarding](/onboarding/overview) to collect informed consent before the experiment begins
* Prolific completion redirects are handled externally — add a final jsPsych trial with a "Return to Prolific" link using your Prolific completion URL
* See [Running a Study](/quests/running-a-study) for the full end-to-end workflow with Prolific


# Wearables & Health Data
Source: https://docs.usefusion.ai/integrations/wearables

Collect steps, sleep, and heart rate data from Apple Health, Oura Ring, and Whoop.

Fusion can sync health data from wearable devices and health platforms. This enables longitudinal studies that combine behavioral experiments with physiological measures.

## Supported Platforms

| Platform         | Connection Method           | Status         |
| ---------------- | --------------------------- | -------------- |
| **Apple Health** | Direct read (iOS HealthKit) | ✅ Supported    |
| **Oura Ring**    | OAuth via Vital API         | ✅ Supported    |
| **Whoop**        | OAuth via Vital API         | ✅ Supported    |
| **Google Fit**   | —                           | 🔜 Coming soon |

## Data Types

Three categories of health data can be collected:

| Data Type      | Description                 | Source                |
| -------------- | --------------------------- | --------------------- |
| **Steps**      | Daily step count            | Pedometer / wearable  |
| **Sleep**      | Sleep sessions and duration | Wearable / health app |
| **Heart Rate** | Heart rate samples          | Wearable / health app |

## Enabling Health Data in a Quest

When creating or editing a quest, you can enable health data collection:

1. Open the quest editor
2. Find the **Health Data** configuration section
3. Toggle the data types you want to collect:
   * ✅ Steps
   * ✅ Sleep
   * ✅ Heart Rate
4. Save the quest

<Info>
  Health data collection is only available in the **Fusion mobile app**. Participants must have the app installed and grant health permissions.
</Info>

## Connecting a Wearable

### Apple Health (Direct)

On iOS, the Fusion app reads directly from Apple HealthKit:

1. Open the quest in the Fusion mobile app
2. Grant health permissions when prompted
3. Data syncs automatically

Requested HealthKit permissions include:

* Step count
* Sleep analysis
* Heart rate
* Workout data
* Activity summary

### Oura Ring & Whoop (OAuth)

For Oura and Whoop, data syncs through the Vital cloud API:

1. Open the quest in the Fusion mobile app
2. Tap **Connect Device**
3. Select **Oura** or **Whoop**
4. You'll be redirected to the device's OAuth page
5. Sign in and authorize data sharing
6. Data syncs automatically once connected

## Data Sync

| Step        | What Happens                                                           |
| ----------- | ---------------------------------------------------------------------- |
| **Read**    | Health data is read from the last 7 days                               |
| **Upload**  | Data is posted to the Fusion server                                    |
| **Storage** | Saved as a `health` dataset type in the quest                          |
| **Billing** | Credits charged per sync (see [Pricing](https://usefusion.ai/pricing)) |

Sync statuses you may see:

* `syncing` — Data transfer in progress
* `successSyncing` — Sync completed successfully
* `failedSyncing` — Sync failed (will retry)
* `nothingToSync` — No new data available
* `syncingCompleted` — All data types finished syncing

## Data Format

Health data is stored as JSON with one entry per date:

```json theme={null}
{
  "date": "2026-03-15",
  "steps": 8432,
  "sleep": {
    "duration": 28800,
    "start": "2026-03-14T23:15:00Z",
    "end": "2026-03-15T07:15:00Z"
  },
  "heart_rate": {
    "avg": 72,
    "min": 58,
    "max": 145
  }
}
```

## Billing

Each health data sync is billed as `health_data_sync` to the quest's organization. See the **[Pricing page](https://usefusion.ai/pricing)** for current costs.

## Use Cases

| Study Type                | Health Data          | Why                                                          |
| ------------------------- | -------------------- | ------------------------------------------------------------ |
| **Sleep & cognition**     | Sleep + experiments  | Correlate sleep quality with task performance                |
| **Exercise & mood**       | Steps + prompts      | Track activity levels alongside self-reported mood           |
| **Stress monitoring**     | Heart rate + prompts | Combine physiological stress markers with subjective reports |
| **Longitudinal wellness** | All three            | Comprehensive health tracking over weeks/months              |

## Tips

* Health data syncs the **last 7 days** of data, so participants don't need to sync daily
* Combine health data with [prompts](/prompts/overview) for rich multi-modal datasets
* Ensure participants understand which health data will be collected — include this in your [onboarding consent](/onboarding/full-text-overview)
* Apple Health data is read-only — Fusion never writes to HealthKit


# Welcome to NeuroFusion
Source: https://docs.usefusion.ai/introduction

Guides, resources, and references for running research studies with NeuroFusion.

NeuroFusion is a platform for researchers to design studies, collect behavioral and brain data from participants, and analyze results — all in one place. Whether you're running a cognitive experiment, deploying daily surveys, or tracking health metrics with wearables, NeuroFusion handles data collection, consent, billing, and collaboration so you can focus on your research.

<Note>
  **Spring 2026 Updates**

  * **Multi-experiment quests** — bundle multiple jsPsych experiments in one quest with defined ordering
  * **Improved experiment editor** — Monaco code editor with live preview and media uploads (images, audio, video)
  * **Mobile experiment runner** — participants can now complete experiments in the Fusion mobile app
  * **Organizations** — group quests under teams with 18 granular permissions and shared billing
  * **Billing & credits** — transparent per-action pricing, credit transfers between orgs
  * **Prolific compatibility** — use quest URLs directly as Prolific study URLs; participant IDs are captured automatically
  * **Onboarding flows** — full-text consent overviews, question guards to screen participants, kiosk mode for shared devices
  * **Conditional prompt notifications** — trigger prompts based on answers to previous prompts or onboarding questions
</Note>

<Frame>
  <img alt="NeuroFusion dashboard with sidebar navigation and quests table" />
</Frame>

## How to Get Started

1. **Sign up** at [usefusion.ai](https://usefusion.ai) and create your account
2. **Create or join an Organization** to manage your team, quests, and billing
3. **Create a Quest** — add prompts for recurring data collection and experiments for interactive tasks
4. **Configure Onboarding** — set up consent overviews and eligibility screening with question guards
5. **Publish & share** — send the quest link directly, via QR code, or use it as a Prolific study URL
6. **Monitor** — track participant responses, billing, and data in your org dashboard

## Explore the Docs

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Go from sign-up to your first published quest in 5 minutes.
  </Card>

  <Card title="Quests" icon="scroll" href="/quests/overview">
    Understand quests — the containers for your prompts, experiments, and onboarding.
  </Card>

  <Card title="Prompts" icon="bell" href="/prompts/overview">
    Configure recurring questions with scheduling, response types, and categories.
  </Card>

  <Card title="Onboarding & Consent" icon="clipboard-check" href="/onboarding/overview">
    Set up consent flows, eligibility screening, and question guards.
  </Card>

  <Card title="Experiments" icon="flask" href="/experiments/overview">
    Build jsPsych experiments with the code editor, upload media, and run on mobile.
  </Card>

  <Card title="Organizations" icon="building" href="/organizations/overview">
    Create teams with granular permissions and shared billing.
  </Card>

  <Card title="Billing & Credits" icon="credit-card" href="/billing/overview">
    Purchase credits, track expenses, and fund collaborator organizations.
  </Card>

  <Card title="Integrations" icon="plug" href="/integrations/prolific">
    Connect with Prolific, EEG brain interfaces, and wearable devices.
  </Card>
</CardGroup>


# API Reference
Source: https://docs.usefusion.ai/model-apis/api-reference

Endpoint reference for the ZUNA EEG model inference API

# API Reference

All endpoints are available through the NeuroFusion backend at `https://usefusion.ai/api/eeg-models/` or directly on the GPU server at `https://models.usefusion.ai/`.

## Health Check

<Tip>Check GPU availability before sending inference requests.</Tip>

```
GET /api/eeg-models/health
```

**Response (GPU running):**

```json theme={null}
{
  "status": "ok",
  "model": "zuna",
  "zuna_available": true,
  "gpu_name": "NVIDIA A100 80GB PCIe"
}
```

**Response (VM deallocated):**

```json theme={null}
{
  "status": "unavailable",
  "vm": { "status": "deallocated" },
  "message": "GPU VM is not running"
}
```

## Wake GPU VM

Start the GPU VM if it's deallocated. The VM takes \~90 seconds to boot.

```
POST /api/eeg-models/wake
```

**Response:**

```json theme={null}
{
  "status": "starting",
  "message": "GPU VM is starting up",
  "estimatedWaitSeconds": 90
}
```

## VM Status

```
GET /api/eeg-models/vm-status
```

**Response:**

```json theme={null}
{
  "status": "running",
  "vmStatus": "running"
}
```

Possible `vmStatus` values: `running`, `deallocated`, `starting`, `stopping`, `deallocating`

## Run ZUNA Inference

<Warning>If the GPU VM is deallocated, this returns HTTP 202 with a retry instruction. Check health first or handle the 202 response.</Warning>

```
POST /api/eeg-models/inference
```

### Request Body

```json theme={null}
{
  "task": "denoise",
  "eeg": {
    "csv_content": "timestamp,CP3,C3,F5,...\n1700000000,12.5,-3.2,8.1,...\n...",
    "device_type": "neurosity",
    "sfreq": 256
  },
  "output_format": "json"
}
```

| Field               | Type      | Required | Description                                      |
| ------------------- | --------- | -------- | ------------------------------------------------ |
| `task`              | string    | ✅        | `"denoise"`, `"reconstruct"`, or `"upsample"`    |
| `eeg.csv_content`   | string    | ✅        | Raw CSV data with channel columns (values in µV) |
| `eeg.device_type`   | string    | ✅        | `"neurosity"`, `"muse"`, or `"auto"`             |
| `eeg.sfreq`         | number    |          | Sampling frequency in Hz (default: 256)          |
| `eeg.channel_names` | string\[] |          | Override auto-detected channel names             |
| `output_format`     | string    |          | `"json"` (default) or `"csv"`                    |
| `target_channels`   | string\[] |          | For `upsample` task: target channel names        |
| `bad_channels`      | string\[] |          | Channels to exclude from processing              |
| `gpu_device`        | number    |          | GPU device index (default: 0)                    |

### Response (JSON format)

```json theme={null}
{
  "task": "denoise",
  "model": "zuna",
  "input": {
    "channel_names": ["CP3", "C3", "F5", "PO3", "PO4", "F6", "C4", "CP4"],
    "n_channels": 8,
    "sfreq": 256.0,
    "duration_seconds": 5.996,
    "n_samples": 1536
  },
  "output": {
    "channel_names": ["CP3", "C3", "F5", "PO3", "PO4", "F6", "C4", "CP4"],
    "n_channels": 8,
    "sfreq": 256.0,
    "duration_seconds": 4.996,
    "n_samples": 1280,
    "format": "json"
  },
  "channel_data": {
    "CP3": [1.23, -0.45, 2.67, ...],
    "C3": [0.89, 1.34, -0.78, ...],
    ...
  }
}
```

### Response (CSV format)

```json theme={null}
{
  "task": "denoise",
  "model": "zuna",
  "input": { ... },
  "output": {
    ...
    "format": "csv",
    "csv_content": "timestamp_s,CP3,C3,F5,...\n0.0,1.23,0.89,...\n..."
  }
}
```

### Response (HTTP 202 — GPU warming up)

```json theme={null}
{
  "status": "warming_up",
  "vmAction": "starting",
  "message": "GPU VM is starting up. Please retry in ~90 seconds.",
  "estimatedWaitSeconds": 90,
  "retryAfter": 15
}
```

## CSV Input Format

Your CSV should have columns for each EEG channel. An optional `timestamp` column is supported but not required.

### Neurosity Crown

```csv theme={null}
timestamp,CP3,C3,F5,PO3,PO4,F6,C4,CP4
1700000000.000,12.5,-3.2,8.1,5.6,-7.3,2.1,9.4,-1.8
1700000000.004,13.1,-2.8,7.9,5.2,-6.9,2.5,9.1,-2.1
...
```

### Muse

```csv theme={null}
timestamp,TP9,AF7,AF8,TP10
1700000000.000,15.2,-4.1,6.3,-8.7
1700000000.004,14.8,-3.9,6.1,-8.2
...
```

<Note>
  **Important**: Values should be in **microvolts (µV)**. The API automatically converts to volts for MNE processing and back to µV for the output.
</Note>

## Error Responses

| Status | Meaning                                                           |
| ------ | ----------------------------------------------------------------- |
| 400    | Invalid request (missing fields, bad task, insufficient duration) |
| 404    | Dataset not found (for analyze-dataset endpoint)                  |
| 500    | Model inference failed                                            |
| 502    | GPU server unreachable                                            |
| 503    | EEG Models API not configured                                     |

## Code Examples

### JavaScript/TypeScript

```typescript theme={null}
import { api } from "~/config/api";

const response = await api.post("/eeg-models/inference", {
  task: "denoise",
  eeg: {
    csv_content: csvString,
    device_type: "neurosity",
    sfreq: 256,
  },
  output_format: "json",
});

const { channel_data, output } = response.data;
console.log(`Denoised ${output.n_channels} channels, ${output.n_samples} samples`);
```

### Python

```python theme={null}
import requests

response = requests.post("https://models.usefusion.ai/inference/zuna", json={
    "task": "denoise",
    "eeg": {
        "csv_content": open("recording.csv").read(),
        "device_type": "muse",
        "sfreq": 256,
    },
    "output_format": "json",
})

result = response.json()
print(f"Channels: {result['output']['channel_names']}")
print(f"Samples: {result['output']['n_samples']}")
```

### cURL

```bash theme={null}
curl -X POST https://models.usefusion.ai/inference/zuna \
  -H "Content-Type: application/json" \
  -d '{
    "task": "denoise",
    "eeg": {
      "csv_content": "timestamp,TP9,AF7,AF8,TP10\n...",
      "device_type": "muse",
      "sfreq": 256
    },
    "output_format": "json"
  }'
```


# Devices & Data Formats
Source: https://docs.usefusion.ai/model-apis/devices-and-formats

Supported EEG devices, channel mappings, and data format specifications

# Devices & Data Formats

## Supported Devices

### Neurosity Crown

The [Neurosity Crown](https://neurosity.co/) is an 8-channel consumer EEG headset.

| Property      | Value                              |
| ------------- | ---------------------------------- |
| Channels      | 8                                  |
| Channel Names | CP3, C3, F5, PO3, PO4, F6, C4, CP4 |
| Sample Rate   | 256 Hz                             |
| Montage       | International 10-20 subset         |
| Connection    | WiFi (SDK) or Bluetooth            |

**Channel locations** map to the standard 10-05 montage:

* **Frontal**: F5, F6 (lateral frontal)
* **Central**: C3, C4 (motor cortex, left/right)
* **Parietal**: CP3, CP4 (centro-parietal)
* **Occipital**: PO3, PO4 (parieto-occipital)

### Muse (Muse 2, Muse S)

The [Muse](https://choosemuse.com/) headbands are 4-channel consumer EEG devices.

| Property      | Value                         |
| ------------- | ----------------------------- |
| Channels      | 4                             |
| Channel Names | TP9, AF7, AF8, TP10           |
| Sample Rate   | 256 Hz                        |
| Montage       | International 10-20 subset    |
| Connection    | Bluetooth (Web Bluetooth API) |

**Channel locations:**

* **Temporal**: TP9, TP10 (behind ears)
* **Frontal**: AF7, AF8 (forehead, above eyebrows)

## Data Formats

### Input: Device CSV

The API accepts raw CSV data as a string. The CSV should contain:

* A **header row** with channel names (and optionally a timestamp column)
* **Data rows** with values in **microvolts (µV)**

```csv theme={null}
timestamp,TP9,AF7,AF8,TP10
1700000000.000,15.2,-4.1,6.3,-8.7
1700000000.004,14.8,-3.9,6.1,-8.2
```

<Tip>
  The timestamp column is optional. If present, it's ignored during processing — ZUNA uses the sample rate to reconstruct timing. But it's useful for aligning with other data sources.
</Tip>

### Output: JSON Channel Data

When `output_format: "json"`, the response includes a `channel_data` object with per-channel arrays:

```json theme={null}
{
  "channel_data": {
    "TP9": [1.23, -0.45, 2.67, ...],
    "AF7": [0.89, 1.34, -0.78, ...],
    "AF8": [2.01, 0.56, 1.89, ...],
    "TP10": [-0.34, 1.12, -0.23, ...]
  }
}
```

Each array contains `output.n_samples` values in **microvolts (µV)**.

### Output: CSV

When `output_format: "csv"`, the response includes `output.csv_content`:

```csv theme={null}
timestamp_s,TP9,AF7,AF8,TP10
0.000000,1.230000,-0.450000,2.670000,...
0.003906,0.890000,1.340000,-0.780000,...
```

The `timestamp_s` column contains time in seconds from the start of the recording.

## ZUNA Processing Details

### What ZUNA Does

ZUNA (by [Zyphra](https://huggingface.co/Zyphra/ZUNA)) is a foundation model for EEG signal processing. It was trained on large-scale EEG datasets to understand the structure of brain signals.

**Denoising** removes:

* Eye blink artifacts (frontal channels)
* Muscle artifacts (jaw clenching, head movement)
* Environmental noise (50/60 Hz line noise)
* Electrode contact noise

While preserving:

* Neural oscillations (alpha, beta, theta, gamma, delta)
* Event-related potentials
* Frequency-specific power patterns

### Processing Pipeline

1. **CSV → FIF**: Convert CSV to MNE RawArray with standard 10-05 montage
2. **Preprocessing**: Resample to 256 Hz, bandpass filter, epoch into 5-second segments, normalize (std = 0.1)
3. **Inference**: Run ZUNA model on GPU (diffusion-based denoising)
4. **Post-processing**: Convert output tensors back to FIF, then to CSV/JSON

### Key Constraints

| Constraint         | Value          | Reason                           |
| ------------------ | -------------- | -------------------------------- |
| Minimum duration   | 5 seconds      | ZUNA epochs are 5s long          |
| Recommended buffer | 1 second       | The API trims partial epochs     |
| Sample rate        | Any → 256 Hz   | ZUNA resamples internally        |
| Channel names      | Standard 10-20 | Required for montage positioning |
| Output length      | ≤ Input        | Partial final epochs are dropped |

### Example: Duration Math

| Input Duration | Epochs | Output Duration |
| -------------- | ------ | --------------- |
| 5.0s           | 1      | 5.0s            |
| 6.0s           | 1      | 5.0s            |
| 10.0s          | 2      | 10.0s           |
| 12.5s          | 2      | 10.0s           |
| 30.0s          | 6      | 30.0s           |


# Model APIs Overview
Source: https://docs.usefusion.ai/model-apis/overview

AI-powered EEG analysis using foundation models hosted on NeuroFusion GPU infrastructure

# Model APIs

NeuroFusion hosts EEG foundation models on GPU infrastructure for AI-powered brain signal analysis. These models run on **models.usefusion.ai** — an NVIDIA A100 GPU server with auto-sleep/wake to minimize costs.

## Available Models

| Model    | Task          | Description                                                                                |
| -------- | ------------- | ------------------------------------------------------------------------------------------ |
| **ZUNA** | `denoise`     | Remove artifacts (eye blinks, muscle, environmental noise) while preserving neural signals |
| **ZUNA** | `reconstruct` | Reconstruct missing or corrupted EEG channels                                              |
| **ZUNA** | `upsample`    | Expand from fewer channels to a standard montage                                           |

## Supported Devices

| Device          | Channels                               | Sample Rate |
| --------------- | -------------------------------------- | ----------- |
| Neurosity Crown | 8 (CP3, C3, F5, PO3, PO4, F6, C4, CP4) | 256 Hz      |
| Muse (2, S)     | 4 (TP9, AF7, AF8, TP10)                | 256 Hz      |

## How It Works

```
Your EEG Device → CSV data → NeuroFusion API → ZUNA Model (GPU) → Cleaned signal → Your app
```

### Pipeline Detail

1. **CSV Input** — Raw EEG data from your device (values in µV)
2. **Preprocessing** — Automatic conversion to MNE `.fif` format with standard 10-05 montage
3. **ZUNA Processing** — Resampling to 256 Hz, filtering, epoching into 5-second segments, normalization, then GPU inference
4. **Output** — Denoised signal returned as JSON (per-channel arrays) or CSV

### Minimum Requirements

* **Recording duration**: At least **6 seconds** (5s minimum for one ZUNA epoch + buffer)
* **Channels**: 4+ EEG channels with standard 10-20 names
* **Format**: CSV with channel columns and optional timestamp column

## Architecture

```
┌─────────────┐     ┌──────────────────┐     ┌───────────────────────┐
│  Frontend    │────▶│  Backend Server   │────▶│  GPU VM               │
│  /recordings │     │  /api/eeg-models  │     │  models.usefusion.ai  │
│  /analysis   │     │  (auto-wake VM)   │     │  NVIDIA A100 80GB     │
└─────────────┘     └──────────────────┘     │  ZUNA model           │
                                              └───────────────────────┘
```

The backend server automatically manages the GPU VM:

* **Auto-wake**: If the VM is deallocated, the first request starts it and returns HTTP 202 with retry guidance
* **Auto-sleep**: VM deallocates after 30 minutes of inactivity to minimize costs
* **Health checks**: `/api/eeg-models/health` shows GPU status and model availability

## Using the Platform

There are two ways to use ZUNA on NeuroFusion:

### 1. Recordings Page (`/recordings`)

* **Live Recording**: Connect your Neurosity Crown or Muse headband, record EEG, then denoise with one click
* **Upload CSV**: Drop in a CSV file from a previous recording
* **View Results**: See denoised signal preview and download cleaned CSV

### 2. Analysis Page (`/analysis`)

* **Upload & Analyze**: Upload CSV, choose ZUNA AI Denoising or other analysis types
* **Side-by-Side**: View raw vs denoised signals in a split comparison
* **Download**: Export denoised data as CSV for further analysis

Both pages are linked — you can record on `/recordings`, denoise, then view detailed results on `/analysis`.


# Full-Text Overview
Source: https://docs.usefusion.ai/onboarding/full-text-overview

Display rich consent content that participants must acknowledge before proceeding.

The full-text overview is the participant-facing **Study Overview / Consent Document** shown as the first step of onboarding, before any questions. It's designed for informed consent language, study descriptions, and data usage policies.

## How It Works

1. When a participant opens a quest with a configured overview, they see the content rendered before any onboarding questions
2. Below the content is a **mandatory acknowledgment checkbox**: *"I have read and understand the information above"*
3. The **Continue** button is disabled until the checkbox is checked
4. After acknowledging, participants proceed to onboarding questions (if any) or directly to joining the quest

## Configuration

The overview is configured in the quest editor's onboarding section:

* **Content field** — enter or paste rich HTML content
* Stored in `onboardingConfig.content` as an HTML string
* If left empty, the overview step is skipped entirely

## What to Include

A good overview should cover:

* **Study title and principal investigator** — who is running this study
* **Purpose** — what the study is investigating
* **What's expected** — duration, tasks (prompts, experiments), time commitment
* **Data usage** — how data will be collected, stored, and used
* **Privacy** — who has access to the data, how long it's retained
* **Risks and benefits** — any potential risks and what participants gain
* **Voluntary participation** — participants can withdraw at any time
* **Contact information** — who to reach out to with questions

<Tip>
  Keep language accessible — aim for an 8th-grade reading level. Avoid jargon where possible and define technical terms when you must use them.
</Tip>

## Example

Here's an example of content you might put in the overview:

```html theme={null}
<h2>Informed Consent — Daily Mood Study</h2>
<p><strong>Principal Investigator:</strong> Dr. Jane Smith, Department of Psychology</p>

<h3>Purpose</h3>
<p>This study examines daily mood patterns and their relationship to sleep quality
over a 4-week period.</p>

<h3>What You'll Do</h3>
<ul>
  <li>Answer 3 short prompts each day (takes ~2 minutes)</li>
  <li>Complete one 5-minute cognitive experiment at the start and end of the study</li>
</ul>

<h3>Data & Privacy</h3>
<p>Your responses are stored securely on encrypted servers. Only the research team
has access to identified data. Published results will use anonymized, aggregate data only.</p>

<h3>Contact</h3>
<p>Questions? Email <a href="mailto:study@example.com">study@example.com</a></p>
```

## Notes

* The overview content supports any valid HTML — you can include headings, lists, links, bold text, etc.
* Content is rendered inside a `prose` container for clean typography
* The overview is optional — if you don't need a consent form, you can skip it
* If you need to re-show the overview to returning participants (e.g., on shared devices), enable [Kiosk Mode](/onboarding/kiosk-mode)


# Kiosk Mode
Source: https://docs.usefusion.ai/onboarding/kiosk-mode

Re-show the onboarding flow every session for shared devices and in-lab setups.

Kiosk mode is an onboarding setting that **re-shows the full onboarding flow every session**, even for participants who have already joined the quest. It's designed for shared devices where multiple people use the same browser or app.

## Default Behavior (Kiosk Off)

When kiosk mode is **disabled** (the default):

1. A participant opens the quest URL for the first time → sees onboarding → joins the quest
2. The same participant opens the quest URL again → **skips onboarding** → goes directly to quest content

## Kiosk Behavior (Kiosk On)

When kiosk mode is **enabled**:

1. A participant opens the quest URL → sees onboarding → joins the quest
2. The same participant (or a different person on the same device) opens the quest URL again → **sees onboarding again** → must complete the overview acknowledgment and questions every time

## When to Use Kiosk Mode

| Scenario                                          | Why                                                                           |
| ------------------------------------------------- | ----------------------------------------------------------------------------- |
| **Lab computers** shared by multiple participants | Each participant needs to see the consent form and answer screening questions |
| **Conference or event demo stations**             | Walk-up stations where different people try the quest                         |
| **Clinical settings** with shared tablets         | Patients use the same device in a waiting room or clinic                      |
| **Classroom studies**                             | Students share computers in a lab setting                                     |

## How to Enable

1. Open your quest in the editor
2. Navigate to the onboarding section
3. Toggle **Kiosk Mode** on

The setting is stored in `onboardingConfig.isKiosk`.

## Important Notes

<Warning>
  Kiosk mode only affects the onboarding flow. It does **not** log out the user or reset other session state. If you need full session isolation on shared devices, consider additional measures like browser private/incognito mode.
</Warning>

* The full-text overview (if configured) is re-shown with the acknowledgment checkbox
* All onboarding questions (if any) are re-shown and must be answered again
* Question guard validation runs again every session
* Onboarding responses are saved as a new dataset entry each time


# Onboarding & Consent Overview
Source: https://docs.usefusion.ai/onboarding/overview

Configure the multi-step gated flow participants complete before joining your quest.

The onboarding system is a **multi-step gated flow** that participants complete before they can access a quest's prompts and experiments. It handles informed consent, eligibility screening, and baseline intake before the participant is enrolled into the quest.

<Frame>
  <img alt="Welcome to NeuroFusion dialog showing platform features and Get Started button" />
</Frame>

## Onboarding Flow

When a participant opens a quest URL, here's what happens:

```
Participant opens quest URL
  → Check if already joined
    → Already joined (not kiosk mode) → Skip to quest content
    → Already joined (kiosk mode) → Re-show onboarding
    → Not joined → Continue to onboarding
  → Step 1: Study Overview / Consent Document (if configured)
    → Must check "I have read and understand" → Continue
  → Step 2: Onboarding questions (if any)
    → Server-side validation of question guards
      → Failed → Show rejection messages, block access
      → Passed → Continue
  → Save onboarding responses (free — not billed)
  → Join quest (billed to org — see [Pricing](https://usefusion.ai/pricing))
  → Quest content (prompts, experiments)
```

## Components

The onboarding system has four configurable components:

| Component                                            | Required? | Description                                                    |
| ---------------------------------------------------- | --------- | -------------------------------------------------------------- |
| [Full-Text Overview](/onboarding/full-text-overview) | Optional  | Study overview / consent content with mandatory acknowledgment |
| [Onboarding Questions](/onboarding/questions)        | Optional  | Screening questions (5 response types supported)               |
| [Question Guards](/onboarding/question-guards)       | Optional  | Server-side validation rules to block ineligible participants  |
| [Kiosk Mode](/onboarding/kiosk-mode)                 | Optional  | Re-show onboarding every session for shared devices            |

A quest can have **none, one, or all** of these configured. If neither the overview nor questions are set, participants join the quest directly.

## Key Facts

* Onboarding responses are saved as a dataset with type `onboarding_responses`
* Onboarding responses are **free** — they are not billed
* Question guard validation is **server-side** — it cannot be bypassed
* Onboarding response types match prompt response types: `text`, `yesno`, `number`, `numberRange`, `customOptions`
* After onboarding passes, the participant joins the quest and appears in the participant roster for researcher operations

## Explore

<CardGroup>
  <Card title="Full-Text Overview" icon="file-lines" href="/onboarding/full-text-overview">
    Informed consent language shown before questions.
  </Card>

  <Card title="Questions" icon="circle-question" href="/onboarding/questions">
    Screening questions with 5 response types.
  </Card>

  <Card title="Question Guards" icon="shield-check" href="/onboarding/question-guards">
    Server-side eligibility validation rules.
  </Card>

  <Card title="Kiosk Mode" icon="display" href="/onboarding/kiosk-mode">
    Re-show onboarding for shared devices.
  </Card>
</CardGroup>


# Question Guards
Source: https://docs.usefusion.ai/onboarding/question-guards

Server-side validation rules that screen participants for eligibility before they can join a quest.

Question guards (also called consent gates or validation rules) are **server-side validation rules** on onboarding questions. They determine whether a participant is eligible to join a quest based on their answers.

## How They Work

1. Participant fills out onboarding questions
2. Answers are sent to the server: `POST /quest/validate-onboarding`
3. Every question with a guard is evaluated
4. If **any** guard fails → participant is blocked with rejection messages
5. If **all** guards pass → participant can proceed to join

<Warning>
  Guard validation is **server-side** — it cannot be bypassed by participants.
</Warning>

## Guard Configuration

Each guard has three fields:

| Field                 | Type   | Description                                                                                                                     |
| --------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------- |
| **Operator**          | string | The comparison operator (see table below)                                                                                       |
| **Value**             | string | The expected value. Single value for `eq/neq/gt/gte/lt/lte`. Comma-separated for `in/not_in`.                                   |
| **Rejection Message** | string | Custom message shown to the participant if they fail. Default: *"Your response does not meet the requirements for this study."* |

## Available Operators

Which operators are available depends on the question's response type:

| Response Type   | Available Operators                                                                                           |
| --------------- | ------------------------------------------------------------------------------------------------------------- |
| `text`          | `eq` (Equals), `neq` (Not equals)                                                                             |
| `yesno`         | `eq` (Equals), `neq` (Not equals)                                                                             |
| `number`        | `eq`, `neq`, `gt` (Greater than), `gte` (Greater than or equal), `lt` (Less than), `lte` (Less than or equal) |
| `numberRange`   | `eq`, `neq`, `gt`, `gte`, `lt`, `lte`                                                                         |
| `customOptions` | `eq` (Equals), `neq` (Not equals), `in` (Is one of), `not_in` (Is not one of)                                 |

### Operator Details

| Operator | Label                 | Behavior                                                             |
| -------- | --------------------- | -------------------------------------------------------------------- |
| `eq`     | Equals                | Case-insensitive exact match                                         |
| `neq`    | Not equals            | Case-insensitive non-match                                           |
| `gt`     | Greater than          | Parses as float: answer > value                                      |
| `gte`    | Greater than or equal | Parses as float: answer ≥ value                                      |
| `lt`     | Less than             | Parses as float: answer \< value                                     |
| `lte`    | Less than or equal    | Parses as float: answer ≤ value                                      |
| `in`     | Is one of             | Value is comma-separated. Answer (lowercased) must be in the set     |
| `not_in` | Is not one of         | Value is comma-separated. Answer (lowercased) must NOT be in the set |

<Info>
  When you change a question's response type, the operator resets to the first valid option if the current operator is no longer available for the new type.
</Info>

## Rejection Behavior

When a participant fails validation:

* **Per-question**: Each failed question shows its rejection message in a **red inline box** below the question
* **Global**: A **yellow warning banner** appears: *"You do not meet the eligibility criteria for this quest."*
* The participant **cannot proceed** and cannot join the quest

## Adding a Guard

1. Open a quest and navigate to the onboarding section
2. Click on an onboarding question (or add a new one)
3. Check **"Add validation rule (consent gate)"**
4. Select an **operator** from the dropdown
5. Enter the expected **value**
6. Optionally customize the **rejection message**

## Worked Examples

### Must Be 18 or Older

| Field             | Value                                                             |
| ----------------- | ----------------------------------------------------------------- |
| Question          | "How old are you?"                                                |
| Response type     | `number`                                                          |
| Operator          | `gte`                                                             |
| Value             | `18`                                                              |
| Rejection message | "You must be at least 18 years old to participate in this study." |

**Behavior**: If a participant enters 17, they see the rejection message and cannot join.

### Must Consent to Data Collection

| Field             | Value                                                                         |
| ----------------- | ----------------------------------------------------------------------------- |
| Question          | "Do you consent to your data being collected and used for research purposes?" |
| Response type     | `yesno`                                                                       |
| Operator          | `eq`                                                                          |
| Value             | `Yes`                                                                         |
| Rejection message | "Consent is required to participate in this study."                           |

**Behavior**: If a participant selects "No", they see the rejection message and cannot join.

### Must Be in Target Demographic

| Field             | Value                                                            |
| ----------------- | ---------------------------------------------------------------- |
| Question          | "What is your occupation?"                                       |
| Response type     | `customOptions`                                                  |
| Options           | Student, Professional, Retired, Other                            |
| Operator          | `in`                                                             |
| Value             | `Student,Professional`                                           |
| Rejection message | "This study is only open to students and working professionals." |

**Behavior**: If a participant selects "Retired" or "Other", they see the rejection message and cannot join.

### Exclude a Specific Condition

| Field             | Value                                                                                                                |
| ----------------- | -------------------------------------------------------------------------------------------------------------------- |
| Question          | "Do you have a history of epilepsy?"                                                                                 |
| Response type     | `yesno`                                                                                                              |
| Operator          | `eq`                                                                                                                 |
| Value             | `No`                                                                                                                 |
| Rejection message | "Due to the nature of the visual stimuli in this study, participants with a history of epilepsy cannot participate." |

**Behavior**: If a participant selects "Yes", they see the rejection message and cannot join.


# Onboarding Questions
Source: https://docs.usefusion.ai/onboarding/questions

Add screening questions to collect eligibility data and baseline information before participants join.

Onboarding questions are pre-join screening questions shown to participants after the [full-text overview](/onboarding/full-text-overview) (if configured). Use them for eligibility screening, demographic collection, and baseline data.

## Question Fields

Each onboarding question has:

| Field               | Required?                | Description                                                                  |
| ------------------- | ------------------------ | ---------------------------------------------------------------------------- |
| **Question text**   | ✅ Yes                    | The question shown to the participant                                        |
| **Response type**   | ✅ Yes                    | How participants answer (see table below)                                    |
| **Options**         | For `customOptions` only | Array of option strings                                                      |
| **Required**        | —                        | Whether the question must be answered (defaults to `true` for new questions) |
| **Validation rule** | Optional                 | A [question guard](/onboarding/question-guards) for eligibility screening    |

## Response Types

Onboarding questions support the same 5 response types as prompts:

| Response Type   | UI Rendering                    | Notes            |
| --------------- | ------------------------------- | ---------------- |
| `text`          | Text input field                | Free-form answer |
| `yesno`         | Two radio buttons: "Yes" / "No" | Binary choice    |
| `number`        | Numeric input field             | Numeric answer   |
| `numberRange`   | Numeric input with bounds       | Bounded numeric  |
| `customOptions` | Radio buttons **or** checkboxes | See below        |

### Custom Options Rendering

The rendering of `customOptions` depends on whether a [question guard](/onboarding/question-guards) is set:

* If the guard uses `in` or `not_in` → **checkboxes** (multi-select), answer stored as comma-separated values
* Otherwise → **radio buttons** (single-select)

<Warning>
  Options in onboarding questions are entered as **comma-separated** values (e.g., `Student, Professional, Retired, Other`). This is different from prompt custom options, which use **semicolons**.
</Warning>

## Adding Questions

1. Open your quest in the editor
2. Navigate to the onboarding section
3. Click **Add Question**
4. Enter the question text
5. Select a response type
6. If using `customOptions`, enter the options
7. Optionally toggle **Required** (on by default)
8. Optionally add a [validation rule (question guard)](/onboarding/question-guards)

## Validation

**Client-side**: All required questions must have a non-empty, trimmed answer before the form can be submitted.

**Server-side**: If any question has a [question guard](/onboarding/question-guards), the answers are validated server-side. Failed validations show rejection messages and block the participant from joining.

## Data Storage

* Onboarding responses are saved as a dataset with type `onboarding_responses`
* Source is tagged as `web` or `mobile` depending on where the participant completed onboarding
* Onboarding responses are **free** — they are not billed

<Info>
  Onboarding responses are submitted **before** the participant joins the quest. This is different from prompt responses, which are submitted after joining.
</Info>

## Example

A typical eligibility screening setup:

| Question                                   | Type                                              | Guard                          |
| ------------------------------------------ | ------------------------------------------------- | ------------------------------ |
| "How old are you?"                         | `number`                                          | Must be ≥ 18                   |
| "Do you consent to participate?"           | `yesno`                                           | Must equal "Yes"               |
| "What is your primary language?"           | `customOptions` (English, Spanish, French, Other) | Must be "English" or "Spanish" |
| "Describe any relevant medical conditions" | `text`                                            | None (informational only)      |


# Creating an Organization
Source: https://docs.usefusion.ai/organizations/creating-an-org

Create a new organization to start managing quests and team members.

Creating an organization is the first step to running quests on Fusion. Every quest must belong to an organization, and creating one takes just a few seconds.

## Required Fields

| Field             | Required | Description                                          |
| ----------------- | -------- | ---------------------------------------------------- |
| **Name**          | ✅ Yes    | The display name of your organization                |
| **Billing Email** | ✅ Yes    | Email address for billing notifications and receipts |
| **Description**   | Optional | A short description of the organization              |

## What Happens on Creation

When you create an organization:

1. A **unique slug** is auto-generated from your org name
   * Lowercased, non-alphanumeric characters replaced with hyphens
   * Truncated to 50 characters
   * If the slug already exists, a number suffix is appended (`-1`, `-2`, etc.)
2. You receive **free starter credits** as a welcome bonus
3. You are added as the **first admin** with full permissions

## Step by Step

1. Navigate to the **Organizations** section in the dashboard
2. Click **Create Organization**
3. Enter a **name** for your organization
4. Enter a **billing email** — this is where billing notifications and receipts will be sent
5. Optionally add a **description**
6. Click **Create**

<Frame>
  <img alt="Organizations page showing empty state with Create Your First Organization button" />
</Frame>

<Info>
  You can create multiple organizations — for example, one per research lab, project, or study.
</Info>

## After Creation

Once your organization exists, you can:

* **Add members** — search for existing Fusion users and invite them to your org ([Members & Permissions](/organizations/members-and-permissions))
* **Create quests** — the organization selector will appear in the quest editor
* **Purchase credits** — add funds to run studies ([Purchasing Credits](/billing/purchasing-credits))

## Slug and Identity

Your organization's slug appears in URLs and is used internally to identify the org. You cannot change the slug after creation, so choose a clear, descriptive name.

**Examples:**

| Name                   | Generated Slug           |
| ---------------------- | ------------------------ |
| Smith Neuroscience Lab | `smith-neuroscience-lab` |
| UofT Psych Research    | `uoft-psych-research`    |
| My First Study         | `my-first-study`         |


# Managing Quests
Source: https://docs.usefusion.ai/organizations/managing-quests

Assign quests to organizations and transfer them between orgs.

Every quest in Fusion belongs to an organization. The organization determines who can edit the quest, where billing is charged, and who has access to collected data.

## Creating a Quest in an Organization

When you create or edit a quest, the **organization selector** appears in the quest form:

* Select which organization the quest belongs to
* All billing for the quest (publishing, data collection, etc.) is charged to that organization's credits
* Members with the appropriate permissions can view and edit the quest

<Info>
  Quests **must** belong to an organization. The organization selector is required when creating a quest.
</Info>

Helper text in the editor reads: *"Quests must belong to an organization. Billing and permissions are managed at the org level."*

## Quest Ownership Rules

| Action              | Required Permission              |
| ------------------- | -------------------------------- |
| Create a quest      | `quest:create` in the target org |
| Edit any quest      | `quest:update_any` or `admin`    |
| Edit your own quest | `quest:update_own`               |
| Publish a quest     | `quest:publish`                  |
| Delete a quest      | `quest:delete`                   |

## Transferring Quests

You can transfer a quest from one organization to another. This is useful when:

* A quest needs to be handed off to another team
* An organization is being reorganized
* A study is moving between labs or departments

### How to Transfer

1. Open the quest you want to transfer
2. Use the **Transfer Quest** option
3. Select the destination organization
4. Confirm the transfer

### Transfer Rules

| Scenario                          | Requirement                                            |
| --------------------------------- | ------------------------------------------------------ |
| Transfer **from** an organization | `quest:create` or `admin` permission in the source org |
| Transfer **to** an organization   | `quest:create` or `admin` permission in the target org |

<Warning>
  Transferring a quest moves all billing responsibility to the destination organization. Existing expenses stay with the original org, but future charges go to the new org.
</Warning>

## Bulk Transfers

A bulk transfer tool is available for moving multiple quests at once — useful during lab onboarding or when migrating between organizations.

## Viewing Organization Quests

Each organization has a dashboard showing all quests owned by that org, including:

* Quest name and status (draft / published)
* Number of participants
* Total expenses
* Last updated date


# Members & Permissions
Source: https://docs.usefusion.ai/organizations/members-and-permissions

Add team members and assign granular permissions across 5 categories.

Organizations support multiple members, each with a customizable set of permissions. This lets you control exactly who can create quests, spend credits, access data, and more.

## Adding Members

Members are added by **searching for existing Fusion users** by username:

1. Navigate to your organization's settings
2. Go to the **Members** tab
3. Search for a user by username
4. Select permissions to grant
5. Click **Add Member**

<Info>
  The user must already have a Fusion account. There is no email invitation flow — add members by their existing username.
</Info>

### Default Permissions for New Members

When you add a member, they start with these permissions:

* `quest:create` — Create Quest
* `quest:update_own` — Update Own Quests
* `credits:view_balance` — View Credit Balance
* `data:view` — View Data

## The 18 Permissions

Permissions are organized into **5 categories**:

### Administrator

| Permission | Description                                                                       | Sensitive |
| ---------- | --------------------------------------------------------------------------------- | --------- |
| `admin`    | Full administrator access — can do everything, including granting admin to others | ✅         |

### Organization Management

| Permission            | Description                                | Sensitive |
| --------------------- | ------------------------------------------ | --------- |
| `org:manage_members`  | Add and remove members, change permissions | ✅         |
| `org:manage_settings` | Edit organization name and settings        | ❌         |
| `org:delete`          | Delete the entire organization             | ✅         |

### Quest Management

| Permission               | Description                        | Sensitive |
| ------------------------ | ---------------------------------- | --------- |
| `quest:create`           | Create new quests                  | ❌         |
| `quest:update_any`       | Edit any quest in the organization | ❌         |
| `quest:update_own`       | Edit quests you created            | ❌         |
| `quest:delete`           | Delete quests                      | ✅         |
| `quest:publish`          | Publish and unpublish quests       | ❌         |
| `quest:add_participants` | Add participants to quests         | ❌         |

### Credit Management

| Permission             | Description                             | Sensitive |
| ---------------------- | --------------------------------------- | --------- |
| `credits:view_balance` | View the organization's credit balance  | ❌         |
| `credits:spend`        | Perform actions that spend credits      | ❌         |
| `credits:purchase`     | Buy credits with a payment method       | ✅         |
| `credits:transfer`     | Transfer credits to other organizations | ✅         |

### Data Access

| Permission          | Description                          | Sensitive |
| ------------------- | ------------------------------------ | --------- |
| `data:view`         | View collected data                  | ❌         |
| `data:download`     | Download datasets                    | ❌         |
| `data:make_public`  | Mark datasets as publicly accessible | ✅         |
| `data:run_analysis` | Run AI analysis on datasets          | ❌         |

<Warning>
  Permissions marked as **sensitive** can only be granted by admins. Non-admin members cannot grant or revoke sensitive permissions.
</Warning>

## Modifying Permissions

Admins can update any member's permissions at any time:

1. Go to the **Members** tab in your organization
2. Click on the member you want to edit
3. Toggle permissions on or off
4. Save changes

## Owner & Admin Safeguards

Several safeguards protect organization integrity:

| Rule                          | Description                                                            |
| ----------------------------- | ---------------------------------------------------------------------- |
| **Cannot remove yourself**    | Use "Leave Organization" instead of removing yourself                  |
| **Owner cannot leave**        | The organization creator cannot leave the organization                 |
| **Last admin protection**     | The last admin cannot have their admin permission removed              |
| **Only admins manage admins** | Only admins can add/remove other admins or grant sensitive permissions |

## Recommended Role Patterns

| Role                       | Suggested Permissions                                                                                                               |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Principal Investigator** | `admin` (full access)                                                                                                               |
| **Lab Manager**            | `org:manage_members`, `quest:update_any`, `quest:publish`, `credits:purchase`, `credits:view_balance`, `data:view`, `data:download` |
| **Research Assistant**     | `quest:create`, `quest:update_own`, `quest:add_participants`, `data:view`, `data:download`, `credits:view_balance`                  |
| **Data Analyst**           | `data:view`, `data:download`, `data:run_analysis`, `credits:view_balance`                                                           |
| **External Collaborator**  | `data:view`, `credits:view_balance`                                                                                                 |


# Organizations Overview
Source: https://docs.usefusion.ai/organizations/overview

Organizations are the team-level structure in Fusion — own quests, manage members, and control billing.

Every quest in Fusion belongs to an **organization**. Organizations provide team-level ownership, shared billing, and fine-grained permissions for collaborating on research.

## Why Organizations?

* **Shared ownership** — quests belong to the org, not an individual
* **Billing hub** — credits are managed at the org level
* **Access control** — 18 granular permissions across 5 categories
* **Collaboration** — add team members, assign roles, share data

## Key Concepts

| Concept             | Description                                                               |
| ------------------- | ------------------------------------------------------------------------- |
| **Slug**            | URL-safe identifier, auto-generated from the org name. Max 50 characters. |
| **Starter credits** | Every new organization gets **free starter credits** automatically.       |
| **Owner**           | The creator is automatically the first admin.                             |
| **Members**         | Other users added by admins. Each member has a custom set of permissions. |
| **Credits**         | 1 credit = 1 cent. All billing goes through the org's credit balance.     |

## Organization Lifecycle

1. **Create** — choose a name, get a unique slug and free starter credits
2. **Add members** — search by username, assign permissions
3. **Create quests** — all quests are scoped to an organization
4. **Publish & run** — publishing, data collection, and storage deduct from the org's credits
5. **Monitor spending** — track expenses per quest, per item type

## Explore

<CardGroup>
  <Card title="Creating an Organization" icon="plus" href="/organizations/creating-an-org">
    Set up a new org with starter credits.
  </Card>

  <Card title="Members & Permissions" icon="users" href="/organizations/members-and-permissions">
    Add members and configure 18 granular permissions.
  </Card>

  <Card title="Managing Quests" icon="clipboard-list" href="/organizations/managing-quests">
    Assign quests to orgs and transfer between them.
  </Card>

  <Card title="Billing & Credits" icon="credit-card" href="/billing/overview">
    Purchase credits, track expenses, and fund other orgs.
  </Card>
</CardGroup>


# Prompt Categories
Source: https://docs.usefusion.ai/prompts/categories

Organize prompts into 9 categories for filtering and participant clarity.

Every prompt is tagged with a **category** — a label that helps you and your participants organize and filter prompts by topic.

## Available Categories

| Category               | Icon  | Color              | Example Prompt                                  |
| ---------------------- | ----- | ------------------ | ----------------------------------------------- |
| **Mental Health**      | 🧠    | Pink (`#FFC0CB`)   | "How anxious do you feel right now?"            |
| **Productivity**       | 👩‍💻 | Gold (`#FFD700`)   | "How many focus hours did you have today?"      |
| **Relationships**      | 👫    | Cyan (`#00FFFF`)   | "Did you have a meaningful conversation today?" |
| **Health and Fitness** | 🏃    | Green (`#00FF00`)  | "Did you exercise today?"                       |
| **Spiritual Practice** | 🧘    | Orange (`#FFA500`) | "Did you meditate today?"                       |
| **Self-Care**          | 🧖    | —                  | "Did you take time for self-care today?"        |
| **Finance**            | 💸    | Red (`#FF0000`)    | "How much did you spend today?"                 |
| **Personal Interest**  | 🤩    | Purple (`#800080`) | "What hobby did you engage in?"                 |
| **Other**              | 📁    | Black (`#000000`)  | Catch-all for uncategorized prompts             |

## How Categories Work

* Categories are set **per prompt**, not per quest — a single quest can have prompts across multiple categories
* Categories appear as colored badges with icons in the prompt list
* Participants see the category label when viewing their prompts
* Categories help researchers organize data during analysis

## Choosing a Category

Pick the category that best matches the research domain of your prompt. If none of the 8 specific categories fit, use **Other**.

<Tip>
  For multi-domain studies, use different categories for different prompts to make it easy to filter and analyze responses by topic area.
</Tip>


# Conditional Notifications
Source: https://docs.usefusion.ai/prompts/conditional-notifications

Trigger prompts based on a participant's answer to a previous prompt or onboarding question.

Conditional notifications let you configure a prompt to **only fire if a participant's previous answer meets a specific condition**. This is an advanced feature for creating adaptive, branching study flows.

## How It Works

Each prompt can have an optional **notify condition** with four fields:

| Field           | Description                                                                                                     |
| --------------- | --------------------------------------------------------------------------------------------------------------- |
| **Source Type** | What kind of question to check: `prompt` (another prompt in the quest) or `onboarding` (an onboarding question) |
| **Source ID**   | Which specific prompt or onboarding question to evaluate                                                        |
| **Operator**    | The comparison operator                                                                                         |
| **Value**       | The value to compare the participant's answer against                                                           |

When a condition is set, the prompt's notification is **only sent** if the participant's answer to the source question satisfies the condition.

## Available Operators

| Operator | Label                 | Description                    |
| -------- | --------------------- | ------------------------------ |
| `eq`     | Equals                | Exact match (case-insensitive) |
| `neq`    | Not equals            | Does not match                 |
| `gt`     | Greater than          | Numeric: answer > value        |
| `gte`    | Greater than or equal | Numeric: answer ≥ value        |
| `lt`     | Less than             | Numeric: answer \< value       |
| `lte`    | Less than or equal    | Numeric: answer ≤ value        |

## Source Options

The source list is built from:

* **All other prompts** in the same quest (excluding the current prompt)
* **All onboarding questions** in the quest

This means you can use either a participant's ongoing prompt responses or their initial onboarding answers to determine whether a follow-up prompt should fire.

## Examples

### Follow-up on Poor Sleep

> Only ask about caffeine if the participant reported sleeping poorly.

| Field       | Value                                             |
| ----------- | ------------------------------------------------- |
| Source Type | `prompt`                                          |
| Source      | *"Did you sleep well last night?"* (yesno prompt) |
| Operator    | `eq`                                              |
| Value       | `No`                                              |

**Result**: The caffeine prompt only fires when the participant answered "No" to the sleep prompt.

### High Stress Follow-up

> Only ask about stress coping strategies if stress rating is high.

| Field       | Value                                                  |
| ----------- | ------------------------------------------------------ |
| Source Type | `prompt`                                               |
| Source      | *"Rate your stress level (1–10)"* (numberRange prompt) |
| Operator    | `gte`                                                  |
| Value       | `7`                                                    |

**Result**: The coping strategies prompt only fires when the participant rated stress ≥ 7.

### Based on Onboarding Answer

> Only send exercise prompts to participants who indicated they exercise regularly.

| Field       | Value                                                      |
| ----------- | ---------------------------------------------------------- |
| Source Type | `onboarding`                                               |
| Source      | *"Do you exercise regularly?"* (yesno onboarding question) |
| Operator    | `eq`                                                       |
| Value       | `Yes`                                                      |

**Result**: Exercise-related prompts only fire for participants who answered "Yes" during onboarding.

## Tips

<Tip>
  Conditional notifications are evaluated at notification time. The condition checks the participant's **most recent** response to the source question.
</Tip>

<Warning>
  A prompt with a conditional notification will **never fire** if the source question hasn't been answered yet. Make sure the source prompt is scheduled before the conditional prompt.
</Warning>

* Use conditions to reduce participant burden — only ask follow-up questions when relevant
* Combine with the scheduling system to create sophisticated adaptive study protocols
* You can only set **one** condition per prompt


# Prompts Overview
Source: https://docs.usefusion.ai/prompts/overview

Prompts are optional recurring questions delivered to participants on a schedule.

Prompts are recurring questions or tasks delivered to participants at scheduled times throughout your study. They're a powerful way to collect longitudinal data in NeuroFusion, but they are **optional** at the quest level.

## What Is a Prompt?

A prompt is a question with:

* **Prompt text** — the question or instruction shown to participants
* **Response type** — how participants answer (Yes/No, Text, Number, Number Range, or Custom Options)
* **Category** — organizational tag (e.g., Mental Health, Productivity)
* **Schedule** — which days, what time window, and how often the prompt fires
* **Notifications** — whether to send push notifications for this prompt
* **Conditional rules** (optional) — only fire if a previous answer meets a condition

## Requirements

* Quests can have **zero prompts**
* There is no upper limit on prompts per quest

If your study only needs onboarding, experiments, recordings, health data, or analysis scripts, you can leave prompts empty and still create the quest.

## Billing

See the [Pricing](https://usefusion.ai/pricing) page for details on prompt-based billing.

## Explore

<CardGroup>
  <Card title="Response Types" icon="list" href="/prompts/response-types">
    Yes/No, Text, Number, Number Range, and Custom Options.
  </Card>

  <Card title="Categories" icon="tags" href="/prompts/categories">
    9 categories to organize your prompts.
  </Card>

  <Card title="Scheduling" icon="clock" href="/prompts/scheduling">
    Active days, time windows, and frequency settings.
  </Card>

  <Card title="Conditional Notifications" icon="code-branch" href="/prompts/conditional-notifications">
    Trigger prompts based on previous answers.
  </Card>
</CardGroup>


# Prompt Response Types
Source: https://docs.usefusion.ai/prompts/response-types

The 5 response types available for prompts: Yes/No, Text, Number, Number Range, and Custom Options.

Each prompt requires a **response type** that determines how participants answer the question. There are 5 types available.

<Frame>
  <img alt="Configure Prompt dialog with response type selector set to Text" />
</Frame>

## Yes/No

|                |                                                   |
| -------------- | ------------------------------------------------- |
| **Type value** | `yesno`                                           |
| **UI**         | Two radio buttons: "Yes" and "No"                 |
| **Best for**   | Binary screening, daily check-ins, habit tracking |

**Example**: *"Did you exercise today?"* → Yes / No

## Text

|                |                                                      |
| -------------- | ---------------------------------------------------- |
| **Type value** | `text`                                               |
| **UI**         | Free-form text input field                           |
| **Best for**   | Open-ended reflections, journaling, qualitative data |

**Example**: *"Describe your mood in a few words."* → (free text)

## Number

|                |                                              |
| -------------- | -------------------------------------------- |
| **Type value** | `number`                                     |
| **UI**         | Numeric input field                          |
| **Best for**   | Counts, measurements, single numeric ratings |

**Example**: *"How many cups of coffee did you drink today?"* → 3

## Number Range

|                |                                                                |
| -------------- | -------------------------------------------------------------- |
| **Type value** | `numberRange`                                                  |
| **UI**         | Numeric input with configurable min/max bounds                 |
| **Best for**   | Likert scales, pain scales, mood ratings, bounded measurements |
| **Defaults**   | min = 0, max = 10                                              |

**Example**: *"Rate your stress level (1–10):"* → 7

### Configuring the Range

* **Min** — the lowest value participants can enter (default: `0`)
* **Max** — the highest value participants can enter (default: `10`)
* Validation: min must be less than max

<Tip>
  Use Number Range instead of plain Number when you want to constrain participant responses to a bounded scale (e.g., 1–5 Likert, 0–100 VAS).
</Tip>

## Custom Options

|                |                                                            |
| -------------- | ---------------------------------------------------------- |
| **Type value** | `customOptions`                                            |
| **UI**         | Radio buttons (single select) or checkboxes (multi-select) |
| **Best for**   | Categorical data, multiple choice, forced-choice paradigms |

**Example**: *"How would you describe your sleep quality?"* → Poor; Fair; Good; Excellent

### Configuring Custom Options

1. **Enter options as a semicolon-separated list** — e.g., `Poor;Fair;Good;Excellent`
2. **"Allow multiple responses" toggle**:
   * **ON** (single only = true) → participants pick **one** option (radio buttons)
   * **OFF** (single only = false) → participants can pick **multiple** options (checkboxes)

<Warning>
  Options are separated by **semicolons** (`;`) in prompts. This is different from onboarding questions, which use commas.
</Warning>

## Summary Table

| Type            | UI Element             | Configurable?                     | Example Use                      |
| --------------- | ---------------------- | --------------------------------- | -------------------------------- |
| `yesno`         | Radio: Yes/No          | No                                | "Did you meditate today?"        |
| `text`          | Text input             | No                                | "How are you feeling?"           |
| `number`        | Number input           | No                                | "Hours of sleep last night?"     |
| `numberRange`   | Number input (bounded) | Min/Max                           | "Rate your mood (1–10)"          |
| `customOptions` | Radio or checkboxes    | Options list, single/multi select | "What did you eat? (select all)" |


# Prompt Scheduling
Source: https://docs.usefusion.ai/prompts/scheduling

Configure when and how often prompts are delivered to participants.

Each prompt has a schedule that controls when it's delivered to participants. Scheduling is configured along three dimensions: **active days**, **time window**, and **frequency**.

<Frame>
  <img alt="Configure Prompt dialog showing frequency set to Once and time picker at 08:00 AM" />
</Frame>

## Active Days

Choose which days of the week the prompt fires. Each day has an independent toggle.

| Day       | Default |
| --------- | ------- |
| Monday    | ✅ On    |
| Tuesday   | ✅ On    |
| Wednesday | ✅ On    |
| Thursday  | ✅ On    |
| Friday    | ✅ On    |
| Saturday  | ✅ On    |
| Sunday    | ✅ On    |

All days are enabled by default. Disable specific days for studies that only need data on certain days (e.g., weekdays only).

## Time Window

Set the time range during which the prompt can fire each day.

| Setting        | Default         | Format |
| -------------- | --------------- | ------ |
| **Start time** | `08:00` (8 AM)  | HH:mm  |
| **End time**   | `22:00` (10 PM) | HH:mm  |

* When frequency is set to **"Once"**, the picker shows a single **"At"** time, and the end time is automatically set to start + 2 minutes
* When frequency is anything else, the picker shows **"Between \[start] And \[end]"** with two time pickers

## Frequency

How many times per day the prompt fires within the time window.

| Label                 | Interval | Description                                   |
| --------------------- | -------- | --------------------------------------------- |
| **Once**              | —        | Single notification at the specified time     |
| **Every 30 minutes**  | 30 min   | Fires every 30 minutes within the time window |
| **Every hour**        | 60 min   | Fires every 60 minutes within the time window |
| **Every two hours**   | 120 min  | Fires every 2 hours within the time window    |
| **Every three hours** | 180 min  | Fires every 3 hours within the time window    |
| **Every four hours**  | 240 min  | Fires every 4 hours within the time window    |

## Notifications

Each prompt has a **notifications toggle**. When enabled, participants receive push notifications at the scheduled times to remind them to respond.

## Examples

### Daily Morning Check-in

> *"How did you sleep last night?"*

| Setting   | Value      |
| --------- | ---------- |
| Days      | All 7 days |
| Frequency | Once       |
| Time      | 08:00      |

### Hourly Stress Rating (Weekdays)

> *"Rate your current stress level (1–10):"*

| Setting    | Value              |
| ---------- | ------------------ |
| Days       | Monday–Friday only |
| Frequency  | Every hour         |
| Start time | 09:00              |
| End time   | 17:00              |

### Twice-Daily Mood Tracking

> *"How are you feeling right now?"*

| Setting    | Value            |
| ---------- | ---------------- |
| Days       | All 7 days       |
| Frequency  | Every four hours |
| Start time | 09:00            |
| End time   | 21:00            |

<Info>
  Prompt defaults when creating a new prompt: all days enabled, start time 08:00, end time 22:00, frequency "Once", notifications on.
</Info>


# Analysis Scripts
Source: https://docs.usefusion.ai/quests/analysis-scripts

Automate data analysis on quest datasets with Python scripts — run quality checks, compute metrics, and process experiment results.

Analysis scripts let you attach **Python code** to a quest that runs against collected datasets. Use them to automate quality checks on EEG recordings, compute summary metrics from experiment trials, or process prompt responses — without downloading data manually.

## How It Works

Each analysis script has:

| Field             | Required? | Description                                    |
| ----------------- | --------- | ---------------------------------------------- |
| **Name**          | ✅ Yes     | Display name for the script                    |
| **Description**   | Optional  | What the script does                           |
| **Code**          | ✅ Yes     | Python code to execute                         |
| **Trigger Type**  | ✅ Yes     | When the script runs (see below)               |
| **Dataset Types** | Optional  | Filter which dataset types the script receives |
| **Active**        | Yes       | Enable/disable without deleting                |

## Trigger Types

Scripts can be triggered in different ways:

| Trigger                 | When it runs                                |
| ----------------------- | ------------------------------------------- |
| `manual`                | On-demand — click "Run" in the dashboard    |
| `after_experiment`      | After a participant completes an experiment |
| `after_dataset`         | After a new dataset is uploaded             |
| `after_prompt_response` | After a prompt response is submitted        |
| `scheduled`             | On a cron schedule                          |

<Info>
  Currently, only **manual** execution is available in the UI. Automatic triggers (after\_experiment, scheduled, etc.) will be enabled in a future update.
</Info>

## Data Flow

When a script executes:

1. The server queries all datasets for the quest (filtered by the script's `datasetTypes` if set)
2. For each dataset, the actual file content is downloaded from blob storage
3. Everything is sent to the **Python executor** as structured input
4. The executor runs the script and returns output + stdout
5. Results are saved as an execution record with status, output, errors, and timing

```
Quest Datasets (DB) → Blob Storage (download) → Python Executor → Execution Record
```

## Writing Scripts

Scripts run in a Python 3.11 environment with **numpy**, **pandas**, **scipy**, and **json** pre-imported. Your code receives several variables automatically:

### Available Variables

| Variable        | Type         | Description                                                       |
| --------------- | ------------ | ----------------------------------------------------------------- |
| `datasets`      | `list[dict]` | List of dataset objects (see below)                               |
| `dataset_count` | `int`        | Number of datasets                                                |
| `quest_guid`    | `str`        | GUID of the quest                                                 |
| `triggered_by`  | `str`        | How the script was triggered (`manual`, `after_experiment`, etc.) |
| `np`            | module       | NumPy                                                             |
| `pd`            | module       | Pandas                                                            |
| `json`          | module       | JSON                                                              |

### Dataset Object

Each item in the `datasets` list is a dictionary:

| Key              | Type          | Description                                                          |
| ---------------- | ------------- | -------------------------------------------------------------------- |
| `id`             | `int`         | Dataset row ID                                                       |
| `type`           | `str`         | `brain_recordings`, `experiment_trials`, `prompt_responses`, etc.    |
| `content`        | `str \| None` | Raw file content (CSV, JSON). `None` if file couldn't be downloaded. |
| `userGuid`       | `str`         | Participant identifier                                               |
| `timestamp`      | `int`         | Unix timestamp of the recording                                      |
| `experimentName` | `str \| None` | Name of the experiment (if applicable)                               |
| `deviceType`     | `str \| None` | EEG device type (`muse`, `neurosity`, etc.)                          |
| `provider`       | `str \| None` | Data source (`fusion`, etc.)                                         |
| `fileName`       | `str \| None` | Blob storage path                                                    |

### Returning Results

Set the `output` variable to return structured results. Anything printed to `stdout` is also captured.

```python theme={null}
output = {"status": "success", "results": my_results}
```

### Example: EEG Quality Check

```python theme={null}
from io import StringIO

results = []
for ds in datasets:
    if ds["type"] != "brain_recordings" or ds["content"] is None:
        continue

    df = pd.read_csv(StringIO(ds["content"]))
    channels = [c for c in df.columns if c != "timestamp"]

    quality = {}
    for ch in channels:
        vals = df[ch].values
        quality[ch] = {
            "mean": float(np.mean(vals)),
            "std": float(np.std(vals)),
            "is_flat": bool(np.std(vals) < 0.001),  # flat signal = bad contact
        }

    results.append({
        "dataset_id": ds["id"],
        "experiment": ds.get("experimentName"),
        "n_samples": len(df),
        "channels": quality,
        "pass": all(not q["is_flat"] for q in quality.values()),
    })

output = {"status": "success", "results": results}
print(f"Checked {len(results)} recordings")
```

### Example: Experiment Reaction Times

```python theme={null}
from io import StringIO

for ds in datasets:
    if ds["type"] != "experiment_trials" or ds["content"] is None:
        continue

    df = pd.read_csv(StringIO(ds["content"]))
    if "rt" in df.columns:
        rt = df["rt"].dropna()
        output = {
            "mean_rt": float(rt.mean()),
            "median_rt": float(rt.median()),
            "std_rt": float(rt.std()),
            "n_trials": len(rt),
            "outliers": int((rt > rt.mean() + 3 * rt.std()).sum()),
        }
        print(f"Mean RT: {output['mean_rt']:.1f}ms across {output['n_trials']} trials")
```

## Using the Dashboard

Analysis scripts are managed from the **quest detail page**, below the dataset sections.

### Creating a Script

1. Open your quest in the dashboard
2. Scroll to the **Analysis Scripts** section
3. Click **New Script**
4. Enter a name, select a trigger type, and write your Python code in the Monaco editor
5. Click **Save Script**

### Running a Script

1. Find the script in the list
2. Click **Run**
3. The execution status and output appear in the expandable execution history below the script

### Viewing Execution History

Click on a script row to expand it and see recent executions with:

* Status (completed / failed)
* Execution time
* Output (stdout + structured output)
* Error messages and Python tracebacks (if failed)

## Filtering by Dataset Type

If your script only needs certain data types, set the **Dataset Types** field when creating the script. For example, an EEG quality script should filter to `brain_recordings` only — this avoids loading irrelevant prompt responses or experiment trials.

Supported dataset types:

* `brain_recordings` — EEG data from Muse or Neurosity
* `experiment_trials` — jsPsych experiment results
* `prompt_responses` — Answers to recurring prompts
* `onboarding_responses` — Onboarding form answers

## Billing

Each script execution costs credits, billed as `script_run` to the quest's organization. See the **[Pricing page](https://usefusion.ai/pricing)** for current costs.

<Warning>
  Credits are deducted **before** execution. If the script fails, credits are still consumed. Check your script logic in a small test before running on large datasets.
</Warning>

## Permissions

To create, edit, or run analysis scripts, you need the **`data.run_script`** permission in the quest's organization. Organization admins have this by default. See [Members & Permissions](/organizations/members-and-permissions) for details.

## Limits

| Limit                  | Value            |
| ---------------------- | ---------------- |
| Execution timeout      | 5 minutes        |
| Datasets per execution | 50 (most recent) |
| Scripts per quest      | Unlimited        |

## API Reference

Analysis scripts are also available via the REST API:

| Method   | Endpoint                                                | Description              |
| -------- | ------------------------------------------------------- | ------------------------ |
| `POST`   | `/api/quest/analysis-scripts`                           | Create a script          |
| `GET`    | `/api/quest/analysis-scripts?questId=...`               | List scripts for a quest |
| `GET`    | `/api/quest/analysis-scripts/:guid`                     | Get a single script      |
| `PUT`    | `/api/quest/analysis-scripts/:guid`                     | Update a script          |
| `DELETE` | `/api/quest/analysis-scripts/:guid`                     | Delete a script          |
| `POST`   | `/api/quest/analysis-scripts/:guid/execute`             | Execute a script         |
| `GET`    | `/api/quest/analysis-scripts/executions?scriptGuid=...` | Get execution history    |

### Execute Request Body

```json theme={null}
{
  "triggeredBy": "manual",
  "datasetId": 42,
  "inputValues": {
    "threshold": 0.5
  }
}
```

All fields are optional. `datasetId` restricts execution to a single dataset (useful for event-driven triggers). `inputValues` maps to the script's configured input variables.

## Explore

<CardGroup>
  <Card title="Experiments" icon="flask" href="/experiments/overview">
    Learn about the experiments that generate data for your scripts.
  </Card>

  <Card title="Billing" icon="credit-card" href="/billing/overview">
    Understand how script execution costs are billed.
  </Card>

  <Card title="Viewing Quest Data" icon="table" href="/quests/viewing-quest-data">
    Browse the datasets your scripts analyze.
  </Card>

  <Card title="Members & Permissions" icon="users" href="/organizations/members-and-permissions">
    Manage who can run analysis scripts.
  </Card>
</CardGroup>


# Cloning a Quest
Source: https://docs.usefusion.ai/quests/cloning-a-quest

Duplicate an existing quest as a starting point for a new study.

Quest cloning lets you create a copy of an existing quest, including all its configuration — experiments, prompts, onboarding questions, and media files. This is useful when you want to run a variation of a previous study or use a published quest as a template.

## How to Clone a Quest

1. Navigate to the quest you want to clone
2. Click the **⋯ (more)** menu on the quest card or detail page
3. Select **Clone Quest**
4. The cloned quest opens in the editor with all configuration pre-filled

## What Gets Copied

| Component            | Copied? | Notes                                                |
| -------------------- | ------- | ---------------------------------------------------- |
| Title                | ✅       | Appended with "(Copy)" suffix                        |
| Description          | ✅       | Exact copy                                           |
| Prompts              | ✅       | All prompts with their response types and scheduling |
| Experiments          | ✅       | Full experiment code and configuration               |
| Onboarding questions | ✅       | Questions, guards, and overview text                 |
| Media files          | ✅       | Duplicated in cloud storage with new URLs            |
| Health data config   | ✅       | All selected health data types                       |
| Extra config         | ✅       | Gift cards, Vital API keys, etc.                     |
| Collaborators        | ❌       | Must be re-added on the new quest                    |
| Participant data     | ❌       | Clone starts fresh with no responses                 |
| Join code            | ❌       | A new unique join code is generated                  |

## Media File Handling

When a quest contains uploaded media (images, audio, video used in experiments), NeuroFusion **duplicates the actual files** in cloud storage rather than sharing references. This means:

* Editing or deleting media on the cloned quest does not affect the original
* Each quest has fully independent media storage
* URLs in the experiment code are automatically rewritten to point to the new copies

## Permissions

* You need `quest.create` permission in the target organization to clone a quest
* You can clone your own quests or any public quest
* The cloned quest is created within your currently selected organization

<Note>
  If cloning fails partway through (e.g., media copy error), the operation is **rolled back** — the partially created quest and any copied media are cleaned up automatically.
</Note>


# Creating a Quest
Source: https://docs.usefusion.ai/quests/creating-a-quest

Step-by-step guide to building and configuring a quest.

This guide walks you through creating a quest from scratch — selecting an organization, optionally adding prompts and experiments, configuring onboarding, and publishing.

## Step 1: Choose an Organization

When you click **Create Quest**, you'll see an **org selector dropdown**. Choose which organization the quest belongs to — this determines who can manage the quest and where billing is charged.

<Frame>
  <img alt="Create Quest form showing title, description, organized by, and organization fields" />
</Frame>

* Select an existing organization from the dropdown

<Info>
  You must create an organization before creating a quest. See [Creating an Organization](/organizations/creating-an-org) to get started.
</Info>

## Step 2: Fill in Quest Metadata

* **Title** — a clear name for your study (e.g., *"Daily Mood & Sleep Tracking"*)
* **Description** — what the quest is about (shown to participants)
* **Category** — helps organize and discover quests

## Step 3: Add Prompts (Optional)

Prompts are **optional**. Add them when your study needs recurring questions on a schedule, and skip them when your quest is experiment-only, onboarding-only, recording-focused, or otherwise does not need scheduled surveys.

1. Click **Add Prompt**
2. Enter the prompt text
3. Select a response type (Yes/No, Text, Number, Number Range, or Custom Options)
4. Pick a category (Mental Health, Productivity, Health and Fitness, etc.)
5. Configure the schedule: active days, time window, and frequency

If you skip prompts, your quest can still be saved and published — participants just won't receive scheduled survey-style questions.

<Frame>
  <img alt="Configure Prompt dialog showing category selector, prompt text, response type, frequency, and time picker" />
</Frame>

<Info>
  See [Prompts](/prompts/overview) for full details on response types, categories, scheduling, and conditional notifications.
</Info>

## Step 4: Add Experiments (Optional)

Add interactive jsPsych experiments for participants to complete.

1. Click **Add Experiment**
2. Enter a name and optional description
3. Write or paste experiment code in the Monaco editor (starts with a default jsPsych 8.0.3 template)
4. Upload media (images, audio, video) using the media uploader
5. Use the live preview to test your experiment

You can add **multiple experiments** — they'll be displayed as a horizontal list of cards that participants navigate through.

<Info>
  See [Experiments](/experiments/overview) for full details on the editor, media uploads, and ordering.
</Info>

## Step 5: Configure Onboarding (Optional)

Set up what participants see before they join the quest:

1. **Full-text overview** — rich HTML content for informed consent, study purpose, and data usage. Participants must check an acknowledgment box before continuing.
2. **Onboarding questions** — screening questions with optional question guards to block ineligible participants.

<Frame>
  <img alt="Create Quest form showing onboarding, prompts, experiments, health data, and script configuration sections" />
</Frame>

<Info>
  See [Onboarding & Consent](/onboarding/overview) for full details on the overview, questions, guards, and kiosk mode.
</Info>

## Step 6: Configure Health Data (Optional)

Toggle which health metrics to collect from participants with wearables:

* **Steps** — daily step count
* **Sleep** — sleep duration and quality
* **Heart Rate** — heart rate measurements

## Step 7: Save

Click **Save** to store your quest. This:

* Generates a unique **quest GUID** and URL
* Enables **media uploads** for experiments (you can't upload media until the quest is saved)
* Keeps the quest in **draft** status — it's not visible to participants yet

## Step 8: Publish

Click **Publish** to make the quest live and accessible via its URL.

<Warning>
  Publishing consumes credits from the quest's organization. Make sure the org has sufficient credits. See [Pricing](https://usefusion.ai/pricing) for current costs.
</Warning>

Once published, you can share the quest link:

* **Direct link** — copy the URL and send it to participants
* **QR code** — generate a QR code for in-person recruitment
* **Prolific** — paste the URL as your Prolific study URL (see [Prolific Integration](/integrations/prolific))

## Next Steps

<CardGroup>
  <Card title="Running a Study" icon="microscope" href="/quests/running-a-study">
    End-to-end guide for conducting research.
  </Card>

  <Card title="Sharing & Publishing" icon="share" href="/quests/sharing-and-publishing">
    Share your quest and manage collaborators.
  </Card>
</CardGroup>


# Deleting a Quest
Source: https://docs.usefusion.ai/quests/deleting-a-quest

How to safely delete a quest with impact review and confirmation.

Quest deletion uses a **soft-delete** approach — deleted quests are marked as removed but their data is preserved in the database for a grace period. This ensures accidental deletions can be recovered.

## How to Delete a Quest

1. Navigate to the **Quests** dashboard
2. Find the quest you want to delete
3. Click the **⋯ (more)** menu on the quest card
4. Select **Delete Quest**

## Impact Preview

Before confirming deletion, NeuroFusion shows an **impact summary** so you understand exactly what will be affected:

| Impact Area      | What's Shown                                                    |
| ---------------- | --------------------------------------------------------------- |
| **Participants** | Number of users who have joined this quest                      |
| **Datasets**     | Total number of submitted responses and experiment data         |
| **Media files**  | Count of uploaded files, grouped by type (images, audio, video) |

## Confirmation

* If the quest has **no data** (no participants, no datasets), you can delete it with a single click
* If the quest **has data**, you must type the quest title to confirm deletion — this prevents accidental data loss

<Info>
  Deleted quests are **soft-deleted** — they are hidden from the dashboard but their data is preserved. Contact support at [contact@usefusion.app](mailto:contact@usefusion.app) if you need to recover a deleted quest.
</Info>

## Who Can Delete a Quest

Only the quest **creator** or an organization member with `quest.delete` permission can delete a quest. Collaborators without this permission will not see the delete option.

## What Happens After Deletion

* The quest is removed from the dashboard and public listings
* Participants can no longer submit data to the quest
* Existing datasets and responses are preserved (soft-delete)
* The deletion is recorded in the [Data Audit Trail](/data/audit-trail) if enabled for your organization


# Managing Participants
Source: https://docs.usefusion.ai/quests/managing-participants

View, filter, and manage participant status and cohort assignments for your quest.

Every quest has a **Participants** page where researchers can view enrolled participants, update their lifecycle status, and assign them to cohorts. This is the primary operational surface for managing a study's participant roster.

## Accessing the Participants Page

1. Open your quest detail page
2. Click **Manage Participants** in the action bar
3. The participants page opens at `/quest/<guid>/participants`

<Info>
  Only quest editors (the quest creator, organization members with `quest.update` permission, or listed collaborators) can access the participants page.
</Info>

## The Participant Table

The participants table shows every person who has joined the quest. Each row includes:

| Column                 | Description                                                                                     |
| ---------------------- | ----------------------------------------------------------------------------------------------- |
| **Participant**        | Username, email, or public key — whichever is available. A secondary identifier is shown below. |
| **Cohort**             | The cohort the participant belongs to, or "Unassigned". Editable via dropdown.                  |
| **Status**             | The participant's current lifecycle status, shown as a colored badge. Editable via dropdown.    |
| **Joined**             | When the participant joined the quest.                                                          |
| **Last status update** | When the status was last changed.                                                               |

Changes to status and cohort **save immediately** — there is no separate save button.

## Participant Statuses

Participants move through a lifecycle of statuses. Each status has a distinct color badge for quick visual identification:

| Status         | Color  | Description                                   |
| -------------- | ------ | --------------------------------------------- |
| **Screened**   | Gray   | Participant has been reviewed for eligibility |
| **Eligible**   | Cyan   | Meets eligibility criteria                    |
| **Ineligible** | Amber  | Does not meet eligibility criteria            |
| **Consented**  | Violet | Has provided informed consent                 |
| **Enrolled**   | Gray   | Joined the quest (default status on join)     |
| **Active**     | Blue   | Currently participating in the study          |
| **Completed**  | Green  | Finished all study activities                 |
| **Withdrawn**  | Red    | Withdrew from the study                       |
| **Excluded**   | Rose   | Removed from the study by the researcher      |

### Automatic Enrollment

When a participant joins a quest, they are automatically created as a **QuestSubject** with `enrolled` status. No manual action is needed — the participant appears in the table as soon as they complete the join flow.

### Changing Status

Select a new status from the dropdown in the Status column. The update is sent to the server immediately. Use this to track participant progress through your study protocol — for example, moving participants from `enrolled` → `active` → `completed`.

## Cohorts

Cohorts let you organize participants into groups — useful for multi-arm studies, A/B conditions, treatment vs. control groups, or any grouping your study design requires.

### Creating Cohorts

Cohorts are created via the API:

```
POST /api/quest/:questGuid/cohorts
{
  "name": "Treatment Group A",
  "description": "Participants receiving the active intervention"
}
```

Each cohort has a **name** (required) and an optional **description**.

### Assigning Participants to Cohorts

In the participants table, use the Cohort dropdown to assign or reassign a participant. Select "Unassigned" to remove the cohort assignment. Changes save immediately.

## Filtering

The participants page includes two filters above the table:

* **Filter by status** — show only participants with a specific status (e.g., only "Active" participants)
* **Filter by cohort** — show only participants in a specific cohort, or those who are "Unassigned"

Filters can be combined — for example, show all "Active" participants in "Treatment Group A".

## Refreshing Data

Click **Refresh participants** to reload the participant list from the server. This is useful when participants are actively joining and you want to see the latest roster.

## API Reference

All participant operations are available via the REST API for programmatic access:

| Method  | Endpoint                                             | Description                                                                                                                           |
| ------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `GET`   | `/api/quest/:questGuid/subjects`                     | List all participants. Supports `?status=` and `?cohortGuid=` query filters. Use `cohortGuid=unassigned` for unassigned participants. |
| `PATCH` | `/api/quest/:questGuid/subjects/:subjectGuid/status` | Update a participant's status. Body: `{ "status": "active" }`                                                                         |
| `PATCH` | `/api/quest/:questGuid/subjects/:subjectGuid/cohort` | Assign a participant to a cohort. Body: `{ "cohortGuid": "..." }` or `{ "cohortGuid": null }` to unassign.                            |
| `GET`   | `/api/quest/:questGuid/cohorts`                      | List all cohorts for a quest.                                                                                                         |
| `POST`  | `/api/quest/:questGuid/cohorts`                      | Create a new cohort. Body: `{ "name": "...", "description": "..." }`                                                                  |

All endpoints require authentication and editor-level access to the quest.

## Next Steps

<CardGroup>
  <Card title="Participant Journey" icon="route" href="/quests/participant-journey">
    Understand the end-to-end flow from a participant's perspective.
  </Card>

  <Card title="Running a Study" icon="microscope" href="/quests/running-a-study">
    Full lifecycle guide for conducting research with NeuroFusion.
  </Card>

  <Card title="Viewing Quest Data" icon="chart-bar" href="/quests/viewing-quest-data">
    Explore collected datasets, responses, and health metrics.
  </Card>

  <Card title="Data Audit Trail" icon="shield-check" href="/data/audit-trail">
    Review who accessed or modified study data.
  </Card>
</CardGroup>


# Quests Overview
Source: https://docs.usefusion.ai/quests/overview

Understand quests — Fusion's product object for configuring and running a study.

A **Quest** is Fusion's product object for configuring and running a **study**. It bundles together the pieces your study needs: optional prompts for recurring data collection, experiments for interactive tasks, onboarding for consent and screening, health data configuration, participant operations, and collected datasets.

## Quest Anatomy

Every quest contains a configuration object with the following components:

| Component                  | Required? | Description                                                                                                                                       |
| -------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Prompts**                | Optional  | Recurring questions delivered on a schedule. See [Prompts](/prompts/overview).                                                                    |
| **Onboarding Questions**   | Optional  | Pre-join screening questions for eligibility. See [Onboarding](/onboarding/overview).                                                             |
| **Onboarding Overview**    | Optional  | Rich HTML consent language shown before questions. See [Full-Text Overview](/onboarding/full-text-overview).                                      |
| **Experiments**            | Optional  | Interactive jsPsych tasks. See [Experiments](/experiments/overview).                                                                              |
| **Health Data Config**     | Optional  | Toggles for collecting `steps`, `sleep`, and `heart_rate` from wearables.                                                                         |
| **Assignment**             | Optional  | Python script for counterbalancing / conditional experiment assignment. See [Ordering & Assignment](/experiments/ordering-and-assignment).        |
| **Analysis Scripts**       | Optional  | Python scripts that run against collected datasets for quality checks, metrics, and processing. See [Analysis Scripts](/quests/analysis-scripts). |
| **Post-Experiment Script** | Optional  | Python code to run after experiment completion.                                                                                                   |

Researchers can also use the quest workspace to:

* review participants and cohort assignments
* update participant lifecycle status
* monitor collected datasets
* configure a compact baseline / follow-up schedule for cohorts
* review simple due / overdue compliance state

<Info>
  Prompts are no longer required to create or save a quest. This means you can run experiment-only, onboarding-only, or recording-focused studies without adding scheduled surveys first.
</Info>

## Quest Lifecycle

1. **Draft** — Quest is created and saved but not yet visible to participants
2. **Published** — Quest is live and accessible via its URL (consumes credits — see [Pricing](https://usefusion.ai/pricing))
3. **Participant operations** — Researchers manage participants, cohorts, and schedule/compliance state
4. **Data collection** — Participants submit prompts, onboarding responses, experiments, recordings, and health data
5. **Unpublished** — Quest is taken offline; existing data is preserved

## Organization Scope

Every quest belongs to an **organization**. When creating a quest, you select the organization using a dropdown. All billable actions on the quest (publishing, participant joins, data submissions) are charged to the quest's organization.

<Info>
  You must create an organization before creating a quest. See [Creating an Organization](/organizations/creating-an-org) to get started.
</Info>

## Data Types Collected

| Dataset Type           | Source       | Description                                         |
| ---------------------- | ------------ | --------------------------------------------------- |
| `prompt_responses`     | Web / Mobile | Answers to recurring prompts                        |
| `onboarding_responses` | Web / Mobile | Answers to onboarding questions (free — not billed) |
| `experiment_trials`    | Web / Mobile | jsPsych experiment results (stored in Azure Blob)   |
| `brain_recordings`     | Web / Mobile | EEG recordings from Neurosity Crown or Muse         |
| `health`               | Mobile       | Steps, sleep, heart rate from wearables             |

## Next Steps

<CardGroup>
  <Card title="Creating a Quest" icon="plus" href="/quests/creating-a-quest">
    Step-by-step guide to building your first quest.
  </Card>

  <Card title="Participant Journey" icon="users" href="/quests/participant-journey">
    See how participants move from onboarding into prompts, experiments, and study activities.
  </Card>

  <Card title="Prompts" icon="bell" href="/prompts/overview">
    Configure recurring data-collection questions.
  </Card>

  <Card title="Onboarding" icon="clipboard-check" href="/onboarding/overview">
    Set up consent and eligibility screening.
  </Card>

  <Card title="Experiments" icon="flask" href="/experiments/overview">
    Add interactive jsPsych experiments.
  </Card>

  <Card title="Analysis Scripts" icon="code" href="/quests/analysis-scripts">
    Automate data analysis with Python scripts.
  </Card>
</CardGroup>


# Participant Journey
Source: https://docs.usefusion.ai/quests/participant-journey

Follow the participant flow from published quest link to onboarding, activities, and collected data.

A **Quest** is the product object researchers configure in Fusion, but it functions as the container for a **study**. This page explains the participant-facing flow once your quest is published.

## End-to-End Flow

```
Researcher publishes quest
  → Participant opens quest link
    → Quest checks whether the participant already joined
      → If joined and kiosk mode is off, continue into the quest
      → If joined and kiosk mode is on, onboarding can be shown again
      → If not joined, continue to study onboarding
    → Study Overview / Consent Document (optional)
    → Onboarding questions with guard validation (optional)
    → Join quest
    → Complete prompts, experiments, recordings, and assignments
    → Researcher reviews participants and collected data
```

## What Participants See

Depending on how your quest is configured, participants may see some or all of the following:

* **Study Overview / Consent Document** before any questions
* **Onboarding questions** for screening or baseline intake
* **Prompts** on a defined schedule
* **Experiments** such as jsPsych-based tasks
* **Brain recordings** and health-data collection steps
* **Assignments** that control when to complete the next activity

## Joining a Published Quest

Participants can only join a quest after it has been **published**. Sharing the quest URL or QR code sends them into the same join flow used on web and mobile.

<Info>
  Joining is the moment that creates a participant record for the quest. Onboarding responses are saved first, then the participant is enrolled into the quest itself.
</Info>

## Study Overview / Consent Document

If you add onboarding overview content, participants see it before any onboarding questions. The page is best used for:

* informed consent language
* study summary
* expectations and time commitment
* privacy and data handling notes
* contact details for the study team

See [Full-Text Overview](/onboarding/full-text-overview) for configuration guidance.

## Onboarding Questions and Eligibility

If onboarding questions are configured, participants answer them before joining the quest. Guard rules are checked server-side, so ineligible participants are stopped before they enter the study workflow.

Use onboarding for:

* eligibility screening
* baseline intake
* demographic collection
* consent confirmation steps

See [Onboarding & Consent Overview](/onboarding/overview) for the full flow.

## Activities After Joining

Once participants are inside the quest, they can complete the modules you configured:

* recurring prompts
* experiments
* brain recordings
* health data collection
* assignments tied to experiments or follow-up activities

Use [Running a Study](/quests/running-a-study) to understand how these pieces fit together operationally.

## Researcher Operations Surfaces

The current researcher workflow uses these pages:

* **Quest detail page** for collected data, publishing, sharing, downloads, and schedule/compliance updates
* **Participants page** for participant roster, cohort assignment, and lifecycle status updates
* **Organization quest list** for study-level navigation
* **Audit Log** for data-access history

See:

* [Managing Participants](/quests/managing-participants)
* [Viewing Quest Data](/quests/viewing-quest-data)
* [Data Audit Trail](/data/audit-trail)

## Notes on Terminology

In Fusion:

* **Quest** is the product term used in the UI
* **study** is the research concept the quest represents

In docs, we keep **Quest** as the actionable UI term while using **study** in explanatory text where it helps orient research teams.


# Running a Study
Source: https://docs.usefusion.ai/quests/running-a-study

End-to-end guide for conducting a research study with NeuroFusion.

This guide covers the full lifecycle of running a study on NeuroFusion — from planning through participant operations and data export.

## 1. Plan Your Study Design

Before creating anything on the platform, outline:

* **Research questions** — what are you investigating?
* **Data types** — prompts (surveys), experiments (tasks), brain recordings, health metrics?
* **Participant pool** — direct recruitment, Prolific, or in-lab?
* **Duration** — single-session experiment, daily prompts for weeks/months, or both?
* **Eligibility criteria** — do you need to screen participants? (age, consent, demographics)

## 2. Create an Organization and Invite Collaborators

1. [Create an organization](/organizations/creating-an-org) for your study
2. Invite co-investigators and research assistants as members
3. Assign [granular permissions](/organizations/members-and-permissions) — e.g., give RAs quest editing access but not billing access

## 3. Build the Quest

1. **Create a quest** under your organization ([Creating a Quest](/quests/creating-a-quest))
2. **Add prompts** for recurring data collection if your study needs scheduled surveys ([Prompts](/prompts/overview))
   * Choose response types, categories, and schedules
   * Set up conditional notifications if prompts depend on prior answers
   * Skip this step for experiment-only or recording-only study designs
3. **Add experiments** for interactive tasks ([Experiments](/experiments/overview))
   * Write jsPsych code or paste existing experiments
   * Upload stimulus media (images, audio, video)
   * Configure ordering for multi-experiment quests
4. **Configure onboarding** for consent and screening ([Onboarding](/onboarding/overview))
   * Write a full-text consent overview
   * Add screening questions with question guards
   * Enable kiosk mode if using shared devices
5. **Set up participant operations**
   * Create cohorts for the groups you want to track
   * Review the participant roster after enrollment begins
   * Use the quest detail page to configure a simple baseline / follow-up schedule per cohort

## 4. Fund the Organization

Check your org's credit balance and [purchase credits](/billing/purchasing-credits) if needed. Use the **[price calculator](https://usefusion.ai/pricing)** to estimate your total study cost based on participant count, prompts, experiments, and data types.

<Tip>
  Quest creation and onboarding responses are **free** — you only start spending credits when you publish and participants join.
</Tip>

## 5. Publish and Recruit

1. Click **Publish** on your quest
2. Share with participants via:
   * **Direct link** — copy the quest URL
   * **QR code** — for in-person recruitment
   * **Prolific** — paste the quest URL as your Prolific study URL. Prolific parameters (`PROLIFIC_PID`, `STUDY_ID`, `SESSION_ID`) are captured automatically. See [Prolific Integration](/integrations/prolific).

## 6. Monitor Participants, Responses, and Billing

From the participant and quest workspaces:

* **Participant roster** — review who joined, which cohort they belong to, and the current study status
* **Schedule & compliance** — set a compact baseline / follow-up schedule and review due / overdue state by participant
* **Response data** — view prompt responses, onboarding responses, experiment data, and recordings as they come in
* **Billing summary** — track per-quest spending, broken down by item type and source (web vs. mobile)
* **Transaction history** — review all credit transactions
* **Audit Log** — review which team members viewed, downloaded, deleted, or analyzed data

<Info>
  Fusion still uses **Quest** as the product term in the UI. In practice, the quest detail and participant pages function as the current study-operations workspace.
</Info>

## 7. Export and Analyze Data

* Export prompt responses, experiment data, and recordings for analysis in your preferred tools (R, Python, SPSS, etc.)
* On mobile, participants can export experiment data as JSON files
* Data types available for export:
  * `prompt_responses` — answers to recurring prompts
  * `experiment_trials` — jsPsych experiment results
  * `brain_recordings` — EEG data from Neurosity Crown or Muse
  * `health` — steps, sleep, heart rate from wearables
  * `onboarding_responses` — screening question answers

## Running a Study with Prolific

If you're recruiting through [Prolific](https://www.prolific.co/):

1. Build and publish your quest on NeuroFusion
2. Copy the quest run URL (e.g., `https://usefusion.ai/quest/<guid>`)
3. Create a study on Prolific and paste the quest URL as the study URL
4. Prolific injects `PROLIFIC_PID`, `STUDY_ID`, and `SESSION_ID` as URL parameters
5. These are automatically passed to your experiments via `jatos.urlQueryParameters`
6. Configure your experiment to redirect to Prolific's completion URL when finished

<Info>
  See [Prolific Integration](/integrations/prolific) for the full setup guide.
</Info>

## Tips

* **Test the full flow yourself** before launching — join your own quest as a participant to verify onboarding, prompts, and experiments work as expected
* **Check the participant roster early** — make sure cohort assignment and participant statuses look correct after the first few joins
* **Monitor billing early** — check the expense breakdown after the first few participants to project total costs
* **Use kiosk mode** for in-lab studies where multiple participants share the same device
* Participants can complete experiments on **both web and mobile** — plan your study design accordingly


# Sharing & Publishing
Source: https://docs.usefusion.ai/quests/sharing-and-publishing

Publish your quest, share it with participants, and manage collaborator access.

Once your quest is built and tested, you can publish it to make it accessible to participants and share it through multiple channels.

## Publishing

Publishing makes your quest **live** — participants can access it via its URL.

1. Open your quest in the editor
2. Click **Publish**
3. The quest is now accessible at its URL

<Warning>
  Publishing consumes credits from the quest's organization. Make sure the org has sufficient credits before publishing. See [Pricing](https://usefusion.ai/pricing) for current costs.
</Warning>

### Unpublishing

You can unpublish a quest at any time to take it offline. Existing data is preserved, but new participants can no longer join.

## Sharing Your Quest

Once published, share the quest with participants:

### Direct Link

Copy the quest URL (e.g., `https://usefusion.ai/quest/<guid>`) and share it via email, messaging, or your study recruitment platform.

### QR Code

Generate a QR code from the share modal for in-person recruitment — print it for posters, flyers, or display it at a study site.

### Prolific

Use the quest URL as your Prolific study URL. Prolific's participant ID parameters are captured automatically. See [Prolific Integration](/integrations/prolific) for a step-by-step guide.

## Collaborator Access

Collaborator access is now managed through **organizations**, replacing the old public-key method.

To give other researchers access to manage your quest:

1. Add them as members of the quest's organization
2. Assign appropriate [permissions](/organizations/members-and-permissions) — e.g., `quest.edit`, `quest.view_data`, `quest.publish`

This gives you fine-grained control over what each collaborator can do.

<Warning>
  **Deprecation notice**: The old method of adding collaborators via public key (from the profile page) has been replaced by organization membership. If you previously used that flow, migrate your collaborators to organization members.
</Warning>

## Transferring Quests Between Organizations

You can move a quest from one organization to another — useful when restructuring teams or transferring ownership.

* Requires appropriate permissions on **both** the source and target organizations
* Use the quest transfer feature in the organization dashboard

<Info>
  See [Managing Quests](/organizations/managing-quests) for details on quest transfers.
</Info>


# Viewing Quest Data
Source: https://docs.usefusion.ai/quests/viewing-quest-data

Explore participants, collected datasets, and schedule/compliance state from your quest workspace.

Once participants start joining your quest and submitting data, you can monitor and explore everything from the **quest detail page**. Navigate there by clicking on a quest from the quests list.

<Frame>
  <img alt="Quests dashboard with table columns for title, description, organization, status, and actions" />
</Frame>

## Quest Detail Page Overview

The quest detail page shows:

* **Quest title, description, and status** (Draft, Published, or Unpublished)
* **Action buttons** for publishing, sharing, downloading, refreshing data, and opening participant operations
* **Schedule & Compliance** for a selected cohort, including baseline / follow-up offsets and due-state summaries
* **Participants page** for participant roster, cohort assignment, and lifecycle updates
* **Participant responses table** listing every data submission across all data types

## Data Types

All submissions are displayed in a single **Participant Responses** table with four columns:

| Column        | Description                                                            |
| ------------- | ---------------------------------------------------------------------- |
| **User**      | The participant's unique identifier (user GUID)                        |
| **Type**      | The kind of data submitted (see below)                                 |
| **Timestamp** | When the data was submitted, formatted as `YYYY-MM-DD HH:mm:ss`        |
| **Value**     | The response content — displayed inline or with a **View data** button |

The table combines the following data types:

| Type                   | Description                                                                                                                  |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `prompt_responses`     | Answers to recurring prompts (surveys). The value contains the participant's response text or selection.                     |
| `onboarding_responses` | Answers to onboarding/screening questions submitted when the participant joined the quest.                                   |
| `experiment_trials`    | Results from jsPsych experiments. Stored as JSON in blob storage — click **View data** or **Download** to access.            |
| `brain_recordings`     | EEG recordings from Neurosity Crown or Muse devices. Stored in blob storage — click **View data** or **Download** to access. |
| `health`               | Steps, sleep, and heart-rate data collected from integrated health sources.                                                  |

<Info>
  Health data (steps, sleep, heart rate) is displayed separately in a **graph view** when available, with a category selector to switch between metrics.
</Info>

## Viewing Individual Responses

### Prompt & Onboarding Responses

For `prompt_responses` and `onboarding_responses`, click the **View data** button in the Value column. A viewer panel opens below the action bar showing the response as formatted JSON.

### Experiment Trials & Brain Recordings

For `experiment_trials` and `brain_recordings`, each row shows:

* **Dataset name** — the experiment name or recording type (e.g., *"Stroop Task"* or *"EEG Recording"*)
* **View data** — opens the data in an inline viewer panel
* **Download** — downloads the individual dataset as a JSON or CSV file
* **URL Parameters** (if present) — expandable section showing any URL parameters captured at submission time (e.g., Prolific IDs)

The downloaded file is named using the pattern:

```
{type}_{name}_{userGuid}_{timestamp}.{json|csv}
```

## Dataset Viewer

When you click **View data** on any response, a viewer panel appears showing:

* **Header** — the data type and a truncated user GUID for context
* **Content** — the full response data rendered as formatted, syntax-highlighted text
* **Close** button to dismiss the viewer

The viewer supports both JSON and plain-text content. For experiment trials and brain recordings, the data is fetched from blob storage on demand.

## Downloading All Data

Click the **Download Dataset** button in the action bar to export **all** quest data as a single CSV file.

The CSV contains the following columns:

| Column      | Description                                                             |
| ----------- | ----------------------------------------------------------------------- |
| `userGuid`  | Participant identifier                                                  |
| `questGuid` | Quest identifier                                                        |
| `timestamp` | Unix timestamp of the submission                                        |
| `type`      | Data type (e.g., `prompt_responses`, `experiment_trials - Stroop Task`) |
| `value`     | The full response value (JSON-encoded for complex data)                 |

<Tip>
  For experiment trials and brain recordings, the `type` column includes the experiment or dataset name — e.g., `experiment_trials - Stroop Task` — so you can filter by experiment in your analysis tool.
</Tip>

The file is named `quest_{questId}_data.csv`.

## Participant Operations

Use **Manage Participants** to open the participant workspace for a quest. See [Managing Participants](/quests/managing-participants) for full documentation on the participants page, including:

* reviewing joined participants and their lifecycle status
* filtering by cohort and status
* updating participant status (enrolled → active → completed, etc.)
* assigning or removing cohort membership
* API reference for programmatic access

## Schedule & Compliance

The quest detail page also includes a compact **Schedule & Compliance** panel. Use it to:

* select a cohort
* save a **baseline** offset in days
* save a **follow-up** offset in days
* review whether each participant is `upcoming`, `due`, `overdue`, or `completed`
* mark baseline or follow-up as complete when needed

<Info>
  This panel is intentionally narrow today: it supports baseline and follow-up checkpoints rather than a full visit-calendar system.
</Info>

## Health Data (Graph View)

If your quest collects health metrics (steps, sleep, heart rate), the page includes a **graph view** showing trends over the past week.

Use the **category selector** to switch between:

| Category   | Metric                  |
| ---------- | ----------------------- |
| Steps      | Daily step count        |
| Sleep      | Sleep duration          |
| Heart Rate | Heart rate measurements |

Each participant's data is plotted as a separate series on the line chart.

## Vital User Mapping

If your quest is integrated with the Vital API for wearable data, a **Get Vital to Fusion User Mapping** button appears in the action bar. Clicking it downloads a CSV mapping Vital user IDs to NeuroFusion user GUIDs — useful for reconciling wearable data with participant identities.

## Refreshing Data

Click the **Refresh** button to reload all datasets from the server. This fetches the latest submissions without reloading the entire page.

## Next Steps

<CardGroup>
  <Card title="Running a Study" icon="microscope" href="/quests/running-a-study">
    Full lifecycle guide including monitoring and export.
  </Card>

  <Card title="Participant Journey" icon="users" href="/quests/participant-journey">
    See the participant flow from onboarding to submitted datasets.
  </Card>

  <Card title="Sharing & Publishing" icon="share" href="/quests/sharing-and-publishing">
    Publish your quest and share it with participants.
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.usefusion.ai/quickstart

Go from sign-up to a published quest in under 5 minutes.

This guide walks you through creating your first quest with prompts, experiments, and onboarding — then publishing it for participants.

## 1. Sign Up

Go to [usefusion.ai](https://usefusion.ai) and create an account. You'll be signed in and taken to your dashboard.

<Frame>
  <img alt="Choose your username dialog with input field and Continue button" />
</Frame>

## 2. Create an Organization

Every quest belongs to an organization. You must create one before you can create quests.

1. Navigate to **Organizations** in the sidebar
2. Click **Create Organization**
3. Enter a name and billing email (required), plus an optional description
4. Your new org starts with **free bonus credits**

<Info>
  You can create multiple organizations — for example, one per lab, project, or study.
</Info>

## 3. Create a Quest

1. Go to **Quests** and click **Create Quest**
2. Select which organization the quest belongs to using the **org selector dropdown**
3. Fill in the quest title, description, and category

## 4. Add Prompts

Prompts are recurring questions delivered to participants on a schedule. Every quest needs at least one.

1. Click **Add Prompt**
2. Enter the prompt text (e.g., *"How are you feeling right now?"*)
3. Choose a **response type**: Yes/No, Text, Number, Number Range, or Custom Options
4. Select a **category** (e.g., Mental Health, Productivity)
5. Set the **schedule**: which days, what time window, and how often

<Info>
  See [Prompts](/prompts/overview) for the full guide on response types, categories, scheduling, and conditional notifications.
</Info>

## 5. Add an Experiment (Optional)

Experiments are interactive jsPsych tasks that participants complete.

1. Click **Add Experiment**
2. Enter a name and optional description
3. The code editor opens with a default **jsPsych 8.0.3 template** — edit it or paste your own code
4. Use the **live preview** to test your experiment
5. Upload images, audio, or video using the **media uploader**

<Info>
  See [Experiments](/experiments/overview) for the full experiment editor guide, media uploads, and ordering.
</Info>

## 6. Configure Onboarding (Optional)

Onboarding lets you show a consent form and screen participants before they join.

1. Write a **full-text overview** with your informed consent language, study purpose, and data usage
2. Add **onboarding questions** for eligibility screening (e.g., *"How old are you?"*)
3. Set **question guards** to block ineligible participants (e.g., must be 18 or older)

<Info>
  See [Onboarding & Consent](/onboarding/overview) for the full onboarding configuration guide.
</Info>

## 7. Save and Publish

1. Click **Save** — this generates a unique quest URL and enables media uploads
2. Click **Publish** to make the quest available to participants (consumes credits — see [Pricing](https://usefusion.ai/pricing))
3. Share the quest link directly, via QR code, or paste it as a Prolific study URL

## What Happens Next

* **Participants** open the quest link → complete onboarding → answer prompts on schedule → complete experiments
* **You** monitor responses, billing, and participant data from the organization dashboard
* **Data** is stored securely and can be exported for analysis

## Next Steps

<CardGroup>
  <Card title="Quest Overview" icon="scroll" href="/quests/overview">
    Learn about quest anatomy and configuration.
  </Card>

  <Card title="Run a Study" icon="microscope" href="/quests/running-a-study">
    End-to-end guide for running a research study.
  </Card>

  <Card title="Organizations" icon="building" href="/organizations/overview">
    Set up teams with permissions and shared billing.
  </Card>

  <Card title="Prolific Integration" icon="plug" href="/integrations/prolific">
    Recruit participants through Prolific.
  </Card>
</CardGroup>


# AI Denoising
Source: https://docs.usefusion.ai/recordings/ai-denoising

Clean EEG signals with ZUNA foundation model — remove artifacts while preserving neural activity

# AI Denoising with ZUNA

ZUNA is a diffusion-based foundation model trained on large-scale EEG data. It removes noise artifacts from brain recordings while preserving the underlying neural signals.

## What Gets Cleaned

| Artifact Type    | Source                      | Effect on EEG                    |
| ---------------- | --------------------------- | -------------------------------- |
| **Eye blinks**   | Eyelid movement             | Large frontal spikes (50–200 µV) |
| **Saccades**     | Eye movement                | Lateral voltage shifts           |
| **Muscle (EMG)** | Jaw, forehead, neck         | High-frequency broadband noise   |
| **Line noise**   | Power outlets               | 50/60 Hz sinusoidal interference |
| **Drift**        | Electrode impedance changes | Slow baseline wander             |
| **Movement**     | Head or cable motion        | Large transient artifacts        |

## What Gets Preserved

* **Neural oscillations** — Alpha (8–13 Hz), beta (13–30 Hz), theta (4–8 Hz), delta (1–4 Hz), gamma (30+ Hz)
* **Event-related potentials** — P300, N170, N400, and other cognitive markers
* **Resting-state patterns** — Eyes-open vs eyes-closed alpha differences
* **Task-related changes** — Frequency power shifts during cognitive tasks

## Processing Pipeline

```
Raw CSV → Parse channels → Resample to 256 Hz → Filter → Epoch (5s segments)
    → Normalize → ZUNA GPU inference → Denormalize → Reconstruct continuous signal
```

### Technical Details

* **Epoch size**: 5 seconds (1,280 samples at 256 Hz)
* **Overlap**: Adjacent epochs for seamless reconstruction
* **Normalization**: Per-epoch z-score normalization before inference, reversed after
* **GPU**: NVIDIA A100 80GB VRAM

## Using Denoising

### From the Recordings Page

1. Record live EEG or upload a CSV file
2. Click **"🧹 Denoise Recording"**
3. Wait for processing (5–15 seconds if GPU is warm)
4. View the **before/after comparison** — raw signal on the left, denoised on the right
5. Download the cleaned CSV or send to the Analysis page

### From the API

For programmatic access, POST to `/api/eeg-models/inference`:

```bash theme={null}
curl -X POST https://usefusion.ai/api/eeg-models/inference \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "denoise",
    "eeg": {
      "csv_content": "CP3,C3,F5,PO3,PO4,F6,C4,CP4\n12.3,8.1,...",
      "device_type": "neurosity",
      "sfreq": 256
    },
    "output_format": "json"
  }'
```

See the [API Reference](/model-apis/api-reference) for full endpoint documentation.

## GPU Management

The ZUNA model runs on a dedicated GPU VM that auto-manages its lifecycle:

### Auto-Sleep

The VM deallocates after **30 minutes** of inactivity. This stops compute billing while preserving the disk. The GPU status indicator on the recordings page shows current state.

### Auto-Wake

When you trigger denoising and the GPU is sleeping:

1. The backend detects the VM is deallocated
2. It sends a start command and returns HTTP 202
3. The frontend **automatically retries** every 15 seconds (up to 6 times)
4. You see live status updates: "GPU is starting up. Auto-retrying in 15s..."
5. Once the VM is ready (\~90 seconds), your denoising request processes normally

<Tip>
  If you know you'll need the GPU soon, click **"Wake GPU"** in the status bar at the top of the recordings page. This starts the VM immediately so it's ready when you finish recording.
</Tip>

### Status Indicators

| Indicator           | Meaning                                        |
| ------------------- | ---------------------------------------------- |
| 🟢 Green            | GPU ready — denoising will start immediately   |
| 🟡 Yellow (pulsing) | GPU starting up — will be ready in \~90s       |
| ⚫ Gray              | GPU sleeping — will auto-wake on first request |

## Before / After Comparison

After denoising, the recordings page shows a side-by-side comparison:

* **Left panel (red label)** — Your original raw recording with all artifacts visible
* **Right panel (green label)** — The ZUNA-denoised output

Both use the same amplitude scale and time axis. You can adjust the scale (±50, ±100, ±200 µV) and zoom/pan with the scroll bar to inspect specific time windows.

This comparison helps you:

* Verify that artifacts were removed (look for smoothed-out eye blink spikes)
* Confirm neural features are preserved (alpha oscillations should remain intact)
* Decide if the denoising quality is sufficient for your analysis

## Other ZUNA Tasks

Beyond denoising, ZUNA supports two additional tasks:

### Reconstruct

Recover missing or corrupted EEG channels using the spatial relationships learned from healthy data. Useful when one electrode has poor contact.

### Upsample

Expand a low-density recording (e.g., 4-channel Muse) to estimate what a higher-density montage would look like. This is experimental and best used for exploratory visualization.

Both tasks use the same API endpoint with `task: "reconstruct"` or `task: "upsample"`. See [API Reference](/model-apis/api-reference) for details.


# Brain Recordings
Source: https://docs.usefusion.ai/recordings/overview

Record, visualize, and clean EEG brain signals in real-time with AI-powered denoising

# Brain Recordings

The **Recordings** page (`/recordings`) is your central hub for capturing and cleaning brain signals. Connect an EEG device, record live data, check signal quality in real-time, then denoise your recording with ZUNA — all in one flow.

```
Connect Device → Record EEG → Check Signal Quality → Stop → Denoise with ZUNA → Compare Before/After → Download
```

## Three Recording Modes

The page offers three modes, selectable via tabs at the top:

### 🧠 Live Recording

Connect your EEG headset and capture brain activity in real-time.

1. **Connect** — Choose your device (Neurosity Crown or Muse) and click Connect. The Muse uses Web Bluetooth; Neurosity uses OAuth.
2. **Record** — Hit Start Recording. You'll see a live waveform and a signal quality panel showing per-channel contact quality.
3. **Review** — Stop recording when you have enough data (minimum 6 seconds for ZUNA).
4. **Denoise** — Click "Denoise Recording" to send your data to the ZUNA GPU for artifact removal.

<Info>
  Record at least **6 seconds** — ZUNA processes in 5-second epochs and needs one full epoch plus a small buffer.
</Info>

### 📁 Upload CSV

Upload a previously recorded EEG file in CSV format. The page auto-detects whether the file came from a Neurosity Crown or Muse based on channel names in the header row.

* Supported formats: CSV with channel columns (e.g., `CP3,C3,F5,PO3,PO4,F6,C4,CP4` for Crown)
* Values should be in **microvolts (µV)**
* Optional timestamp column

### 🧪 Experiments

Run cognitive experiments (Stroop, Oddball, P300, etc.) from the built-in experiment library. An **experimental** panel lets you simultaneously record EEG during the experiment:

1. Choose an experiment from the dropdown
2. Expand the "Record EEG during experiment" panel
3. Connect your device and start recording
4. Run the experiment — brain activity is captured alongside
5. Stop and denoise when the experiment completes

<Note>
  The experiment recording feature is marked as **Experimental**. It records EEG in parallel with the jsPsych experiment but does not yet embed event markers into the EEG timeline.
</Note>

## Live Signal Quality

During active recording, a **Signal Quality** panel appears showing:

* **Bar chart** — Standard deviation per channel. Green (1.5–10) = great, Yellow (10–15) = good, Red (>15) = poor contact
* **Brain montage** — Top-down 2D head map with electrode positions colored by quality

This helps you adjust headset fit before committing to a long recording. Once most channels are green, your data will be high quality.

## ZUNA AI Denoising

After recording or uploading, the "Clean with ZUNA AI" step sends your EEG data to the ZUNA foundation model running on an NVIDIA A100 GPU.

### What ZUNA Removes

| Artifact            | Example                                               |
| ------------------- | ----------------------------------------------------- |
| Eye blinks          | Frontal voltage spikes from blinking                  |
| Muscle activity     | EMG from jaw clenching, forehead tension              |
| Environmental noise | 50/60 Hz line noise, cable movement                   |
| Drift               | Slow baseline wander from electrode impedance changes |

### What ZUNA Preserves

Neural oscillations (alpha, beta, theta, delta, gamma), event-related potentials (P300, N170), and other brain-generated signals.

### GPU Auto-Wake

The GPU VM auto-sleeps after 30 minutes of inactivity to minimize costs. When you trigger denoising:

1. If the GPU is **ready** — processing starts immediately (\~5–15s depending on recording length)
2. If the GPU is **sleeping** — the page automatically wakes it and retries every 15 seconds (up to 6 attempts). You'll see status updates like "Auto-retrying in 15s... (attempt 2/6)"
3. The GPU status indicator at the top of the page shows real-time availability (green = ready, yellow = starting, gray = sleeping)

You can also manually wake the GPU by clicking "Wake GPU" in the status bar.

## Before / After Comparison

After denoising completes, the page shows a **side-by-side comparison**:

| Left Panel                             | Right Panel                           |
| -------------------------------------- | ------------------------------------- |
| **Before — Raw Signal**                | **After — ZUNA Denoised**             |
| Your original recording with artifacts | Cleaned signal with artifacts removed |

Both panels use the same scale (±50 µV, adjustable) and time axis so you can directly compare waveform quality. The raw signal is captured at the moment you click Denoise, ensuring an accurate snapshot.

## After Denoising

Once denoising is complete, you have several options:

* **📥 Download Denoised CSV** — Export the cleaned signal as a CSV file for offline analysis in MATLAB, Python, or other tools
* **📊 View in Analysis** — Navigate to the `/analysis` page for deeper inspection, power spectral density, and more
* **Re-record** — Start a new recording and denoise again

### Result Summary

The results card shows key metadata:

| Field       | Description                                       |
| ----------- | ------------------------------------------------- |
| Input       | Number of channels and duration of your recording |
| Output      | Channels and duration after processing            |
| Channels    | List of EEG channel names in the output           |
| Sample Rate | Output sampling frequency (256 Hz)                |

## Supported Devices

| Device              | Channels                               | Connection        |
| ------------------- | -------------------------------------- | ----------------- |
| **Neurosity Crown** | 8 (CP3, C3, F5, PO3, PO4, F6, C4, CP4) | Bluetooth + OAuth |
| **Muse 2 / Muse S** | 4 (TP9, AF7, AF8, TP10)                | Web Bluetooth     |

Both devices stream at **256 Hz**. See [Brain Interfaces](/integrations/brain-interfaces) for detailed setup instructions.

## End-to-End Flow

```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  EEG Device  │────▶│  /recordings │────▶│  Backend API │────▶│  ZUNA GPU    │
│  Crown/Muse  │     │  Live viewer │     │  Auto-wake   │     │  A100 80GB   │
└──────────────┘     │  Sig quality │     │  /eeg-models │     │  Denoise     │
                     └──────┬───────┘     └──────────────┘     └──────┬───────┘
                            │                                         │
                            ▼                                         ▼
                     ┌──────────────┐                          ┌──────────────┐
                     │  Before/After│◀─────────────────────────│  Cleaned EEG │
                     │  Comparison  │                          │  JSON/CSV    │
                     └──────┬───────┘                          └──────────────┘
                            │
                     ┌──────▼───────┐
                     │  Download /  │
                     │  Analysis    │
                     └──────────────┘
```

For programmatic access to ZUNA (without the UI), see the [Model APIs](/model-apis/overview) documentation.


# Signal Quality
Source: https://docs.usefusion.ai/recordings/signal-quality

Monitor electrode contact quality in real-time during EEG recording

# Signal Quality

Good EEG data starts with good electrode contact. The recordings page shows real-time signal quality metrics during active recording so you can adjust headset fit before capturing important data.

## How It Works

Signal quality is calculated from the **standard deviation** of voltage values over a 1-second sliding window (256 samples at 256 Hz). Lower deviation means cleaner, more stable signal.

| Standard Deviation (µV) | Rating     | Bar Color | Meaning                           |
| ----------------------- | ---------- | --------- | --------------------------------- |
| 1.5 – 10                | Great      | 🟩 Green  | Clean neural signal, good contact |
| 10 – 15                 | Good       | 🟨 Yellow | Acceptable, minor noise           |
| > 15                    | Poor       | 🟥 Red    | High noise, adjust electrode      |
| \< 1.5                  | No contact | ⬜ Gray    | Electrode not touching scalp      |

## Quality Panel

During recording, two views appear:

### Bar Chart

A per-channel bar chart updating every second. Each bar is colored by the quality rating above. Aim for mostly green bars before starting your real recording.

### Brain Montage (2D)

A top-down head diagram (nose at top) showing electrode positions from the 10-20 system. Each electrode dot is colored by its current quality rating, giving you a spatial sense of where contact is poor.

## Tips for Good Signal

<CardGroup>
  <Card title="Neurosity Crown" icon="brain">
    * Dampen the rubber sensors with saline or water
    * Press the band firmly against the back of your head
    * Check that forehead sensors (F5, F6) have contact — push hair aside if needed
    * Sit still for 5 seconds and watch the quality bars settle
  </Card>

  <Card title="Muse Headband" icon="head-side-brain">
    * Ensure the forehead sensors (AF7, AF8) sit flat on skin, not on hair
    * The ear sensors (TP9, TP10) should press firmly behind each ear
    * Tighten the band if temporal channels show poor quality
    * Relax your jaw — jaw clenching adds muscle artifacts
  </Card>
</CardGroup>

## When to Start Recording

* **All green**: Ideal — start immediately
* **Mostly green, one yellow**: Acceptable for most analyses. ZUNA can clean mild artifacts
* **Red or gray channels**: Adjust the headset. Red means high noise; gray means no contact at all

<Warning>
  ZUNA can remove many artifacts, but it works best when the raw signal has decent contact quality. Starting with poor signal quality means losing neural information that can't be recovered.
</Warning>