List and filter bookings

The GET /booking/ endpoint returns your bookings wrapped in the standard response envelope. Use query parameters to narrow results with filters, control the ordering, and page through large result sets. All requests require a bearer token:

Authorization: Bearer calid_xxxxx

Filter

Combine filter parameters to return only the bookings you need. Available filters include status, teamId, eventTypeIds, attendeeEmail, attendeeName, and bookingUid, plus date-range filters for start, creation, and update times: afterStartDate, beforeEndDate, afterCreatedDate, beforeCreatedDate, afterUpdatedDate, and beforeUpdatedDate. The example below returns upcoming bookings for a specific attendee that start within a date range. GET /booking/ has no accepted bucket — the valid values are upcoming, past, cancelled, unconfirmed, and recurring:

curl -G "https://api.cal.id/booking/" \
  -H "Authorization: Bearer calid_xxxxx" \
  --data-urlencode "status=upcoming" \
  --data-urlencode "attendeeEmail=jane@example.com" \
  --data-urlencode "afterStartDate=2026-07-01T00:00:00Z" \
  --data-urlencode "beforeEndDate=2026-07-31T23:59:59Z"

async function filterBookings() {
  const params = new URLSearchParams({
    status: "upcoming",
    attendeeEmail: "jane@example.com",
    afterStartDate: "2026-07-01T00:00:00Z",
    beforeEndDate: "2026-07-31T23:59:59Z",
  });

  const res = await fetch(`https://api.cal.id/booking/?${params}`, {
    headers: { Authorization: `Bearer ${process.env.CALID_KEY}` },
  });

  const body = await res.json();
  if (!res.ok) throw new Error(body.message ?? `HTTP ${res.status}`);
  return body.data;
}

filterBookings().then((bookings) => console.log(bookings.length));

import os
import requests

CALID_KEY = os.environ["CALID_KEY"]

response = requests.get(
    "https://api.cal.id/booking/",
    headers={"Authorization": f"Bearer {CALID_KEY}"},
    params={
        "status": "upcoming",
        "attendeeEmail": "jane@example.com",
        "afterStartDate": "2026-07-01T00:00:00Z",
        "beforeEndDate": "2026-07-31T23:59:59Z",
    },
)
response.raise_for_status()

print(len(response.json()["data"]))

Sort

Order results with sortStart, sortEnd, sortCreated, or sortUpdated. Each accepts asc or desc. This request lists the most recently created bookings first:

curl -G "https://api.cal.id/booking/" \
  -H "Authorization: Bearer calid_xxxxx" \
  --data-urlencode "sortCreated=desc"

async function newestFirst() {
  const params = new URLSearchParams({ sortCreated: "desc" });

  const res = await fetch(`https://api.cal.id/booking/?${params}`, {
    headers: { Authorization: `Bearer ${process.env.CALID_KEY}` },
  });

  const body = await res.json();
  if (!res.ok) throw new Error(body.message ?? `HTTP ${res.status}`);
  return body.data;
}

newestFirst().then((bookings) => console.log(bookings[0]));

import os
import requests

CALID_KEY = os.environ["CALID_KEY"]

response = requests.get(
    "https://api.cal.id/booking/",
    headers={"Authorization": f"Bearer {CALID_KEY}"},
    params={"sortCreated": "desc"},
)
response.raise_for_status()

bookings = response.json()["data"]
print(bookings[0] if bookings else "No bookings")

Paginate

Use page and limit to page through results. page selects the page number and limit sets the number of bookings per page:

curl -G "https://api.cal.id/booking/" \
  -H "Authorization: Bearer calid_xxxxx" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"

async function getPage() {
  const params = new URLSearchParams({ page: "1", limit: "20" });

  const res = await fetch(`https://api.cal.id/booking/?${params}`, {
    headers: { Authorization: `Bearer ${process.env.CALID_KEY}` },
  });

  const body = await res.json();
  if (!res.ok) throw new Error(body.message ?? `HTTP ${res.status}`);

  // Paging state lives in meta.pagination.
  return { bookings: body.data, pagination: body.meta.pagination };
}

getPage().then(({ bookings, pagination }) =>
  console.log(`${bookings.length} of ${pagination.total}`, pagination)
);

import os
import requests

CALID_KEY = os.environ["CALID_KEY"]

response = requests.get(
    "https://api.cal.id/booking/",
    headers={"Authorization": f"Bearer {CALID_KEY}"},
    params={"page": 1, "limit": 20},
)
response.raise_for_status()

body = response.json()
bookings = body["data"]
# Paging state lives in meta.pagination.
pagination = body["meta"]["pagination"]
print(f"{len(bookings)} of {pagination['total']}", pagination)

Every response includes a meta.pagination object describing the current page and total result set:

{
  "page": 1,
  "limit": 20,
  "total": 134,
  "totalPages": 7
}

To retrieve all bookings, request page=1, then keep incrementing page and refetching until page === totalPages. Once the current page equals totalPages, you have reached the last page and can stop.

This loop does not return every booking. GET /booking/ defaults to status=upcoming and there is no all value, so a caller who omits status pages cleanly to the end of a set that excludes everything already in the past. To sweep the whole history, run the loop once per bucket: upcoming, past, cancelled, unconfirmed, recurring.

Reference

For the complete list of parameters and response fields, see the full List bookings endpoint.

Get started

Guides

List and filter bookings

Filter

Sort

Paginate

Reference

​Filter

​Sort

​Paginate

​Reference

Filter

Sort

Paginate

Reference