# Get monthly stats for a listing.

`GET /listings/{listing_id}/kpis/monthly`

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

Returns per-month performance stats, ordered oldest-to-newest. Includes comp-set metrics.

**Covers both past and future months** — up to 15 months back and forward through the month
containing the maximum calendar horizon (1.5 years from today), subject to the months
Wheelhouse holds data for. That last month includes only the nights up to the horizon, so
its nights and revenue cover part of the month. Months from the current one onward are
forward-looking: they reflect the bookings on the books so far plus asking rates for nights
that are still open, so they are not final and will change as bookings come in. Compare a
month's `month` value against today's date to tell which side of the line it falls on.

**Same time last year.** Pass `basis=stly` to get each month as it stood at the same
time last year. The row under a `month` holds that month a year earlier, as it stood
52 weeks ago, so a month that was still ahead then counts only the bookings on the books
at the time. Rows sit under the current `month` they compare with, so the two bases can
be joined on `month`. `revenue_blocked` and the `comp_set_*` fields are `null`. Months
with no stats for last year are absent. `basis=stly` is in early access; accounts without early access get a 403.

All monetary values are in the listing's `currency`.

## Request

`GET https://api.usewheelhouse.com/ss_api/v1/listings/{listing_id}/kpis/monthly`

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.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `listing_id` | string | yes | The channel's unique listing identifier, or the Wheelhouse listing ID when `channel` is `wheelhouse`. |

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `channel` | string | yes | Channel name the listing is on (the `channel` field of the [/listings](https://docs.usewheelhouse.com/rm/reference/rm-get-listings.md) response), or the literal `wheelhouse` to read `listing_id` as a Wheelhouse listing ID instead. See [Identifying Listings](https://docs.usewheelhouse.com/rm/concepts/listings.md). |
| `basis` | string | no | Return today's values (`current`) or the values as they stood at the same time last year (`stly`). See the description above for what `stly` returns. (one of: `current`, `stly`, default: `current`) |

### Example request

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

Monthly KPIs.

Body (`application/json`): object

- `currency` (string, example: `USD`): ISO-4217 currency code for all monetary values in this response.
- `data` (array of object `listing_stats_monthly_response`): Past and future months, ordered oldest-to-newest.
  - Each item: Performance stats for a single calendar month. The month may be in the past or in the future; future months are forward-looking (bookings on the books plus asking rates for open nights) rather than settled results.
  - `month` (string (date)): First day of the month these stats cover (ISO-8601 date). Compare against today's date to tell whether the month is complete, in progress, or still ahead.
  - `adr` (number, nullable): Average daily rate (average nightly rate of booked stays).
  - `adr_fees` (number, nullable): Average daily rate including fees.
  - `asking_rate` (number, nullable): Asking Rate (Booked + Available Nights): average nightly price across booked and available nights, excluding fees. A booked night counts at the rate it was booked for, an available night at its current price. Blocked nights are left out. `null` when no night qualifies. See `asking_rate_available` for available nights only.
  - `asking_rate_available` (number, nullable): Asking Rate (Available Nights): sum of nightly prices on available nights / number of available nights, excluding fees. Booked and blocked nights, and nights without a price, count in neither. `null`, not `0`, when no available night has a price.
  - `asking_rate_highest` (number, nullable): Asking Rate (Highest): highest nightly asking price on any night in the period, whether open, booked or blocked. `null` when no night has a price.
  - `asking_rate_lowest` (number, nullable): Asking Rate (Lowest): lowest nightly asking price on any night in the period, whether open, booked or blocked. `null` when no night has a price.
  - `bookings` (integer, nullable): Bookings: reservations with at least one night in the period. `null`, not `0`, when no reservation overlaps the period.
  - `lead_time` (number, nullable): Average days between booking and check-in.
  - `los` (number, nullable): Average length of stay in nights.
  - `nights_available` (number, nullable): Currently unbooked, bookable nights.
  - `nights_blocked` (number, nullable): Owner-blocked nights preventing bookings.
  - `nights_bookable` (number, nullable): Bookable nights (available plus booked, excluding blocked).
  - `nights_booked` (number, nullable): Currently reserved nights.
  - `nights_calendar` (number, nullable): Nights (Calendar): nights in the period, irrespective of listing status. For a listing with several units, counts the nights of each currently active unit.
  - `nights_percent_open` (number, nullable): Nights (Bookable %): bookable nights as a share of calendar nights.
  - `occupancy` (number, nullable): Occupancy rate (booked nights / calendar nights).
  - `occupancy_adjusted` (number, nullable): Open occupancy rate (booked nights / bookable nights).
  - `revenue` (number, nullable): Total revenue (rent only).
  - `revenue_available` (number, nullable): Potential earnings from currently available nights at current asking rates.
  - `revenue_blocked` (number, nullable): Unrealized revenue from blocked nights at current asking rates.
  - `revenue_fees` (number, nullable): Revenue including fees (rent plus fees) for booked nights.
  - `revenue_fees_taxes` (number, nullable): Revenue including fees and taxes for booked nights.
  - `revpar` (number, nullable): Revenue per available room night.
  - `revpar_fees` (number, nullable): RevPAR including fees.
  - `revpar_adjusted_occupancy_fees` (number, nullable): RevPAR including fees, excluding blocked nights.
  - `revpar_adjusted_occupancy` (number, nullable): RevPAR excluding blocked nights.
  - `comp_set_adr` (number, nullable): Comp-set average daily rate.
  - `comp_set_lead_time` (number, nullable): Comp-set average booking lead time.
  - `comp_set_occupancy` (number, nullable): Comp-set occupancy rate.
  - `comp_set_occupancy_adjusted` (number, nullable): Comp-set open occupancy rate.
  - `comp_set_revpar` (number, nullable): Comp-set RevPAR.
  - `comp_set_revenue` (number, nullable): Comp-set average revenue per unit.
  - `comp_set_revpar_adjusted_occupancy` (number, nullable): Comp-set RevPAR excluding blocked nights.
  - `comp_set_los` (number, nullable): Comp-set average length of stay.

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

```json
{
  "currency": "USD",
  "data": [
    {
      "month": "2026-01-01",
      "adr": 0,
      "adr_fees": 0,
      "asking_rate": 0,
      "asking_rate_available": 0,
      "asking_rate_highest": 0,
      "asking_rate_lowest": 0,
      "bookings": 0,
      "lead_time": 0,
      "los": 0,
      "nights_available": 0,
      "nights_blocked": 0,
      "nights_bookable": 0,
      "nights_booked": 0,
      "nights_calendar": 0,
      "nights_percent_open": 0,
      "occupancy": 0,
      "occupancy_adjusted": 0,
      "revenue": 0,
      "revenue_available": 0,
      "revenue_blocked": 0,
      "revenue_fees": 0,
      "revenue_fees_taxes": 0,
      "revpar": 0,
      "revpar_fees": 0,
      "revpar_adjusted_occupancy_fees": 0,
      "revpar_adjusted_occupancy": 0,
      "comp_set_adr": 0,
      "comp_set_lead_time": 0,
      "comp_set_occupancy": 0,
      "comp_set_occupancy_adjusted": 0,
      "comp_set_revpar": 0,
      "comp_set_revenue": 0,
      "comp_set_revpar_adjusted_occupancy": 0,
      "comp_set_los": 0
    }
  ]
}
```

### 401

API key authorization failed.

### 403

Listing authorization failed, or `basis=stly` was requested by an account without early access to it.

### 404

Listing not found.

### 406

The listing is inactive. See the **Inactive Listings** section in the overview.

Body (`application/json`): object

- `error` (string, example: `Listing '12345' is inactive`)

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

```json
{
  "error": "Listing '12345' is inactive"
}
```

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