📘

Note

The termsaudiences andsegments are interchangeable. Optimizely is currently working on updating the UI to display allsegments asaudiences.

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 theSegments API reference
• GraphQL API – Lets you view the results of existing segments. For more information, see theQuery 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 theAPI reference to find your region's hostname.

📘

Note

This documentation uses the US region hostname (https://api.zaius.com).

These requests require authentication with private API token. SeeAuthentication 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

GEThttps://{hostname}/v3/segments

Responses

Example request

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

Get segment

Gets a previously defined segment.

GEThttps://{hostname}/v3/segments/{segment-id}

Responses

Delete segment

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

DELETEhttps://{hostname}/v3/segments/{segment-id}

Responses

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.zaius.com/v3/segments/example_two{segment_ids: ["example_one", "example_three"]}$ curl -H'x-api-key: your-private-key' \https://api.zaius.com/v3/segments/example_two{"status": 404,"request_id":null,"message"Segment not found."}

Create segment

PUThttps://{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"                      }                  }              }            }          }        }    }}

Responses

Example request

curl -XPUT -H 'x-api-key: your-private-key' \-H 'Content-Type': 'application/json' \https://api.zaius.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 theCreate 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:

1. Create the segmentis_active, including users that were active in the last 7 days. This returns{"revision":0}.
2. Update the description for segmentis_active. This returns{"revision":1}.
3. Update the definition for segmentis_active. This returns{"revision":2}.

$ curl -XPUT -H'x-api-key: your-private-key' \    https://api.zaius.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.zaius.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.zaius.com/v3/segments/is_active \    -d @- << EOF    {      "description": "User was recently active",      "definition": ${ACTIVE_1_DAY}    }    EOF    {"revision":2}

Updated 25 days ago

• Roadmap for Mastering Real-Time Segments