# List reservations

> Returns the tables, appointments and requests your agent took, newest start first — the same object every `reservation.*` webhook carries.

Source: https://www.hey.support/docs/api/reservations/list-reservations

---

<ApiEndpoint method="GET" path="/reservations" />

Window on the start time with `from`/`to` (a day’s service, a week’s load), poll on `since` (creation time), and name the statuses you want with `status`; holds and blocked time are returned only when named. Read-only: reservations are made by visitors or by the team from the calendar.

## Query parameters

<TypeTable
  type={{
  "chatbot_id": { type: "string", description: "Sqid-encoded chatbot id. Scopes results to one chatbot.", required: false },
  "status": { type: "string", description: "Comma-separated statuses. Defaults to every status except `held` and `blocked`. One of: held, requested, confirmed, arrived, completed, no_show, cancelled, declined, blocked.", required: false },
  "from": { type: "string (date-time)", description: "Reservations starting at or after this instant.", required: false },
  "to": { type: "string (date-time)", description: "Reservations starting before this instant.", required: false },
  "since": { type: "string (date-time)", description: "", required: false },
  "limit": { type: "integer", description: "", required: false },
  "offset": { type: "integer", description: "", required: false }
}}
/>

## Response `200`

Returns a `data` array with a `pagination` object. Each item:

<TypeTable
  type={{
  "id": { type: "string (uuid)", description: "Reservation UUID (not sqid-encoded)", required: true },
  "chatbot_id": { type: "string", description: "", required: true },
  "conversation_id": { type: "string", description: "", required: false },
  "customer_id": { type: "integer", description: "The workspace-level guest record the reservation belongs to — the same person across every agent in the workspace.", required: false },
  "status": { type: "\"held\" | \"requested\" | \"confirmed\" | \"arrived\" | \"completed\" | \"no_show\" | \"cancelled\" | \"declined\" | \"blocked\"", description: "", required: true },
  "service_id": { type: "integer", description: "The service, as listed by `/reservation-services`. Null once the service has been deleted; `service_name` keeps the name.", required: false },
  "service_name": { type: "string", description: "", required: false },
  "resource_id": { type: "integer", description: "The staff member or area, null when none was assigned.", required: false },
  "resource_name": { type: "string", description: "", required: false },
  "start_at": { type: "string (date-time)", description: "", required: true },
  "end_at": { type: "string (date-time)", description: "", required: true },
  "party_size": { type: "integer", description: "", required: true },
  "name": { type: "string", description: "", required: false },
  "email": { type: "string (email)", description: "", required: false },
  "phone": { type: "string", description: "", required: false },
  "answers": { type: "object", description: "The guest’s answers to the service’s questions, keyed by question id.", required: false },
  "notes": { type: "string", description: "What the guest wrote when booking.", required: false },
  "source": { type: "\"agent\" | \"card\" | \"manual\" | \"manage\" | \"api\" | \"channel\"", description: "How it was made: in chat, on the widget card, by the team, from the guest’s manage link, or on a messaging channel.", required: true },
  "channel": { type: "string", description: "", required: false },
  "language": { type: "string", description: "", required: false },
  "attendee_timezone": { type: "string", description: "", required: false },
  "cancel_reason": { type: "string", description: "", required: false },
  "cancelled_by": { type: "string", description: "Who cancelled: customer, staff or system.", required: false },
  "decline_reason": { type: "string", description: "", required: false },
  "reschedule_count": { type: "integer", description: "", required: false },
  "created_at": { type: "string (date-time)", description: "", required: true },
  "updated_at": { type: "string (date-time)", description: "", required: true }
}}
/>

### Errors

* `400` — Unknown status or an invalid window
* `401` — Missing or invalid API key
* `404` — Chatbot not found
* `429` — Rate limit exceeded

Every error shares [one envelope](/docs/api/errors).

## Example

```bash
curl https://www.hey.support/api/v1/reservations \
  -H 'Authorization: Bearer hs_live_…'
```