# Rank every listing by one KPI.

`GET /listings/kpis`

> Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-bulk-listing-kpis · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetBulkListingKpis` · Tag: Listings

Returns a single KPI for every listing the authenticated user can access, ranked
by value. Use it to answer portfolio-wide questions (the best or worst
performers on a metric) in one call instead of one call per listing.

Pick the metric with `metric`, then either a rolling window with `window` or a
calendar period with `period` and `period_start`. Exactly one of `window` and
`period` is required.

**Rolling windows.** `0_30` is the next 30 days and `30_0` the trailing 30.
Values come from the same store as
[`GET /listings/{listing_id}/kpis`](https://docs.usewheelhouse.com/rm/reference/rm-get-listing-kpis.md), so the two
always agree; that endpoint remains the way to read every metric and window for
one listing.

**Calendar periods.** `period=monthly&period_start=2026-07-01` ranks on July
2026, `period=quarterly&period_start=2026-07-01` on the third quarter and
`period=yearly&period_start=2026-01-01` on the year. `period_start` must be the
first day of the period. Values are the ones
[`GET /listings/{listing_id}/kpis/monthly`](https://docs.usewheelhouse.com/rm/reference/rm-get-listing-kpis-monthly.md),
`/kpis/quarterly` and `/kpis/yearly` return. Periods are held from three years
back through the calendar horizon. A period from the current one onward is not
final: it reflects the bookings on the books so far, and changes as bookings
come in. Every metric that is computed in both directions can be ranked by
period except `asking_rate_fees`, `last_booked_days` and `min_price_occurrence`;
forward-only and backward-only metrics cannot. A ranking covers one period, so
to compare several months call it once per month.

**Year over year.** With a `period`, pass `compare=previous_year` to add the
same period one year earlier to each row as `compare_value`, along with `change`
(`value - compare_value`) and `change_ratio` (`value / compare_value`). The
comparison is the earlier period's final figure, not the figure as it stood at
the same point last year, so comparing a period still in progress against a
finished one favours the finished one. `rank_by=change` or
`rank_by=change_ratio` ranks on the comparison instead of the value. For a rate
such as `occupancy`, `change` is a difference of fractions, so `0.05` is five
percentage points.

**Metrics** (window `0_N` and `N_0`): `adr`, `adr_fees`, `asking_rate`,
`asking_rate_available`, `asking_rate_fees`, `asking_rate_highest`,
`asking_rate_lowest`, `bookings`,
`last_booked_days`, `lead_time`, `length_of_stay`, `min_price_occurrence`,
`nights_available`, `nights_blocked`, `nights_bookable`, `nights_booked`,
`nights_calendar`, `nights_percent_open`, `occupancy`, `occupancy_adjusted`,
`revenue`, `revenue_available`, `revenue_blocked`, `revenue_fees`,
`revenue_fees_taxes`, `revpar`, `revpar_adjusted_occupancy`,
`revpar_adjusted_occupancy_fees`, `revpar_fees`.

**Forward-only metrics** (window `0_N` only): `occupancy_neighborhood`,
`occupancy_neighborhood_pp`, `occupancy_neighborhood_ratio`,
`occupancy_neighborhood_adjusted`, `occupancy_neighborhood_adjusted_pp`,
`occupancy_neighborhood_adjusted_ratio`, `revenue_score`.

**Backward-only metrics** (window `N_0` only): `pickup`, `pickup_bookings`.

Asking for a window a metric is not computed for returns a 400.

Monetary metrics — the `adr`, `asking_rate`, `revenue` and `revpar` families —
are stored in the currency of the listing's market, falling back to the
listing's own currency when it has no market, and each row reports which in its
`currency`. For a portfolio spanning currencies, pass `currency` to convert
every value before ranking, so that the ordering is meaningful. Without it,
rows are ranked on unconverted numbers. `currency` is ignored for metrics that
are not amounts of money.

A listing with no value for the requested window sorts last whichever direction
you rank in, with `value` set to null, so a ranking never opens with blanks.
Listings for which no stats have been generated at all are absent. Values are
recomputed by the nightly stats pipeline and when a listing's calendar is
refreshed; `updated_at` on each row tells you how current it is.

Comp-set metrics (`comp_set_occupancy` and friends) are not available here yet.

**Same time last year.** Pass `basis=stly` to rank on each listing's values as
they stood at the same time last year: the same window, measured 52 weeks
earlier, so `0_30` is the 30 days that followed the same day last year. Rows have
the same shape and currency handling as `basis=current`. Last year's values
cover every metric above except `min_price_occurrence`, `revenue_blocked`,
`revenue_score` and the `occupancy_neighborhood` metrics, which return a 400.
Listings with no stats for last year are absent from the ranking. `basis=stly`
ranks rolling windows only and returns a 400 with `period`. `basis=stly` is in
early access; accounts without early access get a 403.

## Request

`GET https://api.usewheelhouse.com/ss_api/v1/listings/kpis`

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 |
| --- | --- | --- | --- |
| `metric` | string | yes | The KPI to return. See the metric lists above. (example: `occupancy_adjusted`) |
| `window` | string | no | Rolling window to return. `0_30` is the next 30 days, `30_0` the trailing 30. Required unless `period` is given. (one of: `0_7`, `0_14`, `0_21`, `0_30`, `0_60`, `0_90`, `0_180`, `0_365`, `7_0`, `14_0`, `21_0`, `30_0`, `60_0`, `90_0`, `180_0`, `365_0`, example: `0_30`) |
| `period` | string | no | Rank on a calendar month, quarter or year instead of a rolling window. Requires `period_start`; cannot be combined with `window`. (one of: `monthly`, `quarterly`, `yearly`) |
| `period_start` | string (date) | no | First day of the period to rank on, e.g. `2026-07-01` for July 2026 or the third quarter of 2026. Required with `period`. (example: `2026-07-01`) |
| `compare` | string | no | With `period`, also return the same period one year earlier (its final figure) as `compare_value`, with `change` and `change_ratio`. (one of: `previous_year`) |
| `rank_by` | string | no | What to rank on. `change` and `change_ratio` need `compare`. `sort` sets the direction, and a listing with no value to rank on sorts last either way. (one of: `value`, `change`, `change_ratio`, default: `value`) |
| `basis` | string | no | Rank on today's values (`current`) or on the values as they stood at the same time last year (`stly`). See the description above for the metrics `stly` does not cover. `stly` works with `window` only; for a period, use `compare=previous_year`. `stly` is in early access. (one of: `current`, `stly`, default: `current`) |
| `sort` | string | no | Rank highest value first (`desc`) or lowest first (`asc`). (one of: `desc`, `asc`, default: `desc`) |
| `currency` | string | no | ISO-4217 code to convert monetary values to before ranking. Recommended for portfolios spanning more than one currency. Ignored for metrics that are not amounts of money. (example: `USD`) |
| `exclude_inactive` | boolean | no | Exclude inactive listings, and listings not linked to a channel, from the ranking. Hidden listings are not inactive and are still ranked; read `is_hidden` from `GET /listings` to leave them out. (default: `true`) |
| `include_managed_listings` | boolean | no | When true (default), includes listings the user manages for another Wheelhouse account, in addition to listings they own. Set to false to rank only owned listings. (default: `true`) |
| `owner_user_id` | integer | no | Rank only the listings owned by this Wheelhouse user, matching `owner_user.id` on [`GET /listings`](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md). Pass a membership's `user_id` from [`GET /teams/memberships`](https://docs.usewheelhouse.com/rm/reference/rm-get-team-memberships.md) to rank one team's portfolio. It narrows the listings you can already access and grants no others, so a user whose listings you cannot access returns an empty list. |
| `page` | integer | no | Page of the ranking to return. (default: `1`) |
| `per_page` | integer | no | Rows per page (max 100). (default: `50`, max: 100) |

### Example request

```bash
curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/listings/kpis?metric=<metric>' \
  -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

One row per listing, ranked by the requested metric.

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

- `listing_id` (integer, example: `84521`): Wheelhouse's own listing id.
- `partner_listing_id` (string, nullable, example: `12345`): The channel's unique listing identifier, as accepted by the single-listing endpoints. Always the channel's ID; the Wheelhouse listing ID is the `listing_id` field above.
- `value` (number, nullable, example: `0.82`): The metric's value for the requested window. Null when the listing has no value for it.
- `currency` (string, nullable, example: `USD`): ISO-4217 currency the value is expressed in — the requested `currency` when one was given, otherwise the market's currency the value is stored in. Null for metrics that are not amounts of money.
- `updated_at` (string (date-time), nullable): When this metric was last recomputed for the listing. Null when ranking by `period`.
- `compare_value` (number, nullable, example: `0.74`): Only with `compare`. The same metric for the same period one year earlier, in the same currency as `value`. Null when the listing has no value for that period.
- `change` (number, nullable, example: `0.08`): Only with `compare`. `value - compare_value`. Null when either is null.
- `change_ratio` (number, nullable, example: `1.108`): Only with `compare`. `value / compare_value`, so `1.1` is ten percent up. Null when either is null or `compare_value` is zero.

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

```json
[
  {
    "listing_id": 84521,
    "partner_listing_id": "12345",
    "value": 0.82,
    "currency": "USD",
    "updated_at": "2026-01-01T00:00:00Z",
    "compare_value": 0.74,
    "change": 0.08,
    "change_ratio": 1.108
  }
]
```

### 400

Missing or unknown metric, window or period; both or neither of `window` and `period`; a window the metric is not computed for; a metric not available by period; a `period_start` that is not the first day of the period; `compare` or `rank_by` used incorrectly; with `basis=stly`, a metric not available for last year; or `basis=stly` with `period`.

### 401

API key authorization failed.

### 403

`basis=stly` was requested by an account without early access to it.

### 422

No exchange rate is available for the requested currency.
