Statsig
Sync events and audience segments to Statsig for feature flag targeting and product experimentation. Zeotap can log custom events to Statsig’s analytics engine and manage ID list segment membership for precise feature flag targeting based on your warehouse data.
Prerequisites
- A Statsig account with access to Project Settings > Keys & Environments
- For event syncs: a Server Secret Key
- For segment syncs: a Console API Key and an existing ID list segment
Authentication
Statsig uses API key authentication. Different keys are required depending on the object type you are syncing.
Server Secret Key (for Events)
- In the Statsig console, navigate to Project Settings > Keys & Environments
- Copy your Server Secret Key (starts with
secret-) - Paste it into the Server Secret Key field in Zeotap
Console API Key (for Segments)
- In the Statsig console, navigate to Project Settings > Keys & Environments
- Under Console API Keys, click Generate New Key (or copy an existing one)
- Paste it into the Console API Key field in Zeotap
Configuration
| Field | Type | Required | Description |
|---|---|---|---|
| Object Type | Select | Yes | The type of data to sync: Events or Segments (ID List) |
Target Settings
Events
| Field | Type | Required | Description |
|---|---|---|---|
| Event Name | Text | No | A static event name for all rows. Leave blank to use a mapped event_name column. |
| Environment Tier | Select | No | Statsig environment tier: Production, Staging, or Development |
Segments
| Field | Type | Required | Description |
|---|---|---|---|
| Segment ID | Text | Yes | The ID of the Statsig segment (must be an ID list type segment) |
| ID Type | Select | No | The identifier type for the segment. Default: user_id. Options: user_id, stable_id, custom_id |
Supported Operations
Sync Modes
| Mode | Supported |
|---|---|
| Insert | Yes |
| Upsert | — |
| Update | — |
| Mirror | — |
Sync modes apply to event syncs. Events are append-only and cannot be updated or deleted.
Audience Sync Modes
| Mode | Supported |
|---|---|
| Add | Yes |
| Remove | Yes |
| Mirror | Yes |
Audience sync modes apply to segment syncs. Zeotap adds or removes user IDs from ID list segments.
Features
- Field Mapping: Yes (map source columns to event fields and user properties)
- Schema Introspection: No
Required Mapping Fields
| Field | Description |
|---|---|
| user_id | The unique user identifier for Statsig |
Default Destination Fields
| Field | Type | Applies To |
|---|---|---|
user_id | string | Events and Segments |
event_name | string | Events only |
event_value | string | Events only |
event_time | timestamp | Events only |
email | string | Events and Segments |
country | string | Events and Segments |
custom | json | Events and Segments |
How It Works
Event Syncs
- Zeotap maps your source columns to Statsig event fields
- Events are batched in groups of up to 500 per API request
- Each event is sent to the Statsig HTTP API at
events.statsigapi.net/v1/log_event - The event includes a user object (with
userID,email,country, and custom properties), an event name, optional value, and optional timestamp - Unmapped columns are included as event metadata (key-value string pairs)
- If configured, the environment tier is set on the user object for environment-specific analytics
Segment Syncs
- Zeotap extracts user IDs from your model or audience
- For Add mode, IDs are added to the segment’s ID list via the Console API (
PATCH) - For Remove mode, IDs are removed from the segment’s ID list via the Console API (
DELETE) - For Mirror mode, added/changed IDs are added and removed IDs are deleted, keeping the segment in sync with your warehouse
- IDs are sent in batches of up to 10,000 per API request
Rate Limits
Events API
The Statsig HTTP API accepts batches of events with automatic rate limiting. Zeotap handles retries with exponential backoff and respects Retry-After headers.
Console API (Segments)
Statsig enforces rate limits on the Console API:
- Approximately 100 requests per 10 seconds
- Approximately 900 requests per 15 minutes
Zeotap automatically handles rate limiting with exponential backoff.
Segment Size Limits
Statsig has a hard limit of 10 million IDs across all ID lists per project. Individual ID lists perform best when kept under 1,000 IDs. Lists exceeding 10,000 IDs may experience slower propagation.
Best Practices
- Use Events object type for logging conversion events, user actions, or metric data from your warehouse
- Use Segments object type for syncing audience lists for feature flag targeting
- Set an explicit Event Name in target settings when all rows represent the same event type
- Use the Environment Tier setting to separate development and production events
- For segment syncs, use Mirror mode to keep Statsig segments fully in sync with your warehouse audiences
- Create dedicated API keys for Zeotap with the minimum required scope
- Keep ID lists under the recommended size limits for optimal propagation speed
Troubleshooting
Authentication failed: invalid server secret key
Verify your Server Secret Key starts with secret- and is copied in full from Project Settings > Keys & Environments. Server Secret Keys are different from Client SDK Keys and Console API Keys.
Authentication failed: invalid console API key
Ensure you are using a Console API Key (not a Server Secret Key or Client SDK Key). Console API Keys are found under the Console API Keys section in Project Settings > Keys & Environments.
Segment must be of type “id_list”
The Statsig segment you specified is not an ID list segment. Only segments created as ID list type can be modified via the API. Create a new segment with the ID List type in the Statsig console.
Segment not found
Verify the segment ID is correct. The segment ID can be found in the Statsig console under Segments. It is the identifier shown in the segment URL or settings, not the display name.
Events not appearing in Statsig
Events may take a few minutes to appear in the Statsig console. If events still do not appear after 10 minutes, verify:
- The Server Secret Key is valid and active
- The
event_namefield is mapped or set in target settings (events without a name are dropped) - The
user_idfield is mapped correctly
Rate limit errors
If you see rate limit errors for segment syncs, the Console API enforces strict limits (~100 requests per 10 seconds). Zeotap retries automatically, but large syncs may take longer. Consider reducing sync frequency or audience size if limits are consistently hit.
Mirror mode removing unexpected users
Mirror mode synchronizes the segment to exactly match your audience. Users not in the current audience will be removed from the ID list. If you only want to add users without removing existing ones, use Add mode instead.
Custom properties not appearing
Ensure the custom field contains valid JSON. The field should be a JSON object with string keys. Non-JSON values in the custom column are silently ignored.