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

# List audience segments

`GET /audience/segments`

## Request

- Base URL: `https://app.lettr.com/api`
- URL: `https://app.lettr.com/api/audience/segments`
- Auth: HTTP bearer

List segments with pagination. Requires the `audience:read` scope.

## Query parameters

- `page` integer
- `per_page` integer
- `list_id` string, uuid

## Response `200`

Segments retrieved successfully.

- ListAudienceSegmentsResponse
  - `message` string, required
  - `data` object, required
    - `segments` AudienceSegmentView[], required
      - `id` string, uuid, required
      - `name` string, required
      - `list_id` string, uuid, nullable, required: Restrict segment to a single list (null = all lists)
      - `list_name` string, nullable, required
      - `condition_groups` SegmentConditionGroup[], required
        - `conditions` SegmentCondition[], required
          - `field` string, required: Field to match: `email`, `status`, `created_at`, `properties.<name>` for a custom property, or `topics` / `lists` (by name, `equals` and `not_equals` only). Any other field or operator combination is rejected with `422`.
          - `operator` 'contains' | 'not_contains' | 'equals' | 'not_equals' | 'starts_with' | 'not_starts_with' | 'ends_with' | 'not_ends_with' | 'is_true' | 'is_false' | 'is_empty' | 'is_not_empty' | 'greater_than' | 'greater_than_or_equal' | 'less_than' | 'less_than_or_equal' | 'before' | 'after', required: Segment condition operator
          - `value` string, nullable: Value to compare against. Required for all operators except `is_true` and `is_false`, which evaluate the field's truthiness and accept no value (may be omitted or `null`).
      - `cached_contacts_count` integer, nullable, required: Last computed contacts count (may be stale)
      - `created_at` string, date-time, required
    - `pagination` AudiencePagination, required: Pagination info for audience list responses
      - `total` integer, required: Total items
      - `per_page` integer, required: Items per page
      - `current_page` integer, required: Current page (1-indexed)
      - `last_page` integer, required: Last available page (= ceil(total / per_page), minimum 1)

## Other responses

- `401`: Unauthorized - Missing or invalid API key
- `403`: Forbidden - API key does not have the required scope
- `422`: Validation error
- `500`: Internal server error
- `503`: Service unavailable - the API key could not be verified, so the request was not processed. This does not mean the key is invalid; retry after the delay given in the Retry-After header.

---

[API](https://skmtc.dev/lettr/apis/lettr-api.md) · [All operations](https://skmtc.dev/lettr/apis/lettr-api/llms.txt) · [OpenAPI document](https://skmtc.dev/lettr/apis/lettr-api/revisions/48ef0dac1ebd?raw)