Log Custom Events

Logs one or more custom events for analytics and metric calculation. Events are used to measure experiment outcomes and user behavior.

Logs one or more custom events for analytics and metric calculation. Events are used to measure experiment outcomes and user behavior.

posthttps://api.statsig.com/v1/log_event

Authorizations

statsig-api-keystringrequired

apiKey (header)

Body

application/json
eventsobject[]required

Array of events to log

Show child attributes
eventNamestringrequired

Name of the event

Constraints:min length: 1
valueoneOf

Optional event value (string or number)

Constraints:stringnumber
timeoneOf

Event timestamp (unix timestamp in milliseconds or ISO date string)

Constraints:integer (format: int64)string (format: date-time)
userobject

User object for this specific event (overrides request-level user)

userIDstring

Primary user identifier

Example:user-123
emailstring

User email address

Example:user@example.com
Constraints:format: email
ipstring

User IP address for geo-targeting

Example:192.168.1.1
userAgentstring

User agent string for device/browser targeting

Example:Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36
countrystring

2-letter country code (ISO 3166-1 alpha-2)

Example:US
localestring

Locale/language code

Example:en_US
appVersionstring

Application version

Example:1.2.3
customobject

Custom user attributes for targeting (string, number, boolean, or array of strings)

Example:{"subscription_plan":"premium","account_age_days":45,"is_beta_tester":true}
privateAttributesobject

Private attributes used for evaluation but not logged to analytics

Example:{"internal_user_id":"12345"}
customIDsobject

Additional custom identifier mappings

Example:{"companyID":"company-456","deviceID":"device-789"}
statsigEnvironmentobject

Environment tier for targeting

tierstring

Environment tier

Allowed values:productionstagingdevelopment
metadataobject

Additional event metadata as key-value pairs

secondaryExposuresobject[]

Secondary exposures for this event

gatestringrequired

Name of the gate

gateValuestringrequired

Gate value as string ('true' or 'false')

ruleIDstringrequired

Rule ID that was evaluated

statsigMetadataobject

SDK metadata for tracking SDK type, version, and other diagnostic information

Example:{"sdkType":"js-client","sdkVersion":"4.20.0","exposureLoggingDisabled":false}
sdkTypestring

SDK type sending the request (e.g., js-client)

sdkVersionstring

SDK version

exposureLoggingDisabledboolean

When true, prevents the HTTP API from automatically logging exposures. Use this only if you will handle exposure logging yourself.

userobject

Shared user object for all events (can be overridden per event)

Show child attributes
userIDstring

Primary user identifier

Example:user-123
emailstring

User email address

Example:user@example.com
Constraints:format: email
ipstring

User IP address for geo-targeting

Example:192.168.1.1
userAgentstring

User agent string for device/browser targeting

Example:Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36
countrystring

2-letter country code (ISO 3166-1 alpha-2)

Example:US
localestring

Locale/language code

Example:en_US
appVersionstring

Application version

Example:1.2.3
customobject

Custom user attributes for targeting (string, number, boolean, or array of strings)

Example:{"subscription_plan":"premium","account_age_days":45,"is_beta_tester":true}
privateAttributesobject

Private attributes used for evaluation but not logged to analytics

Example:{"internal_user_id":"12345"}
customIDsobject

Additional custom identifier mappings

Example:{"companyID":"company-456","deviceID":"device-789"}
statsigEnvironmentobject

Environment tier for targeting

tierstring

Environment tier

Allowed values:productionstagingdevelopment
statsigMetadataobject

SDK metadata for tracking SDK type, version, and other diagnostic information

Example:{"sdkType":"js-client","sdkVersion":"4.20.0","exposureLoggingDisabled":false}
Show child attributes
sdkTypestring

SDK type sending the request (e.g., js-client)

sdkVersionstring

SDK version

exposureLoggingDisabledboolean

When true, prevents the HTTP API from automatically logging exposures. Use this only if you will handle exposure logging yourself.

Response

application/json
202· Events accepted for processing
successbooleanrequired

Whether the request was successful

503· Service unavailable
successbooleanrequired

Whether the request was successful

Was this helpful?