--- title: API Usage slug: data-platform/docs/realtimesegments-api-usage docTags: createdAt: 2026-08-10T12:05:16.000Z --- :::hint{type="info"} **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 reference](docId\:YHwQfnKL7gIJycX2mZAAV) - **GraphQL API** – Lets you view the results of existing segments. For more information, see the [Query real-time segments](docId:9PGT9Hc-AExOV1X7TBpOr) 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 reference](docId\:AG2AAmfi-lqBG6sOp0eTu) to find your region's hostname. :::hint{type="info"} **Note** This documentation uses the US region hostname (`https://api.us1.odp.optimizely.com`). ::: These requests require authentication with private API token. See [Authentication](docId\:LIy60XfaOOtW4DxUAxG_6) 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 $ 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 $ 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}` ```javascript { "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 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: 1. Create the segment `is_active`, including users that were active in the last 7 days. This returns `{"revision":0}`. 2. Update the description for segment `is_active`. This returns `{"revision":1}`. 3. Update the definition for segment `is_active`. This returns `{"revision":2}`. ```curl $ 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} ```