# Dynamic Sets

> Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/dynamic-sets · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml

Dynamic sets are user-curated sets of comparison listings used to track competitive performance. Use these endpoints to build a set from scratch (search for candidate listings near a location, create a set from them, and upgrade it to paid), list a user's sets, inspect a set's definition and member listings, retrieve aggregated performance metrics, manage which of the user's own listings the set is associated with, and fetch a set's change history, time-series metrics, and metric distributions.

`GET /sets` returns both free and paid sets; the `is_paid` field on each set indicates which. Everything involved in **building** a set works on a free one — creating it, adding and removing its member listings, reviewing them, and managing which of your own listings it is associated with. What the paid plan buys is the **set-level analytics** computed across the set, including its price calendar. A paid-only endpoint returns `404 Not Found` for a free set, which is indistinguishable from a set that does not exist, so check `is_paid` before calling one.

| Endpoint | Free sets | Paid sets |
|---|---|---|
| `GET /sets` | ✅ | ✅ |
| `POST /sets` | ✅ (creates a free set) | — |
| `GET /sets/candidates` | ✅ (no set required) | ✅ |
| `GET /sets/{set_id}` | ✅ | ✅ |
| `POST /sets/{set_id}/upgrade` | ✅ (this is what upgrades it) | — |
| `POST /sets/{set_id}/share` | ✅ | ✅ |
| `GET /sets/{set_id}/listings` | ✅ | ✅ |
| `PUT /sets/{set_id}/listings` | ✅ | ✅ |
| `DELETE /sets/{set_id}/listings` | ✅ | ✅ |
| `GET /sets/{set_id}/associated_listings` | ✅ | ✅ |
| `PUT /sets/{set_id}/associated_listings` | ✅ | ✅ |
| `DELETE /sets/{set_id}/associated_listings` | ✅ | ✅ |
| `GET /sets/{set_id}/aggregated_metrics` | ❌ 404 | ✅ |
| `GET /sets/{set_id}/price_calendar` | ❌ 404 | ✅ (up to 25 members) |
| `GET /sets/{set_id}/time_series` | ❌ 404 | ✅ |
| `GET /sets/{set_id}/distribution` | ❌ 404 | ✅ |
| `GET /sets/{set_id}/changelog` | ❌ 404 | ✅ |

Upgrade a free set with `POST /sets/{set_id}/upgrade`, which purchases the paid plan and charges the billable user. Sets the user owns as well as sets shared with the user are included throughout; modifying a shared set requires editor or manager access to it.

## Endpoints

- [GET /sets](https://docs.usewheelhouse.com/rm/reference/rm-get-sets.md): List dynamic sets.
- [POST /sets](https://docs.usewheelhouse.com/rm/reference/rm-create-set.md): Create a dynamic set.
- [GET /sets/candidates](https://docs.usewheelhouse.com/rm/reference/rm-get-set-candidates.md): Search candidate listings for a dynamic set.
- [GET /sets/{set_id}](https://docs.usewheelhouse.com/rm/reference/rm-get-set.md): Get a single dynamic set.
- [POST /sets/{set_id}/upgrade](https://docs.usewheelhouse.com/rm/reference/rm-upgrade-set.md): Upgrade a dynamic set to a paid set.
- [GET /sets/{set_id}/aggregated_metrics](https://docs.usewheelhouse.com/rm/reference/rm-get-set-aggregated-metrics.md): Get aggregated metrics for a dynamic set.
- [GET /sets/{set_id}/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-set-listings.md): List the listings in a dynamic set.
- [PUT /sets/{set_id}/listings](https://docs.usewheelhouse.com/rm/reference/rm-put-set-listings.md): Add member listings to a dynamic set.
- [DELETE /sets/{set_id}/listings](https://docs.usewheelhouse.com/rm/reference/rm-delete-set-listings.md): Remove member listings from a dynamic set.
- [GET /sets/{set_id}/associated_listings](https://docs.usewheelhouse.com/rm/reference/rm-get-set-associated-listings.md): List the user listings associated with a dynamic set.
- [PUT /sets/{set_id}/associated_listings](https://docs.usewheelhouse.com/rm/reference/rm-put-set-associated-listings.md): Associate user listings with a dynamic set.
- [DELETE /sets/{set_id}/associated_listings](https://docs.usewheelhouse.com/rm/reference/rm-delete-set-associated-listings.md): Remove associated user listings from a dynamic set.
- [GET /sets/{set_id}/price_calendar](https://docs.usewheelhouse.com/rm/reference/rm-get-set-price-calendar.md): Get the price calendar of a dynamic set's member listings.
- [GET /sets/{set_id}/changelog](https://docs.usewheelhouse.com/rm/reference/rm-get-set-changelog.md): Get the changelog of a dynamic set.
- [POST /sets/{set_id}/share](https://docs.usewheelhouse.com/rm/reference/rm-share-set.md): Share a dynamic set with other users.
- [GET /sets/{set_id}/time_series](https://docs.usewheelhouse.com/rm/reference/rm-get-set-time-series.md): Get time-series metrics for a dynamic set.
- [GET /sets/{set_id}/distribution](https://docs.usewheelhouse.com/rm/reference/rm-get-set-distribution.md): Get metric distributions for a dynamic set.
