Segments

Portfolio segments group listings by filter criteria. The filter_backend field is the core of a segment — it defines which listings belong to it.

Use POST /segments to create a segment, PUT /segments/{segment_id} to update one, GET /segments to list all segments for the authenticated user, GET /segments/{segment_id}/listings to retrieve the listings matched by a segment's filter, and GET /segments/{segment_id}/aggregated_metrics to fetch aggregated performance metrics for those listings.

See the filter_backend_object schema for a full reference of available filter keys, operator suffixes, and value formats.

📄️List portfolio 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.

📄️Create a portfolio segment.

Creates a new portfolio segment owned by the authenticated user.

📄️Update a portfolio segment.

Updates the name, description, and/or default status of an existing portfolio segment. All fields are optional; omitted fields are left unchanged.

📄️List listings in a segment.

Returns the listings that belong to the given portfolio segment. The segment's filter criteria are applied to the user's portfolio — for an RM API key that includes listings shared with the user to manage, not just listings they own (see `include_managed_listings`). Supports pagination and optional exclusion of inactive listings.

📄️Get aggregated metrics for a segment.

Returns monthly performance metrics aggregated across the listings matched by the segment's filter. For an RM API key the filter is evaluated against listings shared with the user to manage as well as listings they own (see `include_managed_listings`). Monetary values are converted to the requested currency. Because a segment has no currency of its own, the default is the currency of the most common market among the segment's listings (falling back to USD).