# Get aggregated metrics for a segment.

`GET /segments/{segment_id}/aggregated_metrics`

> Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-get-segment-aggregated-metrics · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmGetSegmentAggregatedMetrics` · Tag: Segments

Returns monthly performance metrics aggregated across the listings matched by the segment's filter. For an RM API key the filter is evaluated against listings shared with the user to manage as well as listings they own (see `include_managed_listings`). Monetary values are converted to the requested currency. Because a segment has no currency of its own, the default is the currency of the most common market among the segment's listings (falling back to USD).

## Request

`GET https://api.usewheelhouse.com/ss_api/v1/segments/{segment_id}/aggregated_metrics`

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 |
| --- | --- | --- | --- |
| `segment_id` | integer | yes | The Wheelhouse internal segment ID. |

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `currency` | string | no | ISO-4217 3-letter currency code to convert monetary metrics to. Defaults to the currency of the most common market among the segment's listings. |
| `dates` | array of string (date) | no | Restrict the response to periods starting on these dates (first of month, YYYY-MM-DD). Send more than one in brackets (`?dates[]=2026-05-01&dates[]=2026-06-01`); a key repeated without brackets keeps only its last value. Defaults to all available periods. |
| `include_managed_listings` | boolean | no | When true (default for RM API keys), the segment's filter is evaluated against listings the user manages for another Wheelhouse account (valid shared-access grants) as well as listings they own. Set to false to match only owned listings. Channel integration keys default to false, since they act on the one account they connected. (default: `true`) |

### Example request

```bash
curl -X GET 'https://api.usewheelhouse.com/ss_api/v1/segments/{segment_id}/aggregated_metrics' \
  -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

Aggregated metrics per period.

Body (`application/json`): object

- `data` (array of object `segment_aggregated_metric_response`)
  - Each item: Performance metrics for one month, aggregated across the listings matched by a portfolio segment's filter. Metric names follow the [Wheelhouse metrics definitions](https://www.usewheelhouse.com/research-metrics). Values derive from calendar prices and exclude fees and taxes. Monetary values are converted to the response `currency` and rounded to whole units; ratios are expressed as fractions (0–1).
  - `start_date` (string (date)): First day of the period (YYYY-MM-DD).
  - `end_date` (string (date)): Last day of the period (YYYY-MM-DD).
  - `occupancy` (number, nullable): Booked nights as a share of all calendar nights (`nights_booked / nights_calendar`).
  - `occupancy_adjusted` (number, nullable): Booked nights as a share of bookable nights, excluding blocked inventory (`nights_booked / nights_bookable`).
  - `nights_percent_open` (number, nullable): Share of calendar nights that are bookable (`nights_bookable / nights_calendar`), as a fraction.
  - `revenue` (number, nullable): Sum of rental prices for booked nights, excluding fees and taxes.
  - `adr` (number, nullable): Average Daily Rate — average price per booked night, excluding fees (`revenue / nights_booked`).
  - `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.
  - `revpar` (number, nullable): Revenue per available night, excluding fees (Average Daily Rate × Occupancy).
  - `revpar_adjusted` (number, nullable): Revenue per bookable night using adjusted occupancy, excluding fees and blocked inventory.
  - `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.
  - `lead_time` (number, nullable): Days between booking date and stay start date (median across the segment's listings).
  - `length_of_stay` (number, nullable): Nights per reservation (median across the segment's listings).
  - `nights_available` (number, nullable): Currently unbooked, bookable nights.
  - `nights_blocked` (number, nullable): Owner-blocked nights preventing bookings.
  - `nights_booked` (number, nullable): Currently reserved nights.
  - `nights_bookable` (number, nullable): Available plus booked nights, excluding blocked nights.
  - `nights_calendar` (integer, nullable): All nights in the period regardless of status.
  - `count_bookings` (integer, nullable): Total number of unique reservations.
- `currency` (string): The ISO-4217 3-letter currency code of the monetary metrics.

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

```json
{
  "data": [
    {
      "start_date": "2026-01-01",
      "end_date": "2026-01-01",
      "occupancy": 0,
      "occupancy_adjusted": 0,
      "nights_percent_open": 0,
      "revenue": 0,
      "adr": 0,
      "asking_rate": 0,
      "asking_rate_available": 0,
      "revpar": 0,
      "revpar_adjusted": 0,
      "revenue_available": 0,
      "revenue_blocked": 0,
      "lead_time": 0,
      "length_of_stay": 0,
      "nights_available": 0,
      "nights_blocked": 0,
      "nights_booked": 0,
      "nights_bookable": 0,
      "nights_calendar": 0,
      "count_bookings": 0
    }
  ],
  "currency": "string"
}
```

### 401

API key authorization failed.

### 404

Segment not found.

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