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
ParameterdateFrom (query) Typestring | number Requiredyes* Default— DescriptionStart of the interval. ISO 8601 ("2026-05-01T00:00:00Z") or Unix seconds (1714521600)
ParameterdateTo (query) Typestring | number Requiredyes* Default— DescriptionEnd of the interval. ISO 8601 or Unix seconds
Parameterlimit (query) Typenumber Requiredno Default50 DescriptionNumber of records (from 1 to 5000). A negative value or zero → 400 INVALID_PARAMS
Parameteroffset (query) Typenumber Requiredno Default0 DescriptionOffset. Use with caution — see "Known specifics"
Parameterfilter (query) Typeobject Requiredno Default— DescriptionBracket spelling of the interval: filter[dateFrom] and filter[dateTo]. These are the only two keys this method carries to Bitrix24; any other key is refused with 400 UNSUPPORTED_FILTER rather than silently ignored. The flat dateFrom / dateTo win over the envelope keys of the same name. Pass the filter in a single form: bracket notation and a string are mutually destructive spellings, and mixing them returns 400 INVALID_FILTER. An empty ?filter= still means "no filter"

* The interval is mandatory, but the spelling is your choice: the flat dateFrom / dateTo or the envelope keys filter[dateFrom] / filter[dateTo]. Its absence from both spellings is 400 MISSING_REQUIRED_PARAMS.

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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of bookings (each record's fields — see Bookings)
Fieldmeta.total Typenumber DescriptionAlways 0 — the total count is not computed. To determine whether there are more records, use meta.hasMore
Fieldmeta.hasMore Typeboolean Descriptiontrue if the number of records matching the filter exceeds limit

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "datePeriod": {
        "from": "2024-08-12T07:15:00+00:00",
        "to": "2024-08-12T07:30:00+00:00"
      },
      "description": null,
      "id": 3,
      "name": null,
      "resourceIds": [1, 3]
    },
    {
      "datePeriod": {
        "from": "2025-03-11T10:00:00+00:00",
        "to": "2025-03-11T11:00:00+00:00"
      },
      "description": null,
      "id": 1,
      "name": "Booking",
      "resourceIds": [1]
    },
    {
      "datePeriod": {
        "from": "2025-07-15T09:00:00+00:00",
        "to": "2025-07-15T09:30:00+00:00"
      },
      "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
HTTP400 CodeMISSING_REQUIRED_PARAMS DescriptiondateFrom or dateTo not passed
HTTP400 CodeINVALID_DATE DescriptionThe dateFrom or dateTo value is not ISO 8601 or Unix seconds
HTTP400 CodeINVALID_PARAMS Descriptionlimit is less than 1 or is not a number
HTTP400 CodeUNSUPPORTED_FILTER Descriptionfilter carried a key other than dateFrom and dateTo, or filter arrived as something other than an object (a string, a JSON object or an array). The request is refused before the Bitrix24 call: such a condition used to be lost in silence and the answer covered the whole interval
HTTP400 CodeINVALID_FILTER DescriptionA condition spelled in filter did not survive query-string parsing: both forms were mixed, one name was spelled at two different nesting levels (?filter[dateFrom]=…&filter[dateFrom][from]=…), or the nesting is deeper than two levels. The whole request is refused — half-applying a filter would answer 200 with records you did not ask for
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the booking scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not passed
HTTP401 CodeTOKEN_MISSING DescriptionThe 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