Rank every listing by one KPI.
GET/listings/kpis
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, 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,
/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
Responses
- 200
- 400
- 401
- 403
- 422
One row per listing, ranked by the requested metric.
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.
API key authorization failed.
basis=stly was requested by an account without early access to it.
No exchange rate is available for the requested currency.