> ## Documentation Index > Fetch the complete documentation index at: https://docs.bookingshake.com/llms.txt > Use this file to discover all available pages before exploring further. # List bookings > Paginated listing of the venue bookings (dossiers), newest first by default. **Pagination**: cursor-based. Pass the `next_cursor` value of a response as the `cursor` parameter of the next request, until `next_cursor` is null. A page may contain fewer than `limit` items even when more data remains (internal scan bound on very large venues): always rely on `next_cursor`, never on the item count. **Filter combinations**: `date_from`/`date_to` (a booking matches when at least one of its events is inside the window) can only be combined with `status_id`. `created_from`/`created_to` can be combined with `status_id` OR `contact_id`. `status_id` and `contact_id` are mutually exclusive. ## OpenAPI ````yaml /api-reference/bookingshake-openapi.json get /bookings openapi: 3.0.3 info: title: BookingShake API description: >- The BookingShake API allows you to programmatically create and manage events, bookings, and related resources. Integrate BookingShake with your applications to automate event creation, retrieve booking sources, spaces, statuses, and custom fields. **Rate Limiting:** All endpoints are rate limited per API key. POST /events/create allows 10 requests per minute, while GET endpoints allow 60 requests per minute. Rate limit information is provided in response headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset). version: 1.0.0 contact: name: BookingShake Support email: support@bookingshake.com url: https://bookingshake.com servers: - url: https://api.bookingshake.io/api description: Production server security: - bearerAuth: [] tags: - name: Events description: Create and manage events and bookings - name: Resources description: Retrieve booking sources, spaces, and statuses - name: Fields description: Retrieve available custom and default fields - name: Invoices description: Retrieve issued invoices - name: Payments description: Retrieve payments - name: Contacts description: Retrieve contacts (people) - name: Products description: Retrieve the venue product catalog - name: Payment Methods description: Retrieve the venue payment method catalog paths: /bookings: get: tags: - Bookings summary: List bookings description: >- Paginated listing of the venue bookings (dossiers), newest first by default. **Pagination**: cursor-based. Pass the `next_cursor` value of a response as the `cursor` parameter of the next request, until `next_cursor` is null. A page may contain fewer than `limit` items even when more data remains (internal scan bound on very large venues): always rely on `next_cursor`, never on the item count. **Filter combinations**: `date_from`/`date_to` (a booking matches when at least one of its events is inside the window) can only be combined with `status_id`. `created_from`/`created_to` can be combined with `status_id` OR `contact_id`. `status_id` and `contact_id` are mutually exclusive. operationId: listBookings parameters: - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 25 description: Maximum bookings per page - name: cursor in: query schema: type: string description: Opaque pagination cursor from the previous page - name: date_from in: query schema: type: string format: date description: Window start (YYYY-MM-DD, inclusive). Requires date_to. - name: date_to in: query schema: type: string format: date description: Window end (YYYY-MM-DD, inclusive). Requires date_from. - name: created_from in: query schema: type: integer description: Bookings created at or after this Unix millisecond timestamp - name: created_to in: query schema: type: integer description: Bookings created at or before this Unix millisecond timestamp - name: status_id in: query schema: type: string description: Filter by status ID - name: contact_id in: query schema: type: string description: Filter by contact ID responses: '200': description: Paginated bookings headers: X-RateLimit-Limit: schema: type: integer description: Maximum requests allowed per minute X-RateLimit-Remaining: schema: type: integer description: Requests remaining in the current window X-RateLimit-Reset: schema: type: integer description: Unix timestamp when the rate limit resets content: application/json: schema: type: object properties: message: type: string example: success data: type: object properties: items: type: array items: $ref: '#/components/schemas/BookingResource' next_cursor: type: string nullable: true description: >- Cursor for the next page, null when the listing is exhausted '400': description: Invalid request (missing token, invalid parameter or cursor) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/RateLimitResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearerAuth: [] components: schemas: BookingResource: type: object description: >- A booking (dossier): the group of events created and managed together, with its contact, status and financial references. Custom fields defined for the venue with collection "requests" are added as additional custom_* properties (null when empty). properties: id: type: string description: >- Booking ID. Matches the booking_id exposed by payment.* and invoice.created webhooks. NOT guaranteed stable across the whole life of a booking: when a single-event booking gains a second event, a new group ID is generated and a booking.updated webhook delivers the payload under the new id. Individual event IDs (events[].id) never change and can be used to recognize the booking. example: bkg_7f3a1c9e public_id: type: string nullable: true description: Public identifier of the booking, shared by all its events example: nX4fQ2hB name: type: string nullable: true description: Booking title example: Acme annual seminar status_id: type: string nullable: true description: Status ID (resolve label/type with GET /status) source_id: type: string nullable: true description: Source ID (resolve with GET /sources) contact_id: type: string nullable: true description: Contact ID (GET /contacts/{id}) account_id: type: string nullable: true description: Company/account ID (GET /accounts/{id}) owner_ids: type: array items: type: string description: >- Internal user IDs of the booking owners (correlation only: there is no /users endpoint yet) created_at: type: integer nullable: true description: Creation timestamp (Unix milliseconds) example: 1756000000000 updated_at: type: integer nullable: true description: >- Last relevant modification timestamp (Unix milliseconds). Null for bookings never modified since the feature went live (no backfill). canceled_at: type: integer nullable: true description: >- Cancellation timestamp (Unix milliseconds). Non-null only when ALL events of the booking are cancelled. Not backfilled for bookings cancelled before the feature went live. comments: type: string nullable: true description: Booking-level comments quote_ids: type: array items: type: string description: IDs of issued quotes of the booking (oldest first) invoice_ids: type: array items: type: string description: IDs of issued invoices (GET /invoices/{id}), oldest first payment_ids: type: array items: type: string description: >- IDs of payments (GET /payments/{id}), oldest first. Deposits/pre-authorization holds excluded. events: type: array items: $ref: '#/components/schemas/BookingEvent' description: Events of the booking, sorted by date then start time ErrorResponse: type: object properties: message: type: string description: Error message describing what went wrong example: invalid token RateLimitResponse: type: object properties: message: type: string description: Error message example: Rate limit exceeded data: type: object properties: limit: type: integer description: Maximum requests allowed per window example: 10 window: type: string description: Time window duration example: 60 seconds remaining: type: integer description: Requests remaining (always 0 on rate limit error) example: 0 resetAt: type: string format: date-time description: ISO 8601 timestamp when the limit resets example: '2025-11-17T14:30:00.000Z' retryAfter: type: integer description: Seconds to wait before retrying example: 45 BookingEvent: type: object description: >- A single event (date/time slot) inside a booking. Custom fields defined for the venue with collection "reservations" are added as additional custom_* properties (null when empty). properties: id: type: string description: Event ID example: rsv_8fj2kQpL0aXc date: type: string nullable: true description: >- Event date (YYYY-MM-DD). Note: POST /events/create still accepts DD-MM-YYYY as input (legacy contract). example: '2026-09-10' start_time: type: string nullable: true description: Start time (HH:mm) example: '09:00' end_time: type: string nullable: true description: End time (HH:mm) example: '17:00' space_id: type: string nullable: true description: Space ID (resolve with GET /spaces) example: spc_Lp9Xt2Kj5mQw secondary_space_ids: type: array items: type: string description: Secondary space IDs event_type: type: string nullable: true description: Event type / occasion example: Corporate seminar pax: type: integer nullable: true description: Number of guests example: 40 comments: type: string nullable: true description: Event-level comments created_at: type: integer nullable: true description: Creation timestamp (Unix milliseconds) example: 1756000000000 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: >- Bearer authentication using your BookingShake API key. Retrieve your API key from Settings > Integrations in your BookingShake dashboard. ````