API Usage

10 min

📘 Note The terms audiences and segments are interchangeable. Optimizely is currently working on updating the UI to display all segments as audiences.

The following two APIs let you work with segments in different ways:

Segments API – Lets you create, delete, list, and get segments. For more information, see the Segments API referenceSegments API reference

GraphQL API – Lets you view the results of existing segments. For more information, see the Query real-time segments section.

The Real-Time Segments API expands on what the GraphQL API lets you do. This section focuses on the Real-Time Segments API. You can use the Real-Time Segments API to create new segments, delete existing segments, list all segments, and view segment definitions.

The hostname for the API is region-specific. See the API referenceAPI reference to find your region's hostname.

📘 Note This documentation uses the US region hostname (https://api.us1.odp.optimizely.com).

These requests require authentication with private API token. See AuthenticationAuthentication for more information.

The data type for segment-id is string, but they must always conform to case insensitive regexp pattern [a-z0-9_]*.

Operations

The possible operations are:

List segments (GET)

Get segment (GET)

Delete segment (DELETE)

Create segment (POST)

Update segment (PUT)

List segments

GET https://{hostname}/v3/segments

Responses

Status	Content-Type	Body
200	application/json	\{\ segment\_ids: "h-0"\ }

Example request

$ curl -H'x-api-key: your-private-key' \
https://api.us1.odp.optimizely.com/v3/segments
{segment_ids: ["is_active"]}

Get segment

Gets a previously defined segment.

GET https://{hostname}/v3/segments/{segment-id}

Responses

Status	Content-Type	Body
200	application/json	\{\ revision: int,\ description: string,\ definition: segment\_definition\ }
400	application/json	\{\ status: 404,\ request\_id: null,\ message: "Segment not found."\ }

Delete segment

Deletes a previously defined segment. Returns all segmentIds that exist after the delete.

DELETE https://{hostname}/v3/segments/{segment-id}

Responses

Status	Content-Type	Body
200	application/json	\{\ segment\_ids: "h-0"\ }
400	application/json	\{\ status: 404,\ request\_id: null,\ message: "Segment not found."\ }

Example request

Assuming there are three installed segments with segmentIds "example_one", "example_two" and "example_three":

$ curl -H'x-api-key: your-private-key' \
https://api.us1.odp.optimizely.com/v3/segments/example_two
{segment_ids: ["example_one", "example_three"]}

$ curl -H'x-api-key: your-private-key' \
https://api.us1.odp.optimizely.com/v3/segments/example_two
{"status": 404,"request_id":null,"message"Segment not found."}

Create segment

PUT https://{hostname}/v3/segments/{segment-id}

{
    "description": "total revenue less than 25",
    "definition": {
        "root_condition": {
          "customer_condition": {
            "customer_filter": {
              "comparison": {
                  "lhs": {
                      "path_reference": {
                          "value": "customer.observations.total_revenue_percentile"
                      }
                  },
                  "comparator": "LESS_THAN",
                  "rhs": {
                      "number_literal": {
                          "value": "25"
                      }
                  }
              }
            }
          }
        }
    }
}

Parameter	Type	Example
segment-id	string	`total_revenue_lt_25`
description	string	Total revenue percentile less than 25
definition	[segment\_definition](https://docs.developers.optimizely.com/optimizely-data-platform/docs/realtimesegments-defining-real-time-segments)	\{\ "root\_condition": \{\ "customer\_condition": \{\ "customer\_filter": \{\ "comparison": \{\ "lhs": \{\ "path\_reference": \{\ "value": "customer.observations.total\_revenue\_percentile"\ }\ },\ "comparator": "LESS\_THAN",\ "rhs": \{\ "number\_literal": \{\ "value": "25"\ }\ }\ }\ }\ }\ }\ }

Responses

Status	Content-Type	Body	Comment
200	application/json	\{\ "revision": int\ }	\{\ "revision": Starts at 0 when\ segment is created,\ incremented on update\ }
400	application/json	\{\ "code": int,\ "message": "string"\ }	\{\ "code": Same as HTTP\ status code.,\ "message": "Provides\ reason why segment\ definition is invalid"\ }

Example request

curl -XPUT -H 'x-api-key: your-private-key' \
-H 'Content-Type': 'application/json' \
https://api.us1.odp.optimizely.com/v3/segments/is_active \
-d '{
  "description": "Users who were active in the last 7 days",
  "definition": {
    "root_condition": {
      "sequence_condition": {
        "sequence": {
          "entry_event_filter": {
            "path_reference": {
              "value": "event.active_event"
            }
          },
          "max_age_seconds": 604800
        },
        "min_count": 1
      }
    }
  }
}'

Update segment

Updating a segment is similar to creating a segment. If you issue a PUT with a segment-id that already exists and a new segment definition, then that segment-id is updated with the new segment definition and the revision number is incremented.

Example request

Assume you have two variables with segment definitions. The first one is ${ACTIVE_7_DAYS} and matches the Create segment example body. The second one is ${ACTIVE_1_DAY}, which looks the same, except it has "max_age_seconds": 86400. This requires the user to have an active event within the last 86400 seconds (1 day).

The following requests would then:

Create the segment is_active, including users that were active in the last 7 days. This returns {"revision":0}.

Update the description for segment is_active. This returns {"revision":1}.

Update the definition for segment is_active. This returns {"revision":2}.

$ curl -XPUT -H'x-api-key: your-private-key' \
    https://api.us1.odp.optimizely.com/v3/segments/is_active \
    -d @- << EOF
    {
      "description": "User was active in the last week.",
      "definition": ${ACTIVE_7_DAYS}
    }
    EOF
    {"revision":0}
    
    $ curl -XPUT -H'x-api-key: your-private-key' \
    https://api.us1.odp.optimizely.com/v3/segments/is_active \
    -d @- << EOF
    {
      "description": "User was recently active",
      "definition": ${ACTIVE_7_DAYS}
    }
    EOF
    {"revision":1}

    $ curl -XPUT -H'x-api-key: your-private-key' \
    https://api.us1.odp.optimizely.com/v3/segments/is_active \
    -d @- << EOF
    {
      "description": "User was recently active",
      "definition": ${ACTIVE_1_DAY}
    }
    EOF
    {"revision":2}