Skip to main content

Adding ID Lists

Create an ID list for a segment

An ID list enables you specify the user IDs or stable IDs that you want to target as a reusable segment.

Assuming you have created a segment of type ID List,

  • If you're not already there, navigate to the segment page on
  • Click the Edit button in the ID List panel
  • Enter the list of identifiers and click Confirm


You can also sync in an ID list Segment from sources like an Amplitude Cohorts or Segment Audiences or from a custom source using the Console API

There is a hard limit of 10 million IDs across all ID Lists in your project.

Keep ID Lists Small(!)

When an ID List is small (no more than 1000 IDs), it is synchronized in the same process with other feature gates, experiments, and conditional segments, which has high consistency and reliability. Once an ID List goes over 1000 in size, to scale efficiently and not negatively impact the other entities as the lists grow, there is a separate process to synchronize them. As a result, they are not downloaded in the main initialization process (in the initialization path of server SDKs, or the local evaluation version of our client SDKs), and change propagation takes longer.

We recommend always keeping your ID Lists to be no more than 1000 IDs in each, unless you are okay with the caveats mentioned above.

Very Large ID Lists(!)

Evaluating ID Lists requires Statsig to sync down to each instance of the server SDK a copy of the ID List; and then keep syncing any changes made to this list. Having very large ID Lists will extend how long your servers take to initialize the Statsig SDK. Changes to the ID List are synced lazily without blocking other updates to your configuration in Statsig. Client SDKs work great with ID Lists - since it's only the results of the evaluation for a single user that are sent down to the Client SDK.

To target hundreds of thousands of users (or billions), the preferred pattern is to set an attribute on the User object passed to the Statsig SDK. e.g. pass in user_type:Paid or user_type:Trial in the User object, instead of having ID Lists that enumerate the Paid and Trial users. This does require your app to have this information when calling the Statsig SDK, but you're better able to control how/where to cache this information.