previousId: Old user identifier (the anonymous ID)
For source operations:
sourceId: Source identifier
Pitfalls:
ALIAS is a one-way operation; cannot be undone
previousId is the anonymous/old ID, userId is the new/identified ID
Not all destinations support alias calls; check destination documentation
ALIAS should be called once when a user first identifies (e.g., signs up)
Source updates may affect data collection; review changes carefully
Common Patterns
User Lifecycle
Standard Segment user lifecycle:
1. Anonymous user visits -> PAGE call with anonymousId
2. User interacts -> TRACK call with anonymousId
3. User signs up -> ALIAS (anonymousId -> userId), then IDENTIFY with traits
4. User takes action -> TRACK call with userId
5. User joins org -> GROUP call linking userId to groupId
Batch Optimization
For bulk data ingestion:
1. Collect events in memory (array of message objects)
2. Each message includes type, userId/anonymousId, and type-specific fields
3. Call SEGMENT_BATCH with the collected messages
4. Check response for any individual message errors
Naming Conventions
Segment recommends consistent event naming:
Events: Use "Object Action" format (e.g., 'Order Completed', 'Article Viewed')
Properties: Use snake_case (e.g., 'order_total', 'product_name')
Traits: Use snake_case (e.g., 'first_name', 'plan_type')
Known Pitfalls
Identity Resolution:
Always include userId or anonymousId on every call
Use ALIAS only once per user identity merge
Identify before tracking to ensure proper user association
Data Quality:
Event names should be consistent across all sources
Properties should follow a defined schema for downstream compatibility
Avoid sending sensitive PII unless destinations are configured for it
Rate Limits:
Use BATCH for bulk operations to stay within rate limits
Individual calls are rate-limited per source
Batch calls are more efficient and less likely to be throttled
Response Parsing:
Successful responses indicate acceptance, not delivery to destinations
Response data may be nested under data key
Check for error fields in batch responses for individual message failures
Timestamps:
Must be ISO 8601 format with timezone (e.g., '2024-01-15T10:30:00Z')
Omitting timestamp uses server receive time
Historical data imports should include explicit timestamps
Quick Reference
Task
Tool Slug
Key Params
Track event
SEGMENT_TRACK
userId, event, properties
Identify user
SEGMENT_IDENTIFY
userId, traits
Batch calls
SEGMENT_BATCH
batch (array of messages)
Group user
SEGMENT_GROUP
userId, groupId, traits
Page view
SEGMENT_PAGE
userId, name, properties
Alias identity
SEGMENT_ALIAS
userId, previousId
Source schema
SEGMENT_LIST_SCHEMA_SETTINGS_IN_SOURCE
sourceId
Update source
SEGMENT_UPDATE_SOURCE
sourceId
Warehouses
SEGMENT_LIST_CONNECTED_WAREHOUSES_FROM_SOURCE
sourceId
When to Use
This skill is applicable to execute the workflow or actions described in the overview.
Limitations
Use this skill only when the task clearly matches the scope described above.
Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.