# List portfolio segments.

`GET /segments`

> Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-segments · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetSegments` · Tag: Segments

Returns all portfolio segments for the authenticated user. Segments are used in the Wheelhouse UI to group listings by filter criteria; this endpoint provides read-only access to the segment list.

## Request

`GET https://api.usewheelhouse.com/ss_api/v1/segments`

Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Read-only keys can call this endpoint.

### Example request

```bash
curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/segments' \
  -H 'X-Integration-Api-Key: <your RM API key>'
```

Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say.

## Responses

### 200

Array of portfolio segments.

Body (`application/json`): array of object `portfolio_segment_response`

A portfolio segment.

- `id` (integer, required): The Wheelhouse internal segment ID.
- `name` (string): The segment name.
- `description` (string, nullable): An optional description of the segment.
- `filter_backend` (object `filter_backend_object`): A map that controls which listings belong to a segment. Keys are listing attribute
  paths with optional operator suffixes; values are the match criteria. All entries
  are ANDed — a listing must satisfy every condition to be included.

  **Structure**: `{ "key[_suffix]": value, ... }`

  ---

  #### Boolean parameters

  Accept `true` or `false`. No operator suffixes.

  | Key | Description |
  |---|---|
  | `is_live` | Listing is live on its channel |
  | `user_removed` | Listing has been marked removed by the user |
  | `listings.is_active` | Listing is active in Wheelhouse |
  | `listing_preferences.automatic_rate_posting_enabled` | Automatic rate posting is enabled |
  | `listing_views.in_market` | Listing is in a Wheelhouse-covered market |

  ---

  #### Numeric range parameters

  Each base key supports six operator suffixes: `key` (=), `key_ne` (≠),
  `key_lt` (<), `key_gt` (>), `key_lte` (≤), `key_gte` (≥).
  Values are integers (floats accepted for `bathrooms`).

  | Key | Description |
  |---|---|
  | `bedrooms` | Number of bedrooms |
  | `bathrooms` | Number of bathrooms |
  | `sleeps` | Maximum guest capacity |
  | `beds` | Number of beds |
  | `guests_included` | Guests included in the base rate |
  | `number_of_units` | Number of units at the property |
  | `review_count` | Total guest reviews |
  | `listings.minimum_stay` | Default minimum stay in nights |
  | `listings.cleaning_fee` | Cleaning fee amount |
  | `listings.security_deposit` | Security deposit amount |
  | `listing_preferences.base_price` | Wheelhouse base price |
  | `listing_preferences.weekly_discount` | Weekly discount percentage |
  | `listing_preferences.monthly_discount` | Monthly discount percentage |
  | `listing_views.number_of_editors` | Co-host editor count |
  | `listing_views.number_of_restricted_editors` | Restricted editor count |
  | `listing_views.number_of_viewers` | Viewer-level co-host count |
  | `listing_views.minimum_stay_rules_count` | Minimum-stay rules configured |
  | `listing_views.minimum_price_rules_count` | Minimum-price rules configured |

  Performance stats use scoped keys of the form
  `listing_stats_rolling:metric:{metric}:{window}` with the same six
  operator suffixes as other numeric ranges. Windows are `next_N`
  (forward-looking) and `past_N` (trailing) for N in
  7, 14, 21, 30, 60, 90, 180, 365. Metrics include `revenue`,
  `occupancy`, and `booking_count`.
  Example: `"listing_stats_rolling:metric:revenue:next_30_gte": 5000`.
  The most recent booking date remains `listing_stats.last_booked_at`
  under date ranges.

  ---

  #### Enumeration parameters

  Three operator suffixes: `key` (=), `key_ne` (≠), `key_enum` (returns the distinct
  values present on the authenticated user's listings — useful for discovering valid values).

  | Key | Value type | Notes |
  |---|---|---|
  | `source` | string | Channel short ID: `"A"` (Airbnb), `"V"` (Vrbo), `"B"` (Booking.com) |
  | `market_id` | integer | Wheelhouse market ID |
  | `country_code` | string | ISO 3166-1 alpha-2 (e.g. `"US"`, `"GB"`) |
  | `room_type` | string | As reported by the channel (e.g. `"Entire place"`) |
  | `channel_account_id` | integer | Wheelhouse channel connection ID |
  | `listings.currency` | string | ISO 4217 currency code (e.g. `"USD"`, `"EUR"`) |
  | `listings.price_model_id` | integer | Active price model ID |
  | `channel_accounts.status` | string | `"active"`, `"failed"`, `"disabled"`, `"pending"`, `"empty"`, `"invalid_auth"` |
  | `charge_bee_items.id` | string | Billing plan (e.g. `"Free"`, `"Flex_Plan"`, `"Flat_Plan"`) |
  | `managed_listings.level` | string | Co-host level: `"editor"`, `"restricted_editor"`, `"viewer"` |
  | `listings.operating_user_id` | integer | User ID of the operating account |

  ---

  #### String match parameters

  Two operator suffixes: `key` (contains), `key_not` (does not contain).
  Case-insensitive substring match. Comma-separate multiple values for OR logic:
  `"listings.title": "Beach,Ocean"` matches titles containing *either* word.

  | Key | Description |
  |---|---|
  | `listings.title` | Listing title |
  | `listing_views.display_name` | Display name |
  | `listing_views.display_nickname` | Display nickname |
  | `source_address` | Source address |

  ---

  #### Tag parameters

  Filter by Wheelhouse tag IDs (integers). Four operator suffixes:

  | Suffix | Match logic |
  |---|---|
  | `tags.id` | Has **any** of the listed tag IDs (OR) |
  | `tags.id_ne` | Has **none** of the listed tag IDs |
  | `tags.id_and` | Has **all** of the listed tag IDs (AND) |
  | `tags.id_and_ne` | Does **not** have all of the listed tag IDs |

  To combine multiple independent tag conditions in one object, append any unique
  identifier after the suffix — the system strips it before evaluating. Example:
  `"tags.id_pool": [12]` and `"tags.id_certified_and": [5, 7]` are treated as
  two separate filters on the same object.

  ---

  #### Date range parameters

  Six operator suffixes, same as numeric range. Values are either an ISO 8601 date
  string (`"2025-01-01"`) or an integer for a rolling window relative to today
  (`30` means "30 days ago").

  | Key | Description |
  |---|---|
  | `listings.created_at` | When the listing was created in Wheelhouse |
  | `listing_stats.last_booked_at` | Date of the listing's most recent booking |

  ---

  #### Membership parameters

  | Key | Value type | Description |
  |---|---|---|
  | `listings.id_in` | integer[] | Include only listings with these internal IDs |
  | `listings.id_not_in` | integer[] | Exclude listings with these internal IDs |
  | `listings.source_not_in` | string[] | Exclude listings from these channels |

  ---

  #### Geographic parameter

  | Key | Value format | Description |
  |---|---|---|
  | `latlong_distance_from_lte` | `"latitude,longitude,meters"` | Listings within the radius of the given coordinates |

  ---

  **Example**

  ```json
  {
    "is_live": true,
    "bedrooms_gte": 2,
    "source": "A",
    "listings.title": "Beach,Ocean",
    "tags.id_pool": [12],
    "listings.created_at_gte": "2025-01-01",
    "listings.id_in": [101, 102, 103]
  }
  ```
- `is_default` (boolean): Whether this is the default segment.
- `created_at` (string (date-time), required): When the segment was created (ISO-8601).
- `updated_at` (string (date-time), required): When the segment was last updated (ISO-8601).

Example shape (generated from the schema; placeholder values, not a real response):

```json
[
  {
    "id": 0,
    "name": "string",
    "description": "string",
    "filter_backend": {},
    "is_default": true,
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z"
  }
]
```

### 401

API key authorization failed.

### 429

Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy.

Body (`application/json`): object

- `error` (string, example: `API token is at rate limit`)

Example shape (generated from the schema; placeholder values, not a real response):

```json
{
  "error": "API token is at rate limit"
}
```
