---
name: "calendar_list_bookings"
area: "calendar"
title: "List bookings"
price: "free"
method: "POST"
url: "https://api.conecto.chat/v1/tools/calendar_list_bookings"
mcp_server: "https://api.conecto.chat/mcp/calendar"
auth: "Authorization: Bearer <conecto_sk_ key>"
docs_url: "https://conecto.chat/tools/calendar/calendar_list_bookings"
---

# List bookings (`calendar_list_bookings`)

Bookings between two times (from now on by default), soonest first, with each one's hosts, guests and confirmation call.

Bookings between two times (default: from now on), soonest first, with each one's hosts, guests and confirmation call. person lists the meetings that person has.

Price: Free up to 1,000,000 reads a month for the whole account, then $0.50 per 10,000 reads. A call that fails costs nothing.

## Use it when

Someone asks who is coming, or a booking's reference is needed to move or cancel it.

## Say this to your agent

> Who is coming in for a fitting this week?

## Inputs

| Name | Type | Required | Description | Allowed values | Default |
|---|---|---|---|---|---|
| `from` | string (date-time) | no |  |  |  |
| `to` | string (date-time) | no |  |  |  |
| `status` | string | no |  | `"scheduled"`, `"cancelled"`, `"any"` | `"scheduled"` |
| `meeting_type` | string | no |  |  |  |
| `person` | string | no | Someone on the account, by email: their own calendar instead of the business's. Up to 254 characters. |  |  |
| `limit` | integer | no | 1 to 200. |  | `50` |

## Example

Written for Halverson Cycle & Repair, a bike shop with a repair workshop in Portland, Oregon.

MCP: call `calendar_list_bookings` on the MCP server `https://api.conecto.chat/mcp/calendar` with these arguments:

```json
{
  "from": "2026-10-19T00:00:00-07:00",
  "to": "2026-10-24T23:59:00-07:00"
}
```

REST:

```bash
curl https://api.conecto.chat/v1/tools/calendar_list_bookings \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from": "2026-10-19T00:00:00-07:00", "to": "2026-10-24T23:59:00-07:00"}'
```

## Response

```json
{
  "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93",
  "tool": "calendar_list_bookings",
  "status": "succeeded",
  "replayed": false,
  "cost_usd": "$0.00",
  "balance_usd": "$19.75",
  "result": {
    "bookings": [
      {
        "booking_id": "ec535d25-fba9-435c-9f24-e9099c967ab3",
        "reference": "KP8GGN56KJ",
        "status": "scheduled",
        "meeting_type": "bike-fitting",
        "title": "Bike fitting",
        "start": "2026-10-24T18:30:00+00:00",
        "end": "2026-10-24T19:15:00+00:00",
        "attendee_local_time": "Saturday, October 24, 2026 at 11:30 (America/Los Angeles)",
        "attendee": {
          "name": "Rachel Kim",
          "email": "rachel.kim@example.com",
          "phone": null,
          "timezone": "America/Los_Angeles"
        },
        "hosts": [],
        "guests": [],
        "answers": {},
        "location": "Halverson Cycle & Repair, 1830 SE Ash St, Portland, OR 97214",
        "booked_via": "bot",
        "manage_url": "https://cncto.co/booking/ec535d25-fba9-435c-9f24-e9099c967ab3?t=ImVjNTM1ZDI1LWZiYTktNDM1Yy05ZjI0LWU5MDk5Yzk2N2FiMyI:1xJYro:NJLXW-h5yu5BRPp5j7vMCKzVNJzX35k_CUqFS8vilLo",
        "confirmation_call": null,
        "cancel_reason": null
      }
    ],
    "count": 1
  }
}
```

`result`: Up to 200 bookings, soonest first, each with its reference, times, attendee, hosts, guests, answers, location, manage link and confirmation call, and how many were listed.

## Errors

| Code | Status | When | Fix |
|---|---|---|---|
| `invalid_input` | 400 | A time is not ISO 8601 with its offset, or a time zone is unknown. | Send times like 2026-10-24T11:00:00-07:00 and zones like America/Los_Angeles. |

The refusals every tool can give (401 key, 402 balance, 429 limits) are on the errors page: https://conecto.chat/docs/errors.md

## Related

- [calendar_setup](https://conecto.chat/tools/calendar/calendar_setup.md): Sets the business's calendar or a person's own: name, booking address, time zone, weekly hours, closed days, reminder emails and confirmation calls. $0.001 a call.
- [calendar_get_setup](https://conecto.chat/tools/calendar/calendar_get_setup.md): The calendar's settings, booking page, iCal link, connected Google calendar, meeting types, and its people's own calendars. Free up to 1,000,000 reads a month.
- [calendar_connect](https://conecto.chat/tools/calendar/calendar_connect.md): A link that opens a page naming the business, where the owner, or a person for their own page, connects Google Calendar in one click. Free up to 1,000,000 reads a month.
- [calendar_save_meeting_type](https://conecto.chat/tools/calendar/calendar_save_meeting_type.md): Creates or changes a kind of meeting people can book, on the business's calendar or a person's, taken by one host, a round robin or everyone. $0.001 a call.
- [calendar_list_meeting_types](https://conecto.chat/tools/calendar/calendar_list_meeting_types.md): Every meeting type people can book, the business's and each person's own, with its hosts and booking page. Free up to 1,000,000 reads a month.
- [calendar_find_times](https://conecto.chat/tools/calendar/calendar_find_times.md): Free start times for a meeting type between two dates, in the time zone you ask for. Free up to 1,000,000 reads a month.
- [calendar_book](https://conecto.chat/tools/calendar/calendar_book.md): Books a free time for someone, who gets a confirmation email with an invite and a link to change it. $0.01 a call.
- [calendar_move](https://conecto.chat/tools/calendar/calendar_move.md): Moves a booking to another free time and sends the attendee an updated invite. $0.01 a call.
- [calendar_cancel](https://conecto.chat/tools/calendar/calendar_cancel.md): Cancels a booking and tells the attendee by email, unless notify is false. $0.01 a call.
- [calendar_save_routing_form](https://conecto.chat/tools/calendar/calendar_save_routing_form.md): Creates or changes a routing form that asks visitors a few questions and sends each to the right meeting type, host, site or message. $0.001 a call.
- [calendar_list_routing_forms](https://conecto.chat/tools/calendar/calendar_list_routing_forms.md): The routing forms with their addresses, questions, routes and how many people answered each. Free up to 1,000,000 reads a month.
- [calendar_list_routing_responses](https://conecto.chat/tools/calendar/calendar_list_routing_responses.md): What people answered on the routing forms, newest first, where each was sent, and the booking it led to. Free up to 1,000,000 reads a month.