Skip to main content

/i/events/whitelist_segments

Endpoint​

/i/events/whitelist_segments

Overview​

Set or unset per-event whitelisted segment keys in event metadata.

Authentication​

  • API Key (parameter): api_key=YOUR_API_KEY
  • Auth Token (parameter): auth_token=YOUR_AUTH_TOKEN
  • Auth Token (header): countly-token: YOUR_AUTH_TOKEN

Permissions​

  • Update permission for feature events on the target app is required.

Request Parameters​

ParameterTypeRequiredDescription
api_keyStringYes (or use auth_token)Dashboard API authentication key.
auth_tokenStringYes (or use api_key)Dashboard auth token.
app_idStringYesTarget app ID.
whitelisted_segmentsJSON String (Object)YesMap of event keys to segment arrays. Non-empty arrays are set; empty arrays unset existing whitelist entries.

whitelisted_segments Object Structure​

FieldTypeRequiredDescription
eventKeyArray of StringsNoSegment names to whitelist for the given event. Empty array removes whitelist entry for that event key.

Response​

Success Response​

{
  "result": "Success"
}

Response Fields​

FieldTypeDescription
resultStringWhitelist update status.

Error Responses​

Status Code: 400 Bad Request

{
  "result": "Could not find record in event collection"
}

Status Code: 400 Bad Request

{
  "result": "Value for 'whitelisted_segments' missing"
}

Behavior/Processing​

Behavior Modes​

ModeTriggerProcessing PathResponse Shape
Set whitelist entriesEvent key maps to non-empty segment arrayWrites $set updates under whitelisted_segments.eventKey.Wrapped string { "result": "Success" }
Unset whitelist entriesEvent key maps to empty arrayWrites $unset updates for whitelisted_segments.eventKey.Wrapped string { "result": "Success" }

Audit & System Logs​

ActionTriggerPayload
segments_whitelisted_for_eventsAfter successful whitelist update{ update } containing serialized $set/$unset whitelist metadata changes.

Database Collections​

CollectionUsed forData touched by this endpoint
countly.membersAuthentication and permission validationReads member identity and app-level update permissions.
countly.eventsWhitelist metadata update targetReads app event metadata document and updates whitelisted_segments fields.

Examples​

Example 1: Set whitelist for purchase event​

/i/events/whitelist_segments?api_key=YOUR_API_KEY&app_id=64b0ac10c2c3ce0012dd1001&whitelisted_segments={"Purchase":["country","platform"]}

Example 2: Remove whitelist entry​

/i/events/whitelist_segments?api_key=YOUR_API_KEY&app_id=64b0ac10c2c3ce0012dd1001&whitelisted_segments={"Purchase":[]}

Limitations​

  • Missing whitelisted_segments payload is rejected.
  • Invalid JSON payloads can degrade to empty updates depending on parse outcome.

Last Updated​

2026-02-17