# List dynamic sets.

`GET /sets`

> Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-sets · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetSets` · Tag: Dynamic Sets

Returns all dynamic sets the authenticated user owns or has shared access to, including both free and paid sets. Use the `is_paid` field to tell them apart — only paid sets expose KPI data, and free sets can be upgraded via `POST /sets/{set_id}/upgrade`. Results are ordered by most recently updated first and paginated.

Narrow the list with `name` and `kind`. Both are optional, and sending both returns only the sets matching each of them.

## Request

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

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.

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | Match sets by name. `*` stands for any run of characters, so `*Palm Springs*` matches sets with that phrase anywhere in the name, `Palm*` matches names starting with it, and a value with no `*` has to match the whole name. Matching ignores case, and any other character — including `%` and `_` — is matched literally. (example: `*Palm Springs*`) |
| `kind` | string | no | Match sets by their `kind` — see the `kind` field of the set object for the values. Comma-separate several to match any of them, e.g. `competitive,market`. Sets with no kind are reported as `other` and are matched by `kind=other`. An unrecognised value returns 400. (example: `competitive`) |
| `per_page` | integer | no | Number of sets per page. (default: `50`, min: 1, max: 100) |
| `page` | integer | no | Page number to retrieve. |
| `offset` | integer | no | Number of items to skip before starting to collect the result set. |

### Example request

```bash
curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/sets' \
  -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 dynamic sets.

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

A dynamic set (comp set).

- `id` (integer, required): The Wheelhouse internal dynamic set ID.
- `user_id` (integer, required): The Wheelhouse internal ID of the user that owns the set.
- `name` (string, required): The set name.
- `description` (string, nullable): An optional description of the set.
- `kind` (string, one of: `competitive`, `market`, `neighborhood`, `marketing`, `acquisition`, `underwriting`, `other`, `merchandising`): The intended use case for the set:
  - `competitive` — tracks direct competitor properties.
  - `market` — broad market-wide overview.
  - `neighborhood` — properties in the same geographic sub-area.
  - `marketing` — properties used as marketing or positioning references.
  - `acquisition` — evaluating potential acquisition targets.
  - `underwriting` — used in underwriting or investment analysis.
  - `merchandising` — set curated for merchandising purposes.
  - `other` — general-purpose or uncategorized set.
- `currency` (string, nullable): The ISO-4217 3-letter currency code of the set.
- `is_static` (boolean): Whether the set membership is static. Non-static sets are kept in sync automatically based on the set's boundary and filters.
- `is_paid` (boolean): Whether the set is on the paid Dynamic Sets plan. Only paid sets expose the set-level analytics endpoints (aggregated_metrics, time_series, distribution, changelog), which return `404 Not Found` for a free set. Endpoints for building and reviewing a set — including its member listings and associated_listings — work on free sets too. See the Dynamic Sets section for the full per-endpoint breakdown. Upgrade a free set via `POST /sets/{set_id}/upgrade`.
- `filters` (object, nullable): The filter criteria used to select member listings (non-static sets). Keys are listing attributes/metrics, values contain `lower`/`upper` bounds or `one_of` lists.
- `boundary` (array of array of array of array of number, nullable, each item each item each item min items: 2, max items: 2): The geographic boundary of the set as MultiPolygon coordinates (`[[[[lng, lat], ...]]]`), if one is defined.

  The four levels of nesting are: **polygons** → **rings** → **points** → **coordinates**.

  - **Polygons** (`boundary[i]`): Each element is one polygon.
  - **Rings** (`boundary[i][j]`): Each polygon contains one or more linear rings. The first ring is the exterior boundary (outer shell of the shape); any subsequent rings represent interior boundaries (holes inside the polygon).
  - **Points** (`boundary[i][j][k]`): Each ring is an array of `[longitude, latitude]` coordinate pairs.
  - **Coordinates** (`boundary[i][j][k][0/1]`): Each point is `[longitude, latitude]` as floating-point numbers.
- `listing_counts` (object): Number of member listings in the set per status.
  - `active` (integer)
  - `hidden` (integer)
  - `review` (integer)
  - `removed` (integer)
- `updated_at` (string (date-time)): When the set was last updated (ISO-8601).

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

```json
[
  {
    "id": 0,
    "user_id": 0,
    "name": "string",
    "description": "string",
    "kind": "competitive",
    "currency": "string",
    "is_static": true,
    "is_paid": true,
    "filters": {},
    "boundary": [
      [
        [
          [
            0,
            0
          ]
        ]
      ]
    ],
    "listing_counts": {
      "active": 0,
      "hidden": 0,
      "review": 0,
      "removed": 0
    },
    "updated_at": "2026-01-01T00:00:00Z"
  }
]
```

### 400

An unrecognised `kind` was requested.

### 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"
}
```
