---
title: How layer allocation works
description: "How Statsig assigns users to experiments in a layer with layer buckets, and what happens to those users when you change an experiment's allocation or stop an experiment."
product: general
lang: en
token_estimate: 1112
---
# How layer allocation works

Statsig divides each [layer](https://docs.statsig.com/experiments/layers-overview) into 1,000 buckets and gives each experiment in the layer its own set of buckets. Bucket ownership decides which experiment a user enters, what happens to users when an experiment's allocation changes, and which users a new experiment in the layer receives.

> For AI agents: a documentation index is available at [/llms.txt](/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

## How Statsig assigns users in a layer

Statsig assigns a user to an experiment in a layer in two independent steps:

1. **Layer allocation**: Statsig hashes the user's unit ID with the layer's salt and places the user in one of 1,000 layer buckets. Each experiment in the layer owns a specific set of buckets, and no two experiments share a bucket. The experiment that owns the user's bucket receives the user. If no experiment owns the bucket, the user receives the layer's default values.
2. **Group assignment**: Statsig hashes the unit ID again with the experiment's own salt to choose the user's group, such as control or test.

The two steps use different salts, so a user's layer bucket doesn't influence the user's group assignment. Statsig always places the same unit ID in the same layer bucket, so assignment stays consistent across sessions and SDKs.

Statsig checks the experiment's targeting gate after layer allocation. A user who fails the targeting gate receives the layer's default values. Statsig doesn't move the user to another experiment in the layer. Overrides and holdouts apply before layer allocation. For the full evaluation order, refer to [How evaluation works](https://docs.statsig.com/sdks/how-evaluation-works#evaluation-order).

## Change an experiment's allocation in a layer

An experiment's allocation in a layer is the share of layer buckets it owns. Changing one experiment's allocation doesn't reassign users in the other experiments in the layer.

- **Increase allocation**: Statsig gives the experiment more buckets from the layer's unallocated buckets. Users already in the experiment keep their buckets and groups. The increase can't exceed the number of unallocated buckets in the layer.
- **Decrease allocation**: Statsig removes some of the experiment's buckets. Users in the removed buckets leave the experiment and receive the layer's default values. Users in the remaining buckets keep their assignment. Decreasing allocation biases your results, so reset the experiment instead where possible. Refer to [Allocation](https://docs.statsig.com/experiments/setup/allocation-and-targeting#allocation).
- **Decrease, then increase**: The buckets the experiment regains can contain different users from the users who left. Only users in buckets the experiment kept throughout stay in the experiment continuously.
- **Shift allocation between experiments**: When you decrease one experiment's allocation and increase another's, the second experiment can receive the freed buckets. Users who stay in either experiment keep their assignment.

Experiment allocation works differently from a feature gate's percentage rollout. A gate uses a fixed threshold, so changing a gate's rollout from 50% to 0% and back to 50% re-exposes the same users. An experiment owns an explicit set of buckets, so the same change to an experiment's allocation doesn't guarantee the same users.

## What happens to buckets when an experiment in a layer stops

When an experiment in a layer stops, its buckets become unallocated. Statsig doesn't rearrange the other experiments' buckets. A new experiment receives buckets from all unallocated buckets in the layer. Those buckets can include both previously unallocated buckets and buckets that the stopped experiment released.

Mutual exclusion applies only to experiments that run at the same time. A layer doesn't track which buckets a stopped experiment used, so users in a new experiment might have been in an earlier experiment in the layer.

When you ship an experiment in a layer that has no targeting gate, Statsig releases the experiment's buckets and the shipped group's values become the layer's default values. When the experiment has a targeting gate, Statsig adds an override to the layer instead. For how shipped values reach users in each case, refer to [Make a decision](https://docs.statsig.com/experiments/ending/make-decision).

