> ## Documentation Index > Fetch the complete documentation index at: https://docs.voucherify.io/llms.txt > Use this file to discover all available pages before exploring further. # List 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. ## OpenAPI ````yaml /openapi/segments.json get /v1/segments openapi: 3.0.1 info: title: Voucherify API - Segments version: v2018-08-01 description: >- Voucherify promotion engine REST API. Please see https://docs.voucherify.io/docs for more details. contact: name: Voucherify Team url: https://www.voucherify.io/contact-support email: support@voucherify.io termsOfService: https://www.voucherify.io/legal/subscription-agreement license: name: MIT url: https://github.com/voucherifyio/voucherify-js-sdk/blob/main/LICENSE servers: - url: https://{cluster}.voucherify.io description: Base URL variables: cluster: default: api enum: - api - us1.api - as1.api - download - us1.download - as1.download security: [] paths: /v1/segments: get: tags: - Segments summary: List segments description: >- 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. operationId: list-segment parameters: - $ref: '#/components/parameters/limit' - schema: $ref: '#/components/schemas/ParameterOrderCreatedAt' in: query name: order description: >- Apply this filter to order the segments according the date and time when they were created. By default, lists the segments from the newest to the oldest. Use `created_at` to list from the oldest to the newest. - name: filters in: query schema: $ref: '#/components/schemas/ParameterFiltersListSegments' description: Filters for listing templates. style: deepObject explode: true - schema: $ref: '#/components/schemas/ParameterIds' in: query name: ids description: >- Contains the list of segments in the sequence defined by the `order` parameter. responses: '200': description: Returns a `data` array with segment objects. content: application/json: schema: $ref: '#/components/schemas/SegmentsListResponseBody' examples: List of segments: value: object: list data_ref: data data: - id: seg_5ix74s3gM3N7 name: Customers with placed order created_at: '2023-08-03T10:37:49.285Z' updated_at: null type: auto-update filter: junction: and events.payment_placed.count: conditions: $more_than: - '0' object: segment - id: seg_fi47Ds3gM3N7 name: Newsletter subscribers created_at: '2023-08-03T10:37:49.264Z' updated_at: null type: auto-update filter: junction: and events.newsletter_subscribed.count: conditions: $more_than: - '0' object: segment - id: seg_f0r4hs3gM3N7 name: Reviewers created_at: '2023-08-03T10:37:49.244Z' updated_at: null type: auto-update filter: junction: and events.review_left.count: conditions: $more_than: - '0' object: segment - id: seg_t4ir0Ds3gM3N7 name: Sign up customers created_at: '2023-08-03T10:37:49.225Z' updated_at: null type: auto-update filter: junction: and events.sign_up.count: conditions: $more_than: - '0' object: segment total: 99 security: - X-App-Id: [] X-App-Token: [] - X-Voucherify-OAuth: - api - segments components: parameters: limit: name: limit in: query required: false schema: $ref: '#/components/schemas/ParameterLimit' description: >- Limits the number of objects to be returned. The limit can range between 1 and 100 items. If no limit is set, it returns 10 items. schemas: ParameterOrderCreatedAt: type: string enum: - created_at - '-created_at' ParameterFiltersListSegments: type: object properties: junction: $ref: '#/components/schemas/Junction' id: type: object description: Unique segment ID. properties: conditions: $ref: '#/components/schemas/FilterConditionsString' name: type: object description: Unique user-defined segment name. properties: conditions: $ref: '#/components/schemas/FilterConditionsString' type: type: object description: Segment type. properties: conditions: type: object description: >- Data filters used to narrow down the data records to be returned in the result. properties: $in: type: array description: >- Array of resource values that should be included in the results (multiple values). items: type: string enum: - auto-update - passive - static $not_in: type: array description: >- Array of resource values that should be included in the results (multiple values). items: type: string enum: - auto-update - passive - static $is: type: string description: Value is exactly this value (single value). enum: - auto-update - passive - static $is_not: type: string description: Results omit this value (single value). enum: - auto-update - passive - static $has_value: type: string description: >- Value is NOT null. The value for this parameter is an empty string. $is_unknown: type: string description: >- Value is null. The value for this parameter is an empty string. $starts_with: type: string description: Value starts with the specified string. $ends_with: type: string description: Value ends with the specified string. created_at: description: >- Timestamp representing the date and time when the segment was created. The value is shown in the ISO 8601 format. type: object properties: conditions: $ref: '#/components/schemas/FilterConditionsDateTime' ParameterIds: type: array items: type: string SegmentsListResponseBody: title: List Customer Segments Response Body description: Response body schema for **GET** `v1/segments`. type: object properties: object: type: string default: list enum: - list description: >- The type of the object represented by JSON. This object stores information about segments. data_ref: type: string default: data enum: - data description: >- Identifies the name of the attribute that contains the array of segments. segments: type: array description: >- An array of segment objects. Returns an empty array if there are no results matching query parameters. items: $ref: '#/components/schemas/Segment' total: type: integer description: >- Total number of segments returned for given filters and query parameters with the exception of `limit`. required: - object - data_ref - data - total ParameterLimit: type: integer maximum: 100 minimum: 1 Junction: title: Junction description: >- 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. enum: - and - or type: string FilterConditionsString: title: Filter by conditions type: object description: >- Data filters used to narrow down the data records to be returned in the result. properties: $in: type: array description: >- Array of resource values that should be included in the results (multiple values). items: type: string $not_in: type: array description: >- Array of resource values that should be included in the results (multiple values). items: type: string $is: type: string description: Value is exactly this value (single value). $is_not: type: string description: Results omit this value (single value). $has_value: type: string description: Value is NOT null. The value for this parameter is an empty string. $is_unknown: type: string description: Value is null. The value for this parameter is an empty string. $starts_with: type: string description: Value starts with the specified string. $ends_with: type: string description: Value ends with the specified string. $contains: type: string description: Value includes the specified string. $not_contain: type: string description: Value does NOT include the specified string. FilterConditionsDateTime: title: Filter by conditions type: object description: >- Data filters used to narrow down the data records to be returned in the result. properties: $after: type: string description: >- Value is after this date. The value for this parameter is shown in the ISO 8601 format. format: date-time example: '2024-01-01T00:00:00.000Z' $before: type: string description: >- Value is before this date. The value for this parameter is shown in the ISO 8601 format. format: date-time example: '2024-01-01T00:00:00.000Z' $has_value: type: string description: Value is NOT null. The value for this parameter is an empty string. $is_unknown: type: string description: Value is null. The value for this parameter is an empty string. $more_than: type: integer description: >- Value is more days ago before the current date and time, e.g. more than `10` days ago. $less_than: type: integer description: >- Value is less days before the current date and time, e.g. less than `10` days ago. Segment: title: Segment type: object properties: id: type: string example: seg_1wc52c5z6r1kQ81brO8j9Hk2 description: Unique segment ID. name: type: string description: Segment name. created_at: type: string example: '2022-05-12T13:01:56.896Z' description: >- Timestamp representing the date and time when the segment was created. The value is shown in the ISO 8601 format. format: date-time updated_at: type: string format: date-time example: '2022-10-03T12:24:58.008Z' description: >- Timestamp in ISO 8601 format indicating when the segment was updated. type: type: string enum: - auto-update - passive - static description: >- 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: type: object nullable: true description: >- Defines a set of criteria for an `auto-update` or `passive` segment type. object: type: string default: segment description: >- The type of the object represented by JSON. This object stores information about the customer segment. enum: - segment description: This is an object representing a customer segment. securitySchemes: X-App-Id: type: apiKey name: X-App-Id in: header X-App-Token: type: apiKey name: X-App-Token in: header X-Voucherify-OAuth: type: oauth2 flows: implicit: authorizationUrl: https://api.voucherify.io/v1/oauth/token scopes: api: Gives access to whole server-side API. vouchers: >- Gives access to all endpoints and methods starting with `v1/vouchers`. client_api: Gives access to whole client-side API. client_vouchers: >- Gives access to all endpoints and methods starting with `/client/v1/vouchers`. promotions: >- Gives access to all endpoints and methods starting with `/v1/promotions`. client_promotions: >- Gives access to all endpoints and methods starting with `/client/v1/promotions` campaigns: >- Gives access to all endpoints and methods starting with `v1/campaigns`. client_publish: >- Gives access to all endpoints and methods starting with `/client/v1/publish`. exports: >- Gives access to all endpoints and methods starting with `/v1/exports`. publications: >- Gives access to all endpoints and methods starting with `/v1/publications`. client_validate: >- Gives access to all endpoints and methods starting with `/client/v1/validate`. validations: >- Gives access to all endpoints and methods starting with `/v1/validations`. client_validations: >- Gives access to all endpoints and methods starting with `/client/v1/validations`. qualifications: >- Gives access to all endpoints and methods starting with `/v1/qualifications`. client_qualifications: >- Gives access to all endpoints and methods starting with `/client/v1/qualifications`. client_redeem: >- Gives access to all endpoints and methods starting with `/client/v1/redeem redemptions: >- Gives access to all endpoints and methods starting with `/v1/redemptions`. client_redemptions: >- Gives access to all endpoints and methods starting with `/client/v1/redemptions` customers: >- Gives access to all endpoints and methods starting with `/v1/customers`. client_customers: >- Gives access to all endpoints and methods starting with `/client/v1/customers`. orders: >- Gives access to all endpoints and methods starting with `/v1/orders`. products: >- Gives access to all endpoints and methods starting with `/v1/products`. skus: >- Gives access to all endpoints and methods starting with `/v1/SKUs`. validation-rules: >- Gives access to all endpoints and methods starting with `/v1/validation-rules`. validation-rules-assignments: >- Gives access to all endpoints and methods starting with `/v1/validation-rules-assignments segments: >- Gives access to all endpoints and methods starting with `/v1/segments`. events: >- Gives access to all endpoints and methods starting with `/v1/events`. client_events: >- Gives access to all endpoints and methods starting with `client/v1/events`. rewards: >- Gives access to all endpoints and methods starting with `/v1/rewards`. assets: >- Gives access to all endpoints and methods starting with `/v1/assets`. task-results: >- Gives access to all endpoints and methods starting with `/v1/task-results`. loyalties: >- Gives access to all endpoints and methods starting with `/v1/loyalties`. client_consents: >- Gives access to all endpoints and methods starting with `client/v1/consents`. consents: >- Gives access to all endpoints and methods starting with `/v1/consents`. async-actions: >- Gives access to all endpoints and methods starting with `/v1/async-actions`. product-collections: >- Gives access to all endpoints and methods starting with `/v1/product-collections`. categories: >- Gives access to all endpoints and methods starting with `/v1/categories`. metadata-schemas: >- Gives access to all endpoints and methods starting with `/v1/metadata-schemas`. locations: >- Gives access to all endpoints and methods starting with `/v1/locations`. referrals: >- Gives access to all endpoints and methods starting with `/v1/referrals`. trash-bin: >- Gives access to all endpoints and methods starting with `/v1/trash-bin`. templates: >- Gives access to all endpoints and methods starting with `/v1/templates`. ````