---
title: "List segments"
method: GET
path: "/v1/segments"
tags: ["Segments"]
---

# List segments

`GET /v1/segments`

Retrieves a list of segments.

The list doesn't include the customers that belong to respective segments. To return a list of customers who belong to a segment, use [GET List customers](/api-reference/customers/list-customers) endpoint with the `segment_id` query parameter.

To return a list of different results, use the `filters[created_at][conditions][$before]` and `filters[created_at][conditions][$after]` query parameters as pagination.

## Query parameters

- `limit` integer
- `order` 'created_at' | '-created_at'
- `filters` ParameterFiltersListSegments
  - `junction` 'and' | 'or' — Logical Operator Between Filters. Filter by conditions set on the `junction` parameter indicating how the `conditions` should be accounted for in the query. An `AND` is an all-inclusive logical operator, meaning the `AND` operator displays a record if **ALL** the conditions separated by AND are TRUE, while an `OR` operator displays a record if **ANY** of the conditions separated by OR is TRUE.
  - `id` object — Unique segment ID.
    - `conditions` FilterConditionsString — Data filters used to narrow down the data records to be returned in the result.
      - `$in` string[] — Array of resource values that should be included in the results (multiple values).
      - `$not_in` string[] — Array of resource values that should be included in the results (multiple values).
      - `$is` string — Value is exactly this value (single value).
      - `$is_not` string — Results omit this value (single value).
      - `$has_value` string — Value is NOT null. The value for this parameter is an empty string.
      - `$is_unknown` string — Value is null. The value for this parameter is an empty string.
      - `$starts_with` string — Value starts with the specified string.
      - `$ends_with` string — Value ends with the specified string.
      - `$contains` string — Value includes the specified string.
      - `$not_contain` string — Value does NOT include the specified string.
  - `name` object — Unique user-defined segment name.
    - `conditions` FilterConditionsString — Data filters used to narrow down the data records to be returned in the result.
      - `$in` string[] — Array of resource values that should be included in the results (multiple values).
      - `$not_in` string[] — Array of resource values that should be included in the results (multiple values).
      - `$is` string — Value is exactly this value (single value).
      - `$is_not` string — Results omit this value (single value).
      - `$has_value` string — Value is NOT null. The value for this parameter is an empty string.
      - `$is_unknown` string — Value is null. The value for this parameter is an empty string.
      - `$starts_with` string — Value starts with the specified string.
      - `$ends_with` string — Value ends with the specified string.
      - `$contains` string — Value includes the specified string.
      - `$not_contain` string — Value does NOT include the specified string.
  - `type` object — Segment type.
    - `conditions` object — Data filters used to narrow down the data records to be returned in the result.
      - `$in` string[] — Array of resource values that should be included in the results (multiple values).
      - `$not_in` string[] — Array of resource values that should be included in the results (multiple values).
      - `$is` 'auto-update' | 'passive' | 'static' — Value is exactly this value (single value).
      - `$is_not` 'auto-update' | 'passive' | 'static' — Results omit this value (single value).
      - `$has_value` string — Value is NOT null. The value for this parameter is an empty string.
      - `$is_unknown` string — Value is null. The value for this parameter is an empty string.
      - `$starts_with` string — Value starts with the specified string.
      - `$ends_with` string — Value ends with the specified string.
  - `created_at` object — Timestamp representing the date and time when the segment was created. The value is shown in the ISO 8601 format.
    - `conditions` FilterConditionsDateTime — Data filters used to narrow down the data records to be returned in the result.
      - `$after` string, date-time — Value is after this date. The value for this parameter is shown in the ISO 8601 format.
      - `$before` string, date-time — Value is before this date. The value for this parameter is shown in the ISO 8601 format.
      - `$has_value` string — Value is NOT null. The value for this parameter is an empty string.
      - `$is_unknown` string — Value is null. The value for this parameter is an empty string.
      - `$more_than` integer — Value is more days ago before the current date and time, e.g. more than `10` days ago.
      - `$less_than` integer — Value is less days before the current date and time, e.g. less than `10` days ago.
- `ids` string[]

## Response `200`

Returns a `data` array with segment objects.

- SegmentsListResponseBody — Response body schema for **GET** `v1/segments`.
  - `object` 'list', required — The type of the object represented by JSON. This object stores information about segments.
  - `data_ref` 'data', required — Identifies the name of the attribute that contains the array of segments.
  - `segments` Segment[] — An array of segment objects. Returns an empty array if there are no results matching query parameters.
    - `id` string — Unique segment ID.
    - `name` string — Segment name.
    - `created_at` string, date-time — Timestamp representing the date and time when the segment was created. The value is shown in the ISO 8601 format.
    - `updated_at` string, date-time — Timestamp in ISO 8601 format indicating when the segment was updated.
    - `type` 'auto-update' | 'passive' | 'static' — Defines whether the segment is: - Active (`auto-update`): customers enter and leave the segment based on the defined filters and the `customer.segment.entered` and `customer.segment.left` events are triggered, - Passive (`passive`): customers enter and leave the segment based on the defined filters, but the `customer.segment.entered` and `customer.segment.left` events are not triggered, - Static (`static`): manually selected customers.
    - `filter` object, nullable — Defines a set of criteria for an `auto-update` or `passive` segment type.
    - `object` 'segment' — The type of the object represented by JSON. This object stores information about the customer segment.
  - `total` integer, required — Total number of segments returned for given filters and query parameters with the exception of `limit`.

---

[API](https://skmtc.net/voucherifyio/apis/voucherify-api-async-actions.md) · [All operations](https://skmtc.net/voucherifyio/apis/voucherify-api-async-actions/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/voucherifyio/voucherify-api-async-actions/revisions/4982266e0494/schema)