Split
Sync audience segments to Split for feature flag targeting. Zeotap pushes user keys into Split segments, enabling you to target feature flags and experiments based on your warehouse-defined audiences.
Prerequisites
- A Split account with access to the Admin API
- An Admin API key with write permissions on segments
- The workspace ID, environment ID, and traffic type for your Split project
- An existing segment enabled in the target environment
Permissions
The Admin API key must have permissions to:
- List segments in the workspace
- Upload and remove keys from segments in the target environment
Authentication
Split uses Admin API Key authentication.
- In Split, navigate to Admin settings > API keys
- Click Create API key
- Select Admin as the API key type
- Assign a role with segment write permissions
- Copy the generated API key
- Paste it into the Admin API Key field in Zeotap
Configuration
| Field | Type | Required | Description |
|---|---|---|---|
| Workspace ID | Text | Yes | The Split workspace (project) ID. Found in Admin settings > Workspaces. |
| Environment ID | Text | Yes | The Split environment ID for the target environment (e.g., production). Found in Admin settings > Environments. |
| Traffic Type | Text | Yes | The traffic type for segments (e.g., user, account). Segments are scoped to a traffic type. |
Target Settings
| Field | Type | Required | Description |
|---|---|---|---|
| Segment Name | Text | Yes | The name of an existing segment in Split. The segment must be created and enabled in the target environment before syncing. |
Supported Operations
Sync Modes
Split segments are list-based and do not support record-level sync modes.
Audience Sync Modes
| Mode | Supported |
|---|---|
| Add | Yes |
| Remove | Yes |
| Mirror | Yes |
Features
- Field Mapping: No (segments only use keys)
- Schema Introspection: No
Required Mapping Fields
| Field | Description |
|---|---|
| key | The unique identifier for each user or entity in the Split segment |
Default Destination Fields
key
How It Works
- Zeotap extracts keys from your model or audience
- Keys are sent to the Split Admin API to update segment membership
- For Add mode, keys are uploaded to the segment using the
uploadKeysendpoint - For Remove mode, keys are removed from the segment using the
removeKeysendpoint - For Mirror mode, added/changed keys are uploaded and removed keys are deleted — keeping the segment in sync with your warehouse
Keys are sent in batches of up to 10,000 per API request, which is the maximum allowed by Split’s Admin API.
Rate Limits
Split enforces rate limits at both the organization and IP level. Rate-limited requests return HTTP 429 with X-RateLimit-Remaining-Org and X-RateLimit-Remaining-IP headers. Zeotap automatically handles rate limiting with exponential backoff and respects retry headers.
Best Practices
- Use Mirror mode to keep segments fully in sync with your warehouse data
- Create dedicated Admin API keys for Zeotap with minimal required permissions
- Use descriptive segment names that reflect the audience purpose (e.g.,
beta-users,high-value-customers) - Start with a non-production environment to verify sync behavior before targeting production
- Be aware of the 100,000 key limit per segment — split large audiences across multiple segments if needed
Troubleshooting
Authentication failed
Verify your Admin API key is valid and has the required permissions. Admin API keys can be managed in Admin settings > API keys. Note that SDK keys and client-side API keys cannot access the Admin API.
Workspace not found
Ensure the workspace ID is correct. You can find your workspace ID in Admin settings > Workspaces. The ID is a UUID, not the workspace name.
Environment not found
Verify the environment ID is correct. The environment ID can be found in Admin settings > Environments. Make sure you are using the environment ID (UUID), not the environment name.
Segment not found
If using an existing segment, verify the segment name is correct and that it exists in the specified workspace. Segment names are case-sensitive.
Rate limit errors
Split rate limits are applied at both the organization and IP level. If other integrations or team members are making heavy API use, you may see rate limit errors. Zeotap retries automatically, but persistent issues may require reducing concurrent API usage.
Keys not appearing in segment
Verify that the segment is enabled in the target environment. Segments must be activated in each environment where they are used. Also confirm the traffic type matches what your Split SDKs expect.
Segment key limit exceeded
Split segments are limited to 100,000 members. If your audience exceeds this limit, consider splitting it into multiple segments or using Split’s large segment feature (available on Enterprise plans).
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 segment. If you only want to add users without removing existing ones, use Add mode instead.