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

Filtering, paging, and sorting (deprecated)

(Deprecated) Describes how to search for profiles and tracked events using filters, paging, and sorting. Profiles and tracked events are part of the Optimizely Profile Store API, used for querying, creating, and updating visitor profiles, segments, and scopes.

Suggest Edits

❗️

Deprecated

Visitor Intelligence and Profile Store are deprecated and no longer supported. For migration options to Optimizely Data Platform (ODP), contact your sales representative or customer success manager.

See Remove dependencies on Visitor Intelligence and Profile Store.

Endpoints

📘

Note

Replace each {x} placeholder in the following endpoints with an appropriate value.

TrackEvents

GET/api/v1.0/trackevents/?$filter={1}&$skip={2}&$top={3}&$orderBy={4}

Profiles

GET/api/v1.0/profiles/?$filter={1}&$skip={2}&$top={3}&$orderBy={4}

Usage

The querystring parameters are named according to the Microsoft Rest API Guidelines.

📘

Note

If your filter contains special characters, make sure that they are URL-encoded. See https://www.url-encode-decode.com/

  • $skip – Returns results from the specified offset.
  • $top – Optional. Returns the specified number of results.
    • Together the $skip and $top parameters are used for client-driven paging. See also Client-driven paging.
    • If not specified, default values are: $skip=0 $top=100.
    • 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.
  • $orderBy – Optional. Sorts the results according to the specified property. See Sorting collections.

📘

Note

Wildcard searching with * is not supported.

TrackEvents

{
       "DeviceId"      : "91687965-bc76-49a2-862c-e014441b8f6b",
       "EventType"     : "home",
       "Value"         : "Visited the start page.",
       "PageUri"       : "http://localhost:50244/en/",
       "RemoteAddress" : "::1",
       "Headers"       : {},
       "Payload"       : {},
       "EventTime"     : "2017-09-15T07:16:34.7957819Z",
       "CountryCode"   : "Localhost"
    }

📘

Note

The Payload object in TrackEvent is a dynamic object and is defined by a specific tracking implementation.

Profiles

{
      "ProfileId"          : "df0a2b9e-4d78-4ae1-9db0-6cb0db0cda04",
      "DeviceIds"          : [
                               "91687965-bc76-49a2-862c-e014441b8f6b"
                             ],
      "Name"               : "John Doe",
      "UpdateTime"         : "2017-09-15T07:16:41.3501641Z",
      "FirstSeen"          : "2017-09-15T07:16:34.7957819Z",
      "LastSeen"           : "2017-09-15T07:16:34.7957819Z",
      "Visits"             : 1,
      "Info"               : {
                               "InferredCountry" : "Localhost",
                               "Email"           : "[email protected]"
                             },
      "ContactInformation" : [
                               "Mailable",
                               "Known"
                             ]
    }

Segments

{
      "SegmentId"                   : "fc68ee49-c0d0-4002-897c-9762fcfdb814",
      "Name"                        : "Last seen within 1 week",
      "SegmentManager"              : "[email protected]",
      "Created"                     : "2018-01-31T02:58:01.3091778+00:00",
      "ModifiedBy"                  : "[email protected]",
      "Modified"                    : "2018-01-31T02:58:01.3091778+00:00",
      "Archived"                    : false,
      "AvailableForPersonalization" : true,
      "LabelIds"                    : Array[0][],
      "Labels"                      : Array[0][],
      "FavoredBy"                   : Array[0][],
      "ProfileFilter"               : {
        "$type" : "EPiServer.Insight.Api.Models.ProfileRulesFilter, EPiServer.Insight.Api",
        "Rules" : Array[1][
          {
            "Date" : {
              "Field"  : "LastSeen",
              "Method" : "Within",
              "Values" : Array[1]["OneWeek"]
                     }
          }
        ]
      },
      "Filter"                      : {
         "range" : {
           "LastSeen" : {
             "gt" : "now-7d",
             "lt" : "now"
             }
         }
      },
      "MatchingProfiles"            : 1,
      "LastProfileCount"            : "0001-01-01T00:00:00",
      "Source"                      : "default"
    }

Search specifying JSON property name

You can search anything by specifying the JSON property name as the field in the filter.

TrackEvents

EventType eq home

Profiles

Visits gt 1

Segments

SegmentName eq LastWeek

Search within nested objects

To search within nested objects, use the dot notation to build up the field name in the filter.

For example using TrackEvent, see the following Payload object example from the tracking as implemented in the Optimizely Customized Commerce Quicksilver sample site.

{
      "Payload" : {
                    "recContent"  : "refCodeOnly",
                    "channel"     : "web",
                    "category"    : "Fashion>Mens",
                    "type"        : "category",
                    "ip"          : "::1",
                    "session"     : null,
                    "cuid"        : null,
                    "site"        : null,
                    "clientToken" : null,
                    "lang"        : "en",
                    "currentURI"  : "http://localhost:50244/en/fashion/mens/",
                    "previousURI" : "http://localhost:50244/en/fashion/mens/mens-shoes/p-36127195/",
                    "userAgent"   : "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/46.0.2486.0 Safari/537.36 Edge/13.10586",
                    "user"        : {
                                      "name"  : "John Doe",
                                      "email" : "[email protected]"
                                    }
                  }
    }

TrackEvents

When filtering based on email in a user object in Payload, use the following field name:

Payload.user.email eq [email protected]

Profiles

When filtering based on Email in the Info object, use the following field name:

Info.Email eq [email protected]

Responses

Responses are in JSON format. There are the following types of responses:

  • Successful response. Contains the following properties:
    • total – Total number of results on the server regardless of paging.
    • count – Number of results returned for the current request. Affected by the $top parameter.
    • items – Collection of results.
  • Error response. Returns error which contains:
    • code – HTTP response code.
    • message – Error message or description.

See ErrorResponse in the Microsoft Rest API Guidelines.

Date and time format

The following standard for date and time is supported: ISO 8601 (UTC)

Examples:

  • Date: 2017-10-09
  • Combined date and time in UTC: 2017-10-09T06:22:28+00:002017-10-09T06:22:28Z

Examples

Profiles filtered by device id

GET /api/v1.0/profiles/?$filter=DeviceIds eq xxxxx

Profiles filtered by email

GET /api/v1.0/profiles/?$filter=Info.Email eq [email protected]

Sorting of profiles on Name

GET /api/v1.0/profiles/?$filter=LastSeen gt 2017-09-01&$orderBy=Name ASC
GET /api/v1.0/profiles/?$filter=FirstSeen lt 2017-09-01&$orderBy=Name DESC

Sorting of events on CountryCode

GET /api/v1.0/trackevents/?$filter=PageUri eq http://www.host.com&$orderBy=CountryCode ASC

Profiles within a time range

GET /api/v1.0/profiles/?$filter=FirstSeen gt 2017-09-01T00:00:00Z and FirstSeen lt 2017-09-30T00:00:00Z

Events within a date range belonging to a specific profile

GET /api/v1.0/trackevents/?$filter=EventTime gt 2017-09-01 and EventTime lt 2017-09-30 and ProfileId eq yyyyy

Events within a time range belonging to a specific device

GET /api/v1.0/trackevents/?$filter=EventTime gt 2017-09-18T08:15:35Z and EventTime lt 2017-09-20T08:15:35Z and DeviceId eq xxxx

Paging of events that occurred before a specific date (returns page 3 with a page size of 10 results)

GET /api/v1.0/trackevents/?$filter=EventTime le 2017-09-30&$skip=20&$top=10

Specify precedence using parentheses

If not supplied, logical operators are evaluated left to right.

GET /api/v1.0/trackevents/?$filter=Payload.value1 gt 2 or (Payload.value2 le 3 and Payload.value3 eq 3)

Total number of events for URL

GET /api/v1.0/trackevents/?$filter=PageUri eq http://www.url1.com

Get segment by name

GET /api/v1.0/segments/?$filter=SegmentName eq LastMonth

Get segment by Id

GET /api/v1.0/segments/fc68ee49-c0d0-4002-897c-9762fcfdb814

JSON response with count and total

{
      total: 10,
      count: 10,
      items: {
               {...},
               {...},
              ...
             }
    }
Date:2017-10-09
Combined date and time in UTC:2017-10-09T06:22:28+00:00
2017-10-09T06:22:28Z
20171009T062228Z

Related topic

Updated 1 day ago

Next