# List lobby bookings

`GET /lobbyBooking.list`

## Description

Lists bookings for a specific lobby configuration, filtered by date range (after/before).

The ordering of results depends on `ascending` and `after`:

- `ascending=true` sorts in forward chronological order (oldest first).
  `ascending=false` sorts in reverse chronological order (newest first),
  even when `after` is specified.

- When `ascending` is omitted and `after` is not specified, the most recent
  bookings are returned in reverse chronological order. This is equivalent
  to specifying `before` as NOW and leaving `after` unspecified.

- When `ascending` is omitted and `after` is specified, the results are
  sorted in forward chronological order.

Send the same `ascending` value on every page. The cursor marks where to
resume, not which direction to sort.

Either dates or datetimes may be specified. Dates are interpreted in UTC.

**Access:** Organization only.

**Required scope:** `lobby:read`

---

**OpenAPI Spec:** [chat.json](https://developer.ro.am/chat.json)

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `lobbyId` | query | string | Yes | The lobby configuration ID to list bookings for. |
| `after` | query | string | No | The datetime to begin listing bookings (YYYY-MM-DD or RFC-3339). Defaults to "no filter".  |
| `before` | query | string | No | The datetime until which to list bookings (YYYY-MM-DD or RFC-3339). Defaults to "now".  |
| `ascending` | query | boolean | No | `true` sorts oldest-first. `false` sorts newest-first, even when `after` is set. When omitted, results are oldest-first if `after` is set and newest-first otherwise. Send the same value on every page; |
| `limit` | query | integer | No | The number of bookings to return per response. Default is 10. |
| `cursor` | query | string | No | Opaque pagination cursor from a previous response's `nextCursor`. Do not construct cursors manually. |

## Responses

### 200 - OK

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `bookings` | LobbyBooking[] | No |  |
| `nextCursor` | string | No | Returned if there is a subsequent page of bookings. |

**LobbyBooking** (array item):

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | string | Yes | Unique booking identifier |
| `start` | string | Yes | Start time in RFC3339 |
| `end` | string | Yes | End time in RFC3339 |
| `status` | string | Yes | Current status of the booking |
| `timeZone` | string | No | IANA time zone of the booking times |
| `notes` | string | No | Optional notes provided by the booker |
| `created` | string | No | Creation time |
| `hosts` | LobbyBookingHost[] | No |  |
| `invitees` | LobbyBookingInvitee[] | No |  |
| `responses` | LobbyBookingResponse[] | No | The guest's answers to the lobby's custom questions, including hidden fields populated from URL query parameters on the lobby link. One entry per answered question; empty or absent when the guest answ |
| `meetingLink` | string | No | Meeting link URL, used to join the meeting |

**LobbyBookingHost** (array item):

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `name` | string | No | Display name of the host |
| `email` | string | Yes | Email address of the host |
| `isOrganizer` | boolean | Yes | Whether this host is the organizer |

**LobbyBookingInvitee** (array item):

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `name` | string | No | Display name of the invitee |
| `email` | string | Yes | Email address of the invitee |
| `status` | string | Yes | Invitee's RSVP or booking status |
| `isBooker` | boolean | No | Whether this invitee created the booking |

**LobbyBookingResponse** (array item):

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `fieldId` | string | Yes | ID of the custom field (question) this answer belongs to. |
| `key` | string | No | The field's stable key, if the lobby owner assigned one, as captured when the booking was made. For hidden fields this is the URL query parameter name used to populate the value.  |
| `question` | string | No | The question's display name. Omitted if the field definition can no longer be found on the lobby configuration.  |
| `type` | "short_text" | "text" | "email" | "phone_number" | "radio" | "checkbox" | "dropdown" | "hidden" | No | The custom field type. Omitted when `question` is omitted. |
| `value` | object | No | The human-readable answer. For option fields (radio, checkbox, dropdown) this is the selected option label(s), not internal option IDs. Checkbox answers are arrays of strings; all other answers are st |


#### Example Response

```json
{
  "bookings": [
    {
      "id": "018f3f37-eca3-7d07-8a12-9e65a8a0c1b9",
      "start": "2025-08-03T14:10:54Z",
      "end": "2025-08-03T14:40:54Z",
      "status": "active",
      "timeZone": "America/Los_Angeles",
      "notes": "Intro call",
      "created": "2025-08-01T10:00:00Z",
      "hosts": [
        {
          "name": "Alex Doe",
          "email": "alex@example.com",
          "isOrganizer": true
        }
      ],
      "invitees": [
        {
          "name": "Sam Smith",
          "email": "sam@example.com",
          "status": "invited",
          "isBooker": true
        }
      ],
      "responses": [
        {
          "fieldId": "018f3f36-1111-7aaa-8000-9e65a8a0c1b9",
          "key": "utm_source",
          "question": "UTM Source",
          "type": "hidden",
          "value": "partner"
        },
        {
          "fieldId": "018f3f36-2222-7bbb-8000-9e65a8a0c1b9",
          "question": "What would you like to discuss?",
          "type": "text",
          "value": "Pricing for 50 seats"
        },
        {
          "fieldId": "018f3f36-3333-7ccc-8000-9e65a8a0c1b9",
          "question": "Products of interest",
          "type": "checkbox",
          "value": [
            "Widgets",
            "Gadgets"
          ]
        }
      ]
    }
  ],
  "nextCursor": "YzE6MDE4ZjNmMzktMmI1Yy03YjNkLTlmOTYtOGIyZjFjMGUxMjM0"
}
```

### 400 - Bad request, including an unparseable `ascending` value (`code` is `invalid_parameter`).

### 401 - Presented invalid authentication credentials.

### 404 - Lobby not found.

### 405 - An unsupported method was requested.

### 500 - An internal error occured.

---

*Machine-readable API documentation.*
*Full documentation: https://developer.ro.am/docs/chat-api/lobby-booking-list*