> ## Documentation Index
> Fetch the complete documentation index at: https://code.dcycle.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Hotel Stay Tools

> MCP tools for querying hotel stay records and their carbon emissions (Scope 3)

# Hotel Stay Tools

Query hotel stay records — accommodation bookings with check-in/check-out dates, room counts, and associated CO₂e emissions. This is Scope 3 Category 6 (business travel) data.

## `list_hotel_stays`

List hotel stay records with optional filters.

**Parameters:**

| Parameter         | Type    | Required | Default     | Description                               |
| ----------------- | ------- | -------- | ----------- | ----------------------------------------- |
| `organization_id` | string  | No       | default org | Organization UUID                         |
| `status`          | string  | No       | —           | Status filter: `active`, `deleted`        |
| `start_date`      | string  | No       | —           | Filter stays from this date (YYYY-MM-DD)  |
| `end_date`        | string  | No       | —           | Filter stays until this date (YYYY-MM-DD) |
| `name`            | string  | No       | —           | Filter by hotel name (partial match)      |
| `page`            | integer | No       | 1           | Page number                               |
| `size`            | integer | No       | 50          | Results per page                          |

**Example response:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Team offsite — Madrid",
      "check_in_date": "2024-11-04",
      "check_out_date": "2024-11-07",
      "country": "ES",
      "address": "Gran Vía 28, Madrid, Spain",
      "hotel_name": "Hotel Gran Vía",
      "rooms": 3,
      "status": "active",
      "source": "manual",
      "co2e": 18.54,
      "file_id": null,
      "file_name": null,
      "created_at": "2024-11-01T09:00:00Z",
      "updated_at": "2024-11-01T09:00:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "size": 50,
  "pages": 1
}
```

**Key response fields:**

| Field                              | Description                                                      |
| ---------------------------------- | ---------------------------------------------------------------- |
| `name`                             | Description or label for the stay (e.g. "Team offsite — Madrid") |
| `hotel_name`                       | Name of the hotel                                                |
| `check_in_date` / `check_out_date` | Stay dates (number of nights = difference between these)         |
| `rooms`                            | Number of rooms booked                                           |
| `country`                          | ISO country code of the hotel location                           |
| `co2e`                             | Calculated CO₂e emissions in kg                                  |
| `source`                           | How the record was created: `manual`, `bulk_upload`, or `api`    |

**Example prompts:**

```
"List our hotel stays for Q1 2024"
"Show hotel stays at Marriott properties"
"How many hotel nights did we book last year?"
"What are the emissions from our hotel stays in 2025?"
```

## Workflow

1. **List hotel stays** — `list_hotel_stays` to query stays by date range or hotel name
2. **View travel emissions** — `get_greenhouse_gas_emissions` with `category=travels` for aggregated business travel totals
3. **Compare with flights** — `list_business_travels` to see flight/train records alongside hotel data

## Related

<CardGroup cols={2}>
  <Card title="API: List Hotel Stays" icon="code" href="/api-reference/hotel-stays/list">
    REST API equivalent with additional filters
  </Card>

  <Card title="Business Travels" icon="plane" href="/mcp/business-travels">
    Flight and train journey records
  </Card>

  <Card title="Emissions" icon="smog" href="/mcp/emissions">
    Aggregated Scope 3 travel emissions
  </Card>

  <Card title="CLI" icon="terminal" href="/cli/assets">
    Manage hotel stays from the command line
  </Card>
</CardGroup>