Watch a walkthrough: https://www.loom.com/share/124cf50c7d0744259ab402ddb70ef7bb
How to Use This
There are two ways to use Scoreboards:
Call the API directly. Send a
GETrequest to/listings/kpiswith your API key. See "How to request a scoreboard" below for the exact steps.Ask Claude. If you've connected Wheelhouse's MCP tools to Claude, just ask a question like "What are my top 5 listings by occupancy?" — Claude calls this endpoint for you and returns a ranked answer, no code required.
The rest of this article covers what the endpoint returns and how to work with it, for anyone calling it directly.
What the Scoreboards Endpoint Does
Previously, getting one stat across your whole portfolio meant calling GET /listings/{listing_id}/kpis once per listing, then comparing the results yourself. That's manageable for a handful of listings, but slow once you're managing 50, 500, or more.
Scoreboards does this in one call. You specify one metric and one time window, and the response includes every listing you have access to, with that metric's value for that window.
How to request a scoreboard
Decide which metric you want. See "Choosing a metric" below for the full list.
Decide which time window you want. See "Choosing a time window" below.
Send a
GETrequest to/listings/kpiswithmetricandwindowas query parameters, and your API key in theX-Integration-Api-Keyheader.
Example request:
GET /listings/kpis?metric=occupancy_adjusted&window=0_30 X-Integration-Api-Key: [your API key]
Read the response. It's an array with one object per listing — see "Understanding the response" below for the fields included.
Choosing a Metric
Pass the metric name as the metric query parameter (for example, metric=occupancy_adjusted). There are more than 30 available, grouped here by category:
Pricing:
adr,adr_fees,asking_rate,asking_rate_fees,asking_rate_highest,asking_rate_lowestBooking activity:
occupancy,occupancy_adjusted,nights_available,nights_blocked,nights_bookable,nights_booked,nights_calendar,nights_percent_open,bookings,lead_time,length_of_stay,last_booked_days,min_price_occurrenceRevenue:
revenue,revenue_available,revenue_blocked,revenue_fees,revenue_fees_taxes,revpar,revpar_fees,revpar_adjusted_occupancy,revpar_adjusted_occupancy_feesForward-only (only valid with a forward-looking window — see below):
occupancy_neighborhoodand its adjusted/percentile variants,revenue_scoreBackward-only (only valid with a trailing window):
pickup,pickup_bookings
Note: If you request a metric with a window it doesn't support (for example, pickup with a forward-looking window), the request returns a 400 error instead of a result.
Choosing a Time Window
Pass the time window as the window query parameter, using the format 0_N for a forward-looking window (the next N days) or N_0 for a trailing window (the last N days).
Supported values: 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: window=0_30 looks at the next 30 days. window=30_0 looks at the trailing 30 days.
Sorting and Filtering the Response
The endpoint supports ranking and pagination server-side, plus two listing filters — but no attribute-based filters like market or bedroom count.
sort—desc(highest first, default) orasc(lowest first)per_page(up to 100, default 50) andpage— for example,per_page=5&sort=descfor a top 5 listexclude_inactive— exclude inactive listings (defaulttrue)include_managed_listings— include listings you manage for another Wheelhouse account, not just ones you own (defaulttrue)
To filter to a specific market, bedroom count, tag, or anything else you track, match each row to your own listing data using listing_id, then filter on your end.
If you're using Wheelhouse's AI tools in Claude, you can skip this — just ask for what you want (for example, "What are my top 5 listings by occupancy?") and Claude will call this endpoint and handle the ranking and filtering for you.
Handling Multiple Currencies
Monetary metrics (adr, asking_rate, revenue, revpar, and their variants) are stored in the listing's market currency, falling back to the listing's own currency if it has no market. If your portfolio spans more than one currency, values can be converted to a single currency before ranking so you're comparing consistently.
To convert values to a single currency before ranking, pass currency with an ISO-4217 code (for example, currency=USD).
Understanding the Response
Each item in the response array includes:
listing_id— the Wheelhouse listing IDpartner_listing_id— your own listing ID, if setvalue— the metric's value for the requested windowcurrency— the currencyvalueis reported in (only meaningful for monetary metrics)updated_at— when this row was last calculated
Note: A listing with no data for the requested window still appears in the response, with value set to null, so it sorts to the bottom rather than disappearing. A listing with no stats generated at all is left out of the response entirely.
Values are recalculated on Wheelhouse's nightly stats refresh, and whenever a listing's calendar is refreshed — updated_at reflects the most recent of those.
Related Endpoint
This endpoint reads from the same underlying data as GET /listings/{listing_id}/kpis, so the two will always agree. Use GET /listings/{listing_id}/kpis when you want every metric and window for one listing. Use Scoreboards when you want one metric and window across your whole portfolio.