Get room rates

POST /v1/rates/rooms · MCP tool: get_room_rates

Read available supplier-specific room offers, terms, and stay totals for one hotel and itinerary. One room call ($0.06 after signup credits). Room equivalence across providers is not assumed. More pages of the same quote session are free.

Run this tool on HotelUse · Download full captured response

Rooms and rate plans

Pass one HotelUse ID and an itinerary. Multi-room searches preserve each room’s adult count and child ages. Expedia, Booking, Agoda and Brek support multi-room search and room quotes. Booking detailed quotes and Agoda quotes validate each distinct room allocation, shared provider room inventory and the full-party total. They combine the same provider room type across rooms, then use GIATA to group equivalent types across providers. Agoda also confirms the amount against its native whole-party quote. Original child ages are preserved. Unknown stock or failed occupancy branches produce partial coverage, never a single-room price labeled as a full-party total. Combined offers expose room_allocations[] with each room’s guests, full-stay price and cancellation terms; aggregate cancellation amounts must not be inferred from one room. Unsupported room setups are reported explicitly, never as sold out. HotelUse performs GIATA room-type mapping on the server, using the hotel GIATA ID and unique provider room descriptions. The response includes grouped data.room_groups[] and the original data.offers[] across providers. Different rate plans for one room remain separate offers: breakfast, payment timing, occupancy and cancellation can differ.

Use room_groups[].provider_prices[] for each provider's lowest returned rate in that room family; offer_ids links back to complete plans and terms. shared_room_group_id and room_mapping_source: "giata" identify matched families. The group identity is quote-scoped, not a persistent inventory ID. You do not need to perform room matching yourself. Unmatched offers remain grouped by provider/source room ID, with no cross-provider equivalence claimed. data.room_grouping reports mapped coverage or mapping failure. GIATA failure does not discard valid prices. Optional room_groups[].images[] contains up to eight sourced room photos, with URL, source provider/room ID and match method. Photos come from an exact provider room ID or a GIATA-confirmed room family; hotel-level photos are not substituted for missing room photos. Original offers retain room_images[] when available.

Room groups and provider minimum prices cover the full quoted session, so cheaper offers from one provider cannot hide other providers behind transport pages. Raw offers[] are paginated; follow the free quote pages for all rate-plan details. Only offers with confirmed mandatory taxes and fees are eligible as comparable group/provider minima. If none is eligible, the minimum is null and provider status is incomplete_price. All original offers remain available. For example, Booking can return an incalculable mandatory city tax in its excluded charges. That offer has unconfirmed_mandatory_fees and is not eligible as an all-in minimum. A Japanese accommodation tax may still be payable at the hotel when the provider does not itemize it; an absent fee amount is not zero. Different currencies and incompatible price scopes remain separate. For the same GIATA family, requested_stay and all_requested_rooms both cover the full requested party and form one group with canonical price_scope requested_stay. Original offers retain their source scope; per-room prices are not merged with whole-party prices. A missing source room name can appear as Room <external_room_id>; the provider room ID remains the reliable key. returned_offer_count is the total normalized offer count in the session, not the current page size.

Provider	Lowest-rate maximum rooms	Room-detail maximum rooms
expedia	8	8
booking	8	8
agoda	8	8
brek	8	8

Unsupported operations return an explicit provider status; they do not reuse a single-room price. Agoda requests up to 100 supplier rates; do not describe that response as every possible Agoda offer.

Filters & sorting: complete field reference

Request fields

Field	Required	Type	Details
`hotel_id`	Required	string	See request and field notes below
`context`	Required	object	Stay dates, occupancy, currency and residency
`rate_filters`	Optional	object	See request and field notes below
`providers`	Optional	array	See request and field notes below
`page_size`	Optional	integer	1–200
`billing`	Optional	object	Maximum new units authorized for this call

rate_filters

Field	Type	Meaning
`refundable_only`	boolean	Require known refundable terms; unknown terms do not qualify.
`breakfast_included`	boolean	Require an offer explicitly marked breakfast included.
`stay_total_min`	number	Minimum full-stay amount in context.currency for all requested rooms, including mandatory taxes and fees. Not a nightly price.
`stay_total_max`	number	Maximum full-stay amount in context.currency for all requested rooms, including mandatory taxes and fees. Applies to each returned offer before minima.

context requires either explicit hotel-local check_in and check_out, or date_intent: "tonight" without explicit dates, plus rooms (1–8), each with adults (1–8) and children_ages (ages 0–17). Stays are 1–60 calendar nights. Same-day check-in is allowed using the destination or hotel local date, even when UTC is already tomorrow. The server resolves an IANA time zone from destination coordinates or hotel metadata before rejecting past dates. Traveler context.time_zone never overrides the property calendar. date_intent: "tonight" resolves one local night on the server; use the returned explicit dates in follow-ups. data.date_context reports the time zone, local date and resolution timestamp. currency defaults to USD and market.residency_country to US over HTTP; MCP can fill omitted preferences from client metadata (see the MCP guide); set both explicitly for your traveler.

rate_filters supports refundable_only, breakfast_included, stay_total_min and stay_total_max. Budgets are whole-stay totals for all requested rooms in the requested currency, including mandatory fees. Complete filter guide. It filters returned offers before choosing provider/hotel minima, and cannot recover plans omitted by supplier caps. Hotels and provider rows without a qualifying offer have no comparable quote; unknown refundability never passes refundable_only. providers restricts providers; enabled status is available at capabilities.

Request example

The captured request uses 2026-11-12 to 2026-11-14, 2 adults, 1 room, USD. Replace dates with your own future dates for a new rate call. Use a fresh Idempotency-Key per intended operation; keep it for retries.

bash

curl 'https://www.hoteluse.dev/v1/rates/rooms' \
  -H "Authorization: Bearer $HOTELUSE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: replace-with-a-unique-operation-id' \
  --data '{
  "hotel_id": "hu_69450c903d9c06226f1ce17b",
  "context": {
    "check_in": "2026-11-12",
    "check_out": "2026-11-14",
    "rooms": [
      {
        "adults": 2,
        "children_ages": []
      }
    ],
    "currency": "USD",
    "market": {
      "residency_country": "US"
    }
  },
  "page_size": 200
}'

Captured response

Captured 2026-10-21 17:50:47 UTC. The preview below is abridged for reading: arrays and static records can be shortened or selected. The downloadable JSON preserves the full captured transport page. Only request/session/billing identifiers and cursors are redacted. Historical sessions cannot be resumed.

json

{
  "schema_version": "1.0",
  "request_id": "req_documentation_capture",
  "data": {
    "context": {
      "check_in": "2026-11-12",
      "check_out": "2026-11-14",
      "rooms": [
        {
          "adults": 2,
          "children_ages": []
        }
      ],
      "currency": "USD",
      "market": {
        "residency_country": "US"
      }
    },
    "quote_session_id": "qs_documentation_capture_expired",
    "provider_results": [
      {
        "provider": "expedia",
        "status": "complete",
        "upstream_requests": 1,
        "completed_requests": 1,
        "failed_requests": 0
      },
      {
        "provider": "booking",
        "status": "complete",
        "upstream_requests": 1,
        "completed_requests": 1,
        "failed_requests": 0
      },
      {
        "provider": "agoda",
        "status": "complete",
        "upstream_requests": 1,
        "completed_requests": 1,
        "failed_requests": 0,
        "max_offers_returned": 100
      },
      {
        "provider": "brek",
        "status": "complete",
        "upstream_requests": 3,
        "completed_requests": 3,
        "failed_requests": 0
      }
    ],
    "upstream_requests": 6,
    "hotel_id": "hu_69450c903d9c06226f1ce17b",
    "hotel": {
      "hotel_id": "hu_69450c903d9c06226f1ce17b",
      "name": "Hilton Bellevue",
      "city": "Bellevue (WA)",
      "country": "US",
      "star_rating": 4,
      "geo": {
        "longitude": -122.18915,
        "latitude": 47.60723
      },
      "property_type": "hotel"
    },
    "returned_offer_count": 242,
    "offers": [
      {
        "offer_id": "offer_e2c92fbd284a6b1746df16ec5b42",
        "provider": "brek",
        "hotel_id": "hu_69450c903d9c06226f1ce17b",
        "shared_room_group_id": null,
        "currency": "USD",
        "room_name": "ROOM, KING BED, SOFA",
        "external_room_id": "1252232395",
        "room_components": [
          {
            "room_id": "1252232395",
            "name": "ROOM, KING BED, SOFA",
            "occupancy_reference": 1
          }
        ],
        "meal_plan": null,
        "supplier_board_code": "0",
        "cancellation": {
          "refundable": false,
          "free_cancellation_until": null,
          "summary": null,
          "penalties": [
            {
              "deadline": "2026-10-19T05:00:00.000Z",
              "type": "IMPORT",
              "value": 241.0681,
              "currency": "USD"
            }
          ]
        },
        "inventory_source": "118",
        "price_breakdown": {
          "inventory_total": "241.07",
          "inventory_room_total": "207.54",
          "included_taxes_and_fees": "33.52",
          "markup_basis": "inventory_room_total",
          "rounding": "per_night",
          "rounding_adjustment": "-0.01",
          "markup_rate": "0.07",
          "markup_amount": "14.52",
          "pay_at_property": "0.00"
        },
        "stay_total": {
          "amount": "255.58",
          "currency": "USD"
        },
        "price": {
          "base": "222.06",
          "taxes_and_fees": "33.52",
          "pay_at_property": "0.00",
          "stay_total": "255.58",
          "currency": "USD"
        },
        "taxes_and_mandatory_fees_included": true,
        "checked_at": "2026-10-21T17:50:47.489Z"
      },
      {
        "offer_id": "offer_396036e4df6c526dc296a81ff817",
        "provider": "expedia",
        "hotel_id": "hu_69450c903d9c06226f1ce17b",
        "shared_room_group_id": null,
        "currency": "USD",
        "room_name": "Room, 1 King Bed with Sofa bed, Balcony - No-Refunds",
        "external_room_id": "192500",
        "meal_plan": "room_only",
        "cancellation": {
          "refundable": false,
          "free_cancellation_until": null,
          "summary": "This reservation is non-refundable and cannot be cancelled or changed.Stay extensions require a new reservation.",
          "penalties": [
            {
              "deadline": "2026-10-21T17:50:47.000Z",
              "type": "percent",
              "value": "100",
              "currency": null
            }
          ]
        },
        "stay_total": {
          "amount": "489.44",
          "currency": "USD"
        },
        "price": {
          "base": "423.10",
          "taxes_and_fees": "66.34",
          "pay_at_property": "0.00",
          "stay_total": "489.44",
          "currency": "USD"
        },
        "taxes_and_mandatory_fees_included": true,
        "checked_at": "2026-10-21T17:50:47.319Z"
      },
      {
        "offer_id": "offer_55fdb1d090cafbad490177f281c9",
        "provider": "booking",
        "hotel_id": "hu_69450c903d9c06226f1ce17b",
        "shared_room_group_id": null,
        "currency": "USD",
        "room_name": "Room 18067302",
        "external_room_id": "18067302",
        "meal_plan": "no_plan",
        "cancellation": {
          "refundable": false,
          "free_cancellation_until": null,
          "summary": null,
          "penalties": [
            {
              "deadline": "2026-10-21T17:50:47.377Z",
              "type": "amount",
              "value": 423.1,
              "currency": "USD"
            }
          ]
        },
        "conditional_charges": [],
        "price_scope": "requested_room",
        "stay_total": {
          "amount": "489.45",
          "currency": "USD"
        },
        "price": {
          "base": "423.10",
          "taxes_and_fees": "66.35",
          "pay_at_property": null,
          "stay_total": "489.45",
          "currency": "USD"
        },
        "taxes_and_mandatory_fees_included": true,
        "checked_at": "2026-10-21T17:50:47.377Z",
        "maximum_occupancy": {
          "adults": 2,
          "children": null,
          "total": 2
        },
        "available_rooms_at_price": 9,
        "payment_policy": {
          "prepayment_required": true,
          "timings": [
            "pay_online_now"
          ]
        }
      },
      {
        "offer_id": "offer_32a8de813c2d9951dfb57f87e22e",
        "provider": "booking",
        "hotel_id": "hu_69450c903d9c06226f1ce17b",
        "shared_room_group_id": null,
        "currency": "USD",
        "room_name": "Room 18067308",
        "external_room_id": "18067308",
        "meal_plan": "no_plan",
        "cancellation": {
          "refundable": false,
          "free_cancellation_until": null,
          "summary": null,
          "penalties": [
            {
              "deadline": "2026-10-21T17:50:47.377Z",
              "type": "amount",
              "value": 433.22,
              "currency": "USD"
            }
          ]
        },
        "conditional_charges": [],
        "price_scope": "requested_room",
        "stay_total": {
          "amount": "501.04",
          "currency": "USD"
        },
        "price": {
          "base": "433.22",
          "taxes_and_fees": "67.82",
          "pay_at_property": null,
          "stay_total": "501.04",
          "currency": "USD"
        },
        "taxes_and_mandatory_fees_included": true,
        "checked_at": "2026-10-21T17:50:47.377Z",
        "maximum_occupancy": {
          "adults": 2,
          "children": null,
          "total": 2
        },
        "available_rooms_at_price": 9,
        "payment_policy": {
          "prepayment_required": true,
          "timings": [
            "pay_online_now"
          ]
        }
      },
      {
        "offer_id": "offer_e13afa920e1d7dcebc6f9af63e4d",
        "provider": "agoda",
        "hotel_id": "hu_69450c903d9c06226f1ce17b",
        "shared_room_group_id": null,
        "currency": "USD",
        "room_name": "1 KING BED with SOFA SLEEPER",
        "external_room_id": "3530703",
        "meal_plan": "room_only",
        "cancellation": {
          "refundable": false,
          "free_cancellation_until": null,
          "summary": "This booking is Non-Refundable and cannot be amended or modified. Failure to arrive at your hotel or property will be treated as a No-Show and will incur a charge of 100% of the booking value (Hotel policy).",
          "penalties": [
            {
              "deadline": null,
              "deadline_local": "2026-10-21T00:00:00",
              "until": null,
              "until_local": null,
              "type": "amount",
              "value": 489.45,
              "currency": "USD",
              "time_basis": "hotel_local"
            }
          ],
          "free_cancellation_until_local": null,
          "time_basis": "hotel_local",
          "timezone": "America/Los_Angeles",
          "provider_policy": {
            "code": "365D100P_100P",
            "parameters": [
              {
                "days": 365,
                "charge": "P",
                "value": 100
              }
            ]
          }
        },
        "room_type_guaranteed": true,
        "stay_total": {
          "amount": "489.45",
          "currency": "USD"
        },
        "price": {
          "base": "423.10",
          "taxes_and_fees": "66.35",
          "pay_at_property": "0.00",
          "stay_total": "489.45",
          "currency": "USD"
        },
        "taxes_and_mandatory_fees_included": true,
        "checked_at": "2026-10-21T17:50:47.343Z"
      }
    ],
    "next_cursor": "example_expired_cursor",
    "reuse_until": "2026-10-21T18:00:47.763Z"
  },
  "usage": {
    "hotel_record_units": 0,
    "search_calls": 0,
    "room_calls": 1,
    "trial_units_used": 1,
    "paid_units": 0,
    "paid_usd": "0.000",
    "unit_price_usd": "0.060",
    "billing_receipt_id": "bill_documentation_capture",
    "replayed": false
  }
}

Field	Meaning
`schema_version`	Current response schema, `1.0`.
`request_id`	Include this value when reporting an issue.
`data.provider_results`	Provider execution status, completed/failed request counts, and errors.
`data.next_cursor`	Non-null means another page is available. A small page does not mean complete coverage.
`usage`	Actual units, signup units used, paid units and USD charged for this response.

Booking links

Available Expedia, Booking and Agoda offers include an optional booking_url with HotelUse affiliate tracking by default, for both HTTP and developer MCP. Room-group provider minima include the matching lowest offer’s link. Supplier dates, occupancy, device and room/rate parameters are preserved. Links are omitted when no safe supplier URL is available. A booking may earn HotelUse a commission; booking and payment happen at the provider. Links do not change API usage billing.

Real room types and prices

Selected room minima from the captured session, 2026-11-12 to 2026-11-14, 2 adults, 1 room, USD. These are provider-specific room IDs; rows do not assert that rooms match across providers.

Provider	Room ID	Room name	Meal plan	Lowest stay total
brek	`1252232395`	ROOM, KING BED, SOFA	null	$255.58
brek	`1442250655`	ROOM, 2 QUEEN BEDS, SOFA	null	$255.58
expedia	`192500`	Room, 1 King Bed with Sofa bed, Balcony - No-Refunds	room_only	$489.44
booking	`18067302`	Room 18067302	no_plan	$489.45
booking	`18067308`	Room 18067308	no_plan	$501.04
booking	`18067320`	Room 18067320	no_plan	$628.59
booking	`18067314`	Room 18067314	no_plan	$727.98
agoda	`3530703`	1 KING BED with SOFA SLEEPER	room_only	$489.45
agoda	`3530871`	2 Queen Beds With Sofa Sleeper	room_only	$501.04

The capture contains 242 offers. Download all normalized offers. The first transport page and its original returned_offer_count are in the full response JSON.

Read an offer correctly

Field	Meaning
`offer_id`	This provider-specific room/rate/occupancy option.
`external_room_id`	Provider room identifier. One room can have multiple offers.
`stay_total`	Amount and currency for the whole requested stay, using the reported price scope.
`price_scope`	When present, use it to interpret the requested occupancy; Booking single-room offers use requested_room.
`price.pay_at_property`	Included amount due at the hotel when known. Null means unknown, not zero.
`taxes_and_mandatory_fees_included`	Only true confirms that mandatory fees are included. Unknown-fee offers are not eligible for lowest-price comparison.
`currency_conversion`	When present, the source currency, fresh FX rate, premium and expiry. Converted totals are display estimates. Brek uses its 1% FX premium only on prepaid amounts.
`mandatory_fees`	Original local-currency hotel fees and their display amounts. These are already included in stay_total; do not add them again. Local fees have no room markup or FX premium.
`cancellation`	Refundability and penalty schedule. Local deadlines include time_basis, timezone and local fields. Do not convert a hotel-local date to UTC without its timezone.
`maximum_occupancy`	Supplier adult/child/total capacity where available.
`payment_policy`	Payment timing and prepayment requirements where provided.

Pagination

For the next page, POST to this same endpoint with only the returned quote_session_id and cursor. Quote-session pages are account-bound, use no additional search or room units, and expire after 10 minutes. They reuse the original prices.

json

{
  "quote_session_id": "qs_from_your_live_response",
  "cursor": "cursor_from_your_live_response"
}

Pricing and limits · Errors and retries.