HomeDev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideLegal TermsDev CommunityOptimizely AcademySubmit a ticketLog In
Dev Guide

Track events

Describes the track event object in the Optimizely Profile Store API.

Tracked events are used for recording visitor interaction, for example viewing a website page, placing an order, or clicking a link in an email.

The track event object contains the following property fields.

  • DeviceId [string] – The device the event was send from.
  • EventType [string] – The type of event.
  • Value [string] – A human-readable string for the event.
  • PageUri [string] – The URL where the event was made (if it was from a site).
  • RemoteAddress [string] – The IP address for the event visitor.
  • EventTime (datetime) – The UTC time when the event occurred.
  • CountryCode (string) – country from which the event was made.
  • Payload [object] – A property where any other custom values can be stored in the form of a JSON object.

Example

{
      "DeviceId"      : "91687965-bc76-49a2-862c-e014441b8f6b",
      "EventType"     : "home",
      "Value"         : "Visited the start page.",
      "PageUri"       : "https://example.com/en/",
      "RemoteAddress" : "::1",
      "Payload"       : {  
                          "name"          : "Home page",
                          "contentGuid"   : "440be34f-d08a-4a7e-b019-55448d065d28",
                          "contentLink"   : "163204",
                          "contentTypeID" : 170,
                          "parentLink"    : "163198"
                        },
      "EventTime"     : "2017-09-15T07:16:34.7957819Z",
      "CountryCode"   : "Localhost"
    }

TrackEvents methods

You must add an Authorization header to the request. The value should be:

epi-single {YOUR PROFILE STORE API KEY}

GET api/v2.0/TrackEvents

GETapi/v2.0/TrackEventsGets events are based on OData query. Profile Store follows Microsoft REST API Guidelines for supporting $filter, and $orderby.

The result window size is limited and must fit the top 10000 records, so the sum of $skip and $top values must be less than 10000. Defaut values of $skip is 0, $top is 100.

POST api/v2.0/TrackEvents/preview

POSTapi/v2.0/TrackEvents/previewGets events that match KQL query.

When you create a KQL query for a filter definition, this endpoint lets you preview up to 1000 event results.

The execution is dropped if it runs longer than 2 minutes or uses too much compute power so do not make the KQL query too heavy for execution.

Example request

POST /api/v2.0/TrackEvents/preview
    Authorization: epi-single YourAPIKey
    Content-Type: application/json-patch+json
    accept: application/json
     
    { 
      "Query" : "Events
        | where EventTime between (todatetime('2019-01-01') .. endofday(now()))
            and EventType == 'pageview'
            and User.Email != ''
        | take 2", 
      "Scope" : "default" 
    }

Example response data

{
      "items" : [
                 {
                   "TrackId"       : "",
                   "DeviceId"      : "558356a7-86d2-4ca7-9c00-c01c46d81111",
                   "EventType"     : "pageview",
                   "Value"         : "Example page view",
                   "Scope"         : "default",
                   "PageUri"       : "http://example.com",
                   "PageTitle"     : "Example Home",
                   "RemoteAddress" : "192.168.0.1",
                   "SessionId"     : "",
                   "User"          : {
                                       "Email" : "[email protected]",
                                       "Name"  : "John Smith"
                                     },
                   "Payload"       : null,
                   "CountryCode"   : "SE",
                   "City"          : "",
                   "EventTime"     : "2020-01-23T21:27:49.3361008Z"
                 },
                 {
                   "TrackId"       : "",
                   "DeviceId"      : "558356a7-86d2-4ca7-9c00-c01c46d82222",
                   "EventType"     : "pageview",
                   "Value"         : "Example page view from another device",
                   "Scope"         : "default",
                   "PageUri"       : "http://example.com",
                   "PageTitle"     : "Example Home",
                   "RemoteAddress" : "192.168.0.1",
                   "SessionId"     : "",
                   "User"          : {
                                       "Email" : "[email protected]",
                                       "Name"  : "John Smith"
                                     },
                   "Payload"       : null,
                   "CountryCode"   : "SE",
                   "City"          : "",
                   "EventTime"     : "2020-01-23T21:27:59.8661238Z"
                 }
                ],
      "count" : 2
    }

DELETE api/v2.0/TrackEvents/{scope}/{id}

DELETEapi/v2.0/TrackEvents/{scope}/{id}The DELETE method deletes tracking events for the given scope and tracking event Id.

Please note that event deletion happens in 2 stages. Deleted events are not returned when querying and exporting data or executing segment. Actual data deletion usually is scheduled once a day. The cleaning period may be longer, depending on other tasks and the load on the system.

Up to 1 million events can be deleted before the next data cleaning is performed.

Returns

  • HTTP 200 OK when a tracking event was deleted.
  • HTTP 404 NOT FOUND if tracking event does not exist.
  • HTTP 429 TOO MANY REQUESTS if more than 1 million events would be deleted after this operation. See Retry-After response header for the suggested time for retry.
  • HTTP 500 INTERNAL SERVER ERROR when an internal error occurred in the deletion process.

📘

Note

If you experience an HTTP 500 error you can retry the operation again to get a successful response.