Skip to main content

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​

One row per listing, ranked by the requested metric.