---
updatedAt: 2026-04-23T13:15:35.000Z
agentTools:
  projectIndex: https://api-docs.omnisend.com/llms.txt
---

# List segments

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.

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "contact": {},
    "description": "Manage contact segments using flexible condition-based rules.",
    "title": "Segments API",
    "version": "5.0"
  },
  "paths": {
    "/segments": {
      "get": {
        "description": "List segments with sorting and cursor-based pagination support.\n\n**Scopes:**\n`segments.read`\n\n**Pagination:**\nThis endpoint uses cursor-based pagination. Use the `after` cursor from the response to get the next page,\nor the `before` cursor to get the previous page. Do not use both `after` and `before` parameters simultaneously.\n\n**Sorting:**\n- Only single-field sorting is supported. You cannot sort by multiple fields.\n- Available sort fields: `createdAt` (default), `name`.\n- When sorting by `name`, segments are sorted lexicographically (case-sensitive).\n- Sort parameters are only required on the first request. Subsequent requests using a cursor\nwill automatically use the sort settings embedded in the cursor.\n\n**Cursor Behavior:**\n- Cursors are self-contained and include all parameters needed for pagination.\n- Once you have a cursor, you only need to pass the cursor for subsequent pages.\n- If sort parameters are provided with a cursor, they must match the cursor's sort settings.\n- Cursors may become invalid if the underlying data changes significantly (e.g., the referenced segment is deleted).\n\n**Rate Limiting:**\nThis endpoint is rate limited to 100 requests per minute.",
        "parameters": [
          {
            "description": "Page size (1-50)",
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 10
            }
          },
          {
            "description": "Cursor for next page (base64-encoded, obtained from previous response)",
            "in": "query",
            "name": "after",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Cursor for previous page (base64-encoded, obtained from previous response)",
            "in": "query",
            "name": "before",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Sort field (only needed on first request)",
            "in": "query",
            "name": "sort",
            "schema": {
              "type": "string",
              "enum": [
                "createdAt",
                "name"
              ],
              "default": "createdAt"
            }
          },
          {
            "description": "Sort direction (only needed on first request)",
            "in": "query",
            "name": "direction",
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "desc"
            }
          },
          {
            "$ref": "#/components/parameters/APIVersionHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Segments list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListSegmentsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "401": {
            "description": "Authentication is missing or invalid",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient permissions for this operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "410": {
            "description": "API version has been retired",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateLimitProblem"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected error occurred",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "security": [
          {
            "Bearer": [
              "segments.read"
            ]
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "List segments",
        "tags": [
          "Segments"
        ]
      }
    }
  },
  "servers": [
    {
      "url": "https://api.omnisend.com/api"
    }
  ],
  "components": {
    "parameters": {
      "APIVersionHeader": {
        "description": "API version that specifies the response format and behaviour (e.g., 2026-preview)",
        "in": "header",
        "name": "Omnisend-Version",
        "required": true,
        "schema": {
          "type": "string",
          "default": "2026-03-15"
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "description": "API Key authentication. Value format: 'Omnisend-API-Key {api-key}'",
        "in": "header",
        "name": "Authorization",
        "type": "apiKey",
        "x-default": "Omnisend-API-Key your-api-key"
      },
      "Bearer": {
        "type": "oauth2",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://app.omnisend.com/oauth2/token",
            "scopes": {
              "segments.read": "Read segments",
              "segments.write": "Create, update and delete segments"
            }
          }
        }
      }
    },
    "schemas": {
      "CursorsResponse": {
        "description": "Cursor pointers for paginating forward and backward through results",
        "properties": {
          "after": {
            "description": "Opaque cursor for fetching the next page of results",
            "example": "eyJpZCI6ImNhbXAtNDU2In0",
            "type": "string",
            "nullable": true
          },
          "before": {
            "description": "Opaque cursor for fetching the previous page of results",
            "example": "eyJpZCI6ImNhbXAtMTIzIn0",
            "type": "string",
            "nullable": true
          }
        },
        "type": "object"
      },
      "GetSegmentResponse": {
        "description": "Segment resource representation.",
        "properties": {
          "archivedAt": {
            "description": "Segment archival timestamp, null if not archived (read-only)",
            "example": "2026-06-01T00:00:00Z",
            "readOnly": true,
            "type": "string",
            "nullable": true
          },
          "conditionGroups": {
            "description": "Condition groups defining the segment rules",
            "items": {
              "$ref": "#/components/schemas/SegmentConditionGroup"
            },
            "type": "array"
          },
          "createdAt": {
            "description": "Segment creation timestamp (read-only)",
            "example": "2026-01-15T10:30:00Z",
            "readOnly": true,
            "type": "string"
          },
          "isStarred": {
            "description": "Whether the segment is marked as a favourite",
            "example": false,
            "type": "boolean"
          },
          "name": {
            "description": "Segment name",
            "example": "VIP Customers",
            "type": "string"
          },
          "segmentID": {
            "description": "Segment unique identifier (read-only)",
            "example": "000000000000000000000001",
            "readOnly": true,
            "type": "string"
          },
          "status": {
            "description": "Segment processing status (read-only)",
            "enum": [
              "ready",
              "building",
              "archived"
            ],
            "example": "ready",
            "readOnly": true,
            "type": "string"
          },
          "updatedAt": {
            "description": "Segment last update timestamp (read-only)",
            "example": "2026-01-20T14:45:00Z",
            "readOnly": true,
            "type": "string"
          }
        },
        "type": "object"
      },
      "ListSegmentsResponse": {
        "description": "Paginated list of segments.",
        "properties": {
          "paging": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PagingResponse"
              }
            ],
            "description": "Pagination metadata for navigating results"
          },
          "segments": {
            "description": "List of segments on the current page",
            "items": {
              "$ref": "#/components/schemas/GetSegmentResponse"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "PagingResponse": {
        "description": "Cursor-based pagination metadata",
        "properties": {
          "cursors": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CursorsResponse"
              }
            ],
            "description": "Cursor values for navigating between pages"
          },
          "hasMore": {
            "description": "Whether there are more items available beyond the current page",
            "example": true,
            "type": "boolean"
          },
          "limit": {
            "description": "Maximum number of items returned per page",
            "example": 50,
            "type": "integer"
          }
        },
        "type": "object"
      },
      "Problem": {
        "description": "Standard error response returned by all API endpoints on failure.",
        "properties": {
          "detail": {
            "description": "Human-readable explanation of this specific error occurrence",
            "example": "A human-readable explanation of the error.",
            "type": "string"
          },
          "instance": {
            "description": "Request trace identifier for support and debugging",
            "example": "urn:omnisend:request:00000000-0000-0000-0000-000000000001",
            "type": "string"
          },
          "status": {
            "description": "HTTP status code",
            "example": 0,
            "type": "integer"
          },
          "title": {
            "description": "Short description of the error type",
            "example": "Problem",
            "type": "string"
          },
          "type": {
            "description": "URI that identifies the error type",
            "example": "https://problems.omnisend.com/problem",
            "type": "string"
          }
        },
        "type": "object"
      },
      "RateLimitProblem": {
        "description": "Error response returned when the rate limit is exceeded. Use the retryAfter value to know when it is safe to retry the request.",
        "properties": {
          "detail": {
            "description": "Human-readable explanation of this specific error occurrence",
            "example": "A human-readable explanation of the error.",
            "type": "string"
          },
          "instance": {
            "description": "Request trace identifier for support and debugging",
            "example": "urn:omnisend:request:00000000-0000-0000-0000-000000000001",
            "type": "string"
          },
          "retryAfter": {
            "description": "Seconds to wait before retrying the request",
            "example": 60,
            "type": "integer"
          },
          "status": {
            "description": "HTTP status code",
            "example": 0,
            "type": "integer"
          },
          "title": {
            "description": "Short description of the error type",
            "example": "Problem",
            "type": "string"
          },
          "type": {
            "description": "URI that identifies the error type",
            "example": "https://problems.omnisend.com/problem",
            "type": "string"
          }
        },
        "type": "object"
      },
      "SegmentCondition": {
        "description": "A single filter condition applied to a specific entity.",
        "properties": {
          "entity": {
            "description": "Entity type this condition applies to",
            "example": "contact",
            "type": "string"
          },
          "filters": {
            "description": "List of filter criteria. Must contain at least one item.",
            "items": {},
            "minItems": 1,
            "type": "array"
          },
          "junction": {
            "description": "Logical operator combining the filters within this condition",
            "example": "and",
            "type": "string"
          }
        },
        "required": [
          "filters"
        ],
        "type": "object"
      },
      "SegmentConditionGroup": {
        "description": "Group of conditions combined with a logical junction.",
        "properties": {
          "conditions": {
            "description": "List of conditions in this group",
            "items": {
              "$ref": "#/components/schemas/SegmentCondition"
            },
            "type": "array"
          }
        },
        "type": "object"
      }
    }
  }
}
```