For AI agents: markdown of this page — /docs-content-en/entities/bookings/list.md documentation index — /llms.txt

List bookings

GET /v1/bookings

Returns bookings for the given date range. The start and end of the interval are required — without them the request returns an error. Records outside the passed interval are not included in the response.

Parameters

Parameter Type Required Default Description
dateFrom (query) string | number yes — Start of the interval. ISO 8601 ("2026-05-01T00:00:00Z") or Unix seconds (1714521600)
dateTo (query) string | number yes — End of the interval. ISO 8601 or Unix seconds
limit (query) number no 50 Number of records (from 1 to 5000). A negative value or zero → 400 INVALID_PARAMS
offset (query) number no 0 Offset. Use with caution — see "Known specifics"

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/bookings?dateFrom=2024-01-01T00:00:00Z&dateTo=2026-12-31T23:59:59Z&limit=10" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/bookings?dateFrom=2024-01-01T00:00:00Z&dateTo=2026-12-31T23:59:59Z&limit=10" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const params = new URLSearchParams({
  dateFrom: '2024-01-01T00:00:00Z',
  dateTo: '2026-12-31T23:59:59Z',
  limit: '10',
})

const res = await fetch(`https://vibecode.bitrix24.com/v1/bookings?${params}`, {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
console.log(`Received ${data.length} bookings, hasMore: ${meta.hasMore}`)

JavaScript — OAuth application

javascript 
const params = new URLSearchParams({
  dateFrom: '2024-01-01T00:00:00Z',
  dateTo: '2026-12-31T23:59:59Z',
  limit: '10',
})

const res = await fetch(`https://vibecode.bitrix24.com/v1/bookings?${params}`, {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data, meta } = await res.json()

Response fields

Field Type Description
success boolean Always true on success
data array Array of bookings (each record's fields — see Bookings)
meta.total number Always 0 — the total count is not computed. To determine whether there are more records, use meta.hasMore
meta.hasMore boolean true if the number of records matching the filter exceeds limit

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "datePeriod": {
        "from": {
          "timestamp": 1723446900,
          "timezone": "UTC"
        },
        "to": {
          "timestamp": 1723447800,
          "timezone": "UTC"
        }
      },
      "description": null,
      "id": 3,
      "name": null,
      "resourceIds": [1, 3]
    },
    {
      "datePeriod": {
        "from": {
          "timestamp": 1741687200,
          "timezone": "UTC"
        },
        "to": {
          "timestamp": 1741690800,
          "timezone": "UTC"
        }
      },
      "description": null,
      "id": 1,
      "name": "Booking",
      "resourceIds": [1]
    },
    {
      "datePeriod": {
        "from": {
          "timestamp": 1752570000,
          "timezone": "UTC"
        },
        "to": {
          "timestamp": 1752571800,
          "timezone": "UTC"
        }
      },
      "description": null,
      "id": 5,
      "name": null,
      "resourceIds": [1]
    }
  ],
  "meta": {
    "total": 0,
    "hasMore": true
  }
}

Error response example

400 — required parameters not passed:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_PARAMS",
    "message": "GET /v1/bookings requires dateFrom and dateTo query parameters (ISO 8601 datetime or Unix seconds). Example: ?dateFrom=2026-05-01T00:00:00Z&dateTo=2026-05-31T23:59:59Z."
  }
}

Errors

HTTP Code Description
400 MISSING_REQUIRED_PARAMS dateFrom or dateTo not passed
400 INVALID_DATE The dateFrom or dateTo value is not ISO 8601 or Unix seconds
400 INVALID_PARAMS limit is less than 1 or is not a number
403 SCOPE_DENIED The API key does not have the booking scope
401 MISSING_API_KEY The X-Api-Key header was not passed
401 TOKEN_MISSING The API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

offset works unreliably at small values. offset values smaller than the page size do not guarantee skipping records. For fetching bookings over a standard working period (day, week, month), all records fit in a single page with a sufficient limit — a single request with a large limit is preferable to a series of requests with a small offset.

See also