Log Custom Events

curl --request POST \
  --url https://api.statsig.com/v1/log_event \
  --header 'Content-Type: application/json' \
  --header 'statsig-api-key: <api-key>' \
  --data '
{
  "events": [
    {
      "eventName": "<string>",
      "value": "<string>",
      "time": 123,
      "user": {
        "userID": "user-123",
        "email": "[email protected]",
        "ip": "192.168.1.1",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
        "country": "US",
        "locale": "en_US",
        "appVersion": "1.2.3",
        "custom": {
          "subscription_plan": "premium",
          "account_age_days": 45,
          "is_beta_tester": true
        },
        "privateAttributes": {
          "internal_user_id": "12345"
        },
        "customIDs": {
          "companyID": "company-456",
          "deviceID": "device-789"
        },
        "statsigEnvironment": {
          "tier": "production"
        }
      },
      "metadata": {},
      "secondaryExposures": [
        {
          "gate": "<string>",
          "gateValue": "<string>",
          "ruleID": "<string>"
        }
      ],
      "statsigMetadata": {
        "sdkType": "js-client",
        "sdkVersion": "4.20.0",
        "exposureLoggingDisabled": false
      }
    }
  ],
  "user": {
    "userID": "user-123",
    "email": "[email protected]",
    "ip": "192.168.1.1",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
    "country": "US",
    "locale": "en_US",
    "appVersion": "1.2.3",
    "custom": {
      "subscription_plan": "premium",
      "account_age_days": 45,
      "is_beta_tester": true
    },
    "privateAttributes": {
      "internal_user_id": "12345"
    },
    "customIDs": {
      "companyID": "company-456",
      "deviceID": "device-789"
    },
    "statsigEnvironment": {
      "tier": "production"
    }
  },
  "statsigMetadata": {
    "sdkType": "js-client",
    "sdkVersion": "4.20.0",
    "exposureLoggingDisabled": false
  }
}
'

{
  "success": true
}

POST

log_event

Log Custom Events

curl --request POST \
  --url https://api.statsig.com/v1/log_event \
  --header 'Content-Type: application/json' \
  --header 'statsig-api-key: <api-key>' \
  --data '
{
  "events": [
    {
      "eventName": "<string>",
      "value": "<string>",
      "time": 123,
      "user": {
        "userID": "user-123",
        "email": "[email protected]",
        "ip": "192.168.1.1",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
        "country": "US",
        "locale": "en_US",
        "appVersion": "1.2.3",
        "custom": {
          "subscription_plan": "premium",
          "account_age_days": 45,
          "is_beta_tester": true
        },
        "privateAttributes": {
          "internal_user_id": "12345"
        },
        "customIDs": {
          "companyID": "company-456",
          "deviceID": "device-789"
        },
        "statsigEnvironment": {
          "tier": "production"
        }
      },
      "metadata": {},
      "secondaryExposures": [
        {
          "gate": "<string>",
          "gateValue": "<string>",
          "ruleID": "<string>"
        }
      ],
      "statsigMetadata": {
        "sdkType": "js-client",
        "sdkVersion": "4.20.0",
        "exposureLoggingDisabled": false
      }
    }
  ],
  "user": {
    "userID": "user-123",
    "email": "[email protected]",
    "ip": "192.168.1.1",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
    "country": "US",
    "locale": "en_US",
    "appVersion": "1.2.3",
    "custom": {
      "subscription_plan": "premium",
      "account_age_days": 45,
      "is_beta_tester": true
    },
    "privateAttributes": {
      "internal_user_id": "12345"
    },
    "customIDs": {
      "companyID": "company-456",
      "deviceID": "device-789"
    },
    "statsigEnvironment": {
      "tier": "production"
    }
  },
  "statsigMetadata": {
    "sdkType": "js-client",
    "sdkVersion": "4.20.0",
    "exposureLoggingDisabled": false
  }
}
'

{
  "success": true
}

Authorizations

statsig-api-key

string

header

required

SDK API key (Server Secret or Client SDK Key)

Headers

STATSIG-CLIENT-TIME

integer<int64>

Client timestamp in milliseconds. Used to normalize event timestamps against server time and account for client clock drift.

Body

application/json

events

object[]

required

Array of events to log

Minimum array length: 1

Show child attributes

events.eventName

string

required

Name of the event

Minimum string length: 1

events.value

Optional event value (string or number)

events.time

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

events.user

object

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

Show child attributes

events.user.userID

string

Primary user identifier

Example:

"user-123"

events.user.email

string<email>

User email address

Example:

"[email protected]"

events.user.ip

string

User IP address for geo-targeting

Example:

"192.168.1.1"

events.user.userAgent

string

User agent string for device/browser targeting

Example:

"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"

events.user.country

string

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

Example:

"US"

events.user.locale

string

Locale/language code

Example:

"en_US"

events.user.appVersion

string

Application version

Example:

"1.2.3"

events.user.custom

object

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

Example:

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

events.user.privateAttributes

object

Private attributes used for evaluation but not logged to analytics

Example:

{ "internal_user_id": "12345" }

events.user.customIDs

object

Additional custom identifier mappings

Show child attributes

events.user.customIDs.{key}

string

Example:

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

events.user.statsigEnvironment

object

Environment tier for targeting

Show child attributes

events.user.statsigEnvironment.tier

enum<string>

Environment tier

Available options:

production,

staging,

development

events.metadata

object

Additional event metadata as key-value pairs

Show child attributes

events.metadata.{key}

string

events.secondaryExposures

object[]

Secondary exposures for this event

Show child attributes

events.secondaryExposures.gate

string

required

Name of the gate

events.secondaryExposures.gateValue

string

required

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

events.secondaryExposures.ruleID

string

required

Rule ID that was evaluated

events.statsigMetadata

object

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

Show child attributes

events.statsigMetadata.sdkType

string

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

events.statsigMetadata.sdkVersion

string

SDK version

events.statsigMetadata.exposureLoggingDisabled

boolean

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

Example:

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

user

object

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

Show child attributes

user.userID

string

Primary user identifier

Example:

"user-123"

user.email

string<email>

User email address

Example:

"[email protected]"

user.ip

string

User IP address for geo-targeting

Example:

"192.168.1.1"

user.userAgent

string

User agent string for device/browser targeting

Example:

"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"

user.country

string

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

Example:

"US"

user.locale

string

Locale/language code

Example:

"en_US"

user.appVersion

string

Application version

Example:

"1.2.3"

user.custom

object

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

Example:

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

user.privateAttributes

object

Private attributes used for evaluation but not logged to analytics

Example:

{ "internal_user_id": "12345" }

user.customIDs

object

Additional custom identifier mappings

Show child attributes

user.customIDs.{key}

string

Example:

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

user.statsigEnvironment

object

Environment tier for targeting

Show child attributes

user.statsigEnvironment.tier

enum<string>

Environment tier

Available options:

production,

staging,

development

statsigMetadata

object

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

Show child attributes

statsigMetadata.sdkType

string

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

statsigMetadata.sdkVersion

string

SDK version

statsigMetadata.exposureLoggingDisabled

boolean

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

Example:

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

Response

Events accepted for processing

success

boolean

required

Whether the request was successful

Get Ranked List for Contextual Bandit

Log Custom Exposure Events

⌘I

SDK Quickstarts

SDK Concepts

Client SDKs

Server SDKs

AI SDKs

More SDK Methods

Console API Reference

Statsig CLI

HTTP API Reference

Log Custom Events

Authorizations

Headers

Body

Response