Sessions & balancing

The Web Console has three settings for controlling who runs the experiment and how the data is balanced:

• maxSessionCount — total cap on how many sessions can ever run for this experiment.
• excludedSessionIds — drop specific sessions (one bad run, a power outage, an obvious outlier) from the condition-balancer's counts.
• excludedParticipantIds — drop specific participants (and all their sessions) from the condition-balancer's counts.

Together these let you collect a fixed-size sample, drop unusable data, and keep between-subjects conditions evenly distributed without manual rebalancing. If used carelessly, they can also lead to overcollection, undercollection, or unexpected bias in between-subjects assignment.

Screenshot pending — the Sessions panel on the experiment detail page, showing maxSessionCount = 50, six excluded sessions, and one excluded participant.

maxSessionCount — total session cap

A non-negative integer; defaults to 0 meaning unlimited. Once the experiment has accumulated this many sessions, the eligibility check (callExternal type=checkJoinEligibility) starts returning eligible: false for new joiners.

What counts as a "session":

• Each unique sID (session ID) generated by the eligibility check counts as one session.
• Test sessions (isTestMode=true on the Unity side) do count against the cap unless they were also excluded.
• A session that started but never reached End (participant left, hardware crashed) still counts.

Practical workflow:

1. Pilot phase — set maxSessionCount = 10. Run pilots, debug, then exclude any pilot sessions you don't want to count toward analyses.
2. Main run — bump to 50 (or whatever your power analysis requires). The cap protects you from collecting forever.
3. Cap hit — sessions complete normally; new joiners get rejected. You can bump the cap up to extend collection, or flip the experiment's Status to TESTING to remove it from the Recruitment World board.

excludedSessionIds — drop a session from the balancer

A list of sID (session ID) strings. Sessions in this list are not counted by the between-subjects condition balancer, which means the next session's assignment will treat them as if they didn't happen.

When to add a session to the exclude list:

• A session crashed before reaching the trial loop. Its between-subjects assignment was made but no usable data was collected.
• A participant abandoned the experiment partway through.
• Hardware failure on the participant's side.
• Test sessions from isTestMode=true runs that should be ignored for analysis purposes.

Adding an sID here means:

• Balancer ignores it. The next session's between-subjects assignment treats this session as nonexistent — so if you'd otherwise have an imbalance because of this session, excluding it restores the balance.
• Data downloads still show it. Excluding from the balancer does not delete the session's data. You can still download whatever questionnaire answers, participant info, or custom logs the session produced — useful for diagnosing why it failed.
• maxSessionCount still counts it. See above.

To get an sID to exclude: look at the Sessions tab of the experiment detail page (or in the downloaded data — every record carries sID). Copy and paste into the exclude list.

excludedParticipantIds — drop a participant entirely

A list of participant identifiers (Cluster's IDFC). Every session belonging to a listed participant is treated as if it didn't happen — for both balancing and (depending on your analytics pipeline) for data analysis.

When to add a participant to the exclude list:

• Participant turned out not to meet the prerequisites (e.g., self-reported epilepsy after running).
• Participant joined under multiple Cluster accounts to grief or to game the reward.
• Pilot or test participants from your lab that you don't want to mix in.

The Web Console persists this list and consults it on every eligibility check: the participant can still attempt to join (Cluster doesn't block them at the door — there's no per-participant ban mechanism in CCK), but the eligibility check returns eligible: false and their session is rejected before it starts.

To get a participant's IDFC: pull it from any of their existing session records (visible in the Participant Info data export).

How the balancer uses these lists

The between-subjects condition assignment runs at session start, when the first eligible participant joins. It looks at existing sessions for the same experiment (existingConditions per Concepts → Conditions, sessions, participants) and applies a least-frequent-condition-first rule. Excluded sessions and excluded participants' sessions are filtered out of that lookup.

A practical consequence: if you accidentally over-assigned one between-subjects condition (e.g., the first 10 participants all got order=AB due to bad luck), you can rebalance by excluding the worst overrepresented sessions, and the next several joiners will be steered toward the underrepresented condition.

Where the values are stored

All three are columns on the Experiment Prisma model:

• maxSessionCount: Int (default 0).
• excludedSessionIds: String[] (Prisma List field).
• excludedParticipantIds: String[] (Prisma List field).

The lists are simple JSON arrays under the hood — the Web Console UI exposes add/remove buttons but the underlying storage is just an array of strings.

Common pitfalls

• Excluding only the data, not the participant. If a participant runs the experiment twice (e.g., once as a pilot, once for real) and you only exclude the pilot session, their second session counts. If you want their entire history out, exclude the IDFC instead.
• Forgetting to clear the test exclusions before launch. During pilot, you might exclude every test sID you generated. Before going live, make sure those exclusions don't shadow legitimate sessions that happen to share an sID (they won't, but be deliberate).
• Misreading "rejected" as "blocked." Excluded participants can still try to join (Cluster doesn't have a hard ban). They just get a rejection toast and bounced from the experiment. They won't be filtered from your Recruitment World listing.
• Capping maxSessionCount too tight. Once hit, no more participants can join — even if some were partway through onboarding. Set the cap with headroom for late-arriving sessions in your collection window.

Where to go next

• Concepts → Conditions, sessions, participants — the session-start handshake and the between-subjects balancing algorithm.
• Creating an experiment — where you first set maxSessionCount.
• Platform & avatar settings — the related eligibility-check field for which devices can join.
• Reference → Web Console API → checkJoinEligibility — the dispatch type that reads all three fields above.