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

# List segments

`GET /segments`

## Request

- Base URL: `https://api.omnisend.com/api`
- URL: `https://api.omnisend.com/api/segments`
- Auth: one of:
  - OAuth 2
    - Client credentials
    - Token URL: `https://app.omnisend.com/oauth2/token` scopes: `segments.read`
  - API key in header `Authorization`

List segments with sorting and cursor-based pagination support.

**Scopes:**
`segments.read`

**Pagination:**
This endpoint uses cursor-based pagination. Use the `after` cursor from the response to get the next page,
or the `before` cursor to get the previous page. Do not use both `after` and `before` parameters simultaneously.

**Sorting:**
- Only single-field sorting is supported. You cannot sort by multiple fields.
- Available sort fields: `createdAt` (default), `name`.
- When sorting by `name`, segments are sorted lexicographically (case-sensitive).
- Sort parameters are only required on the first request. Subsequent requests using a cursor
will automatically use the sort settings embedded in the cursor.

**Cursor Behavior:**
- Cursors are self-contained and include all parameters needed for pagination.
- Once you have a cursor, you only need to pass the cursor for subsequent pages.
- If sort parameters are provided with a cursor, they must match the cursor's sort settings.
- Cursors may become invalid if the underlying data changes significantly (e.g., the referenced segment is deleted).

**Rate Limiting:**
This endpoint is rate limited to 100 requests per minute.

## Query parameters

- `limit` integer
- `after` string
- `before` string
- `sort` 'createdAt' | 'name'
- `direction` 'asc' | 'desc'

## Headers

- `Omnisend-Version` string, required

## Response `200`

Segments list

- ListSegmentsResponse: Paginated list of segments.
  - `paging` PagingResponse: Cursor-based pagination metadata
    - `cursors` CursorsResponse: Cursor pointers for paginating forward and backward through results
      - `after` string, nullable: Opaque cursor for fetching the next page of results
      - `before` string, nullable: Opaque cursor for fetching the previous page of results
    - `hasMore` boolean: Whether there are more items available beyond the current page
    - `limit` integer: Maximum number of items returned per page
  - `segments` GetSegmentResponse[]: List of segments on the current page
    - `archivedAt` string, nullable: Segment archival timestamp, null if not archived (read-only)
    - `conditionGroups` SegmentConditionGroup[]: Condition groups defining the segment rules
      - `conditions` SegmentCondition[]: List of conditions in this group
        - `entity` string: Entity type this condition applies to
        - `filters` unknown[], required: List of filter criteria. Must contain at least one item.
          - unknown
        - `junction` string: Logical operator combining the filters within this condition
    - `createdAt` string: Segment creation timestamp (read-only)
    - `isStarred` boolean: Whether the segment is marked as a favourite
    - `name` string: Segment name
    - `segmentID` string: Segment unique identifier (read-only)
    - `status` 'ready' | 'building' | 'archived': Segment processing status (read-only)
    - `updatedAt` string: Segment last update timestamp (read-only)

## Other responses

- `400`: Invalid request parameters
- `401`: Authentication is missing or invalid
- `403`: Insufficient permissions for this operation
- `410`: API version has been retired
- `429`: Rate limit exceeded
- `500`: Unexpected error occurred

---

[API](https://skmtc.dev/omnisend/apis/segments-api.md) - [All operations](https://skmtc.dev/omnisend/apis/segments-api/llms.txt) - [OpenAPI document](https://skmtc.dev/omnisend/apis/segments-api/revisions/5d5cfb339623?raw)