[{"data":1,"prerenderedAt":7},["ShallowReactive",2],{"docs-entities\u002Fbookings\u002Flist":3,"docs-tabs-entities\u002Fbookings\u002Flist":6},{"content":4,"lastmod":5},"\n## List bookings\n\n`GET \u002Fv1\u002Fbookings`\n\nReturns 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.\n\n## Parameters\n\n| Parameter | Type | Required | Default | Description |\n|----------|-----|:-----:|-----------|---------|\n| `dateFrom` (query) | string \\| number | yes* | — | Start of the interval. ISO 8601 (`\"2026-05-01T00:00:00Z\"`) or Unix seconds (`1714521600`) |\n| `dateTo` (query) | string \\| number | yes* | — | End of the interval. ISO 8601 or Unix seconds |\n| `limit` (query) | number | no | `50` | Number of records (from 1 to 5000). A negative value or zero → `400 INVALID_PARAMS` |\n| `offset` (query) | number | no | `0` | Offset. Use with caution — see \"Known specifics\" |\n| `filter` (query) | object | no | — | Bracket 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` \u002F `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\" |\n\n\\* The interval is mandatory, but the spelling is your choice: the flat `dateFrom` \u002F `dateTo` **or** the envelope keys `filter[dateFrom]` \u002F `filter[dateTo]`. Its absence from both spellings is `400 MISSING_REQUIRED_PARAMS`.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fbookings?dateFrom=2024-01-01T00:00:00Z&dateTo=2026-12-31T23:59:59Z&limit=10\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth application\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fbookings?dateFrom=2024-01-01T00:00:00Z&dateTo=2026-12-31T23:59:59Z&limit=10\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — personal key\n\n```javascript\nconst params = new URLSearchParams({\n  dateFrom: '2024-01-01T00:00:00Z',\n  dateTo: '2026-12-31T23:59:59Z',\n  limit: '10',\n})\n\nconst res = await fetch(`https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fbookings?${params}`, {\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\n\nconst { success, data, meta } = await res.json()\nconsole.log(`Received ${data.length} bookings, hasMore: ${meta.hasMore}`)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst params = new URLSearchParams({\n  dateFrom: '2024-01-01T00:00:00Z',\n  dateTo: '2026-12-31T23:59:59Z',\n  limit: '10',\n})\n\nconst res = await fetch(`https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fbookings?${params}`, {\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\n\nconst { success, data, meta } = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|---------|\n| `success` | boolean | Always `true` on success |\n| `data` | array | Array of bookings (each record's fields — see [Bookings](\u002Fdocs\u002Fentities\u002Fbookings)) |\n| `meta.total` | number | Always `0` — the total count is not computed. To determine whether there are more records, use `meta.hasMore` |\n| `meta.hasMore` | boolean | `true` if the number of records matching the filter exceeds `limit` |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"datePeriod\": {\n        \"from\": \"2024-08-12T07:15:00+00:00\",\n        \"to\": \"2024-08-12T07:30:00+00:00\"\n      },\n      \"description\": null,\n      \"id\": 3,\n      \"name\": null,\n      \"resourceIds\": [1, 3]\n    },\n    {\n      \"datePeriod\": {\n        \"from\": \"2025-03-11T10:00:00+00:00\",\n        \"to\": \"2025-03-11T11:00:00+00:00\"\n      },\n      \"description\": null,\n      \"id\": 1,\n      \"name\": \"Booking\",\n      \"resourceIds\": [1]\n    },\n    {\n      \"datePeriod\": {\n        \"from\": \"2025-07-15T09:00:00+00:00\",\n        \"to\": \"2025-07-15T09:30:00+00:00\"\n      },\n      \"description\": null,\n      \"id\": 5,\n      \"name\": null,\n      \"resourceIds\": [1]\n    }\n  ],\n  \"meta\": {\n    \"total\": 0,\n    \"hasMore\": true\n  }\n}\n```\n\n## Error response example\n\n400 — required parameters not passed:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"MISSING_REQUIRED_PARAMS\",\n    \"message\": \"GET \u002Fv1\u002Fbookings 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.\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 400 | `MISSING_REQUIRED_PARAMS` | `dateFrom` or `dateTo` not passed |\n| 400 | `INVALID_DATE` | The `dateFrom` or `dateTo` value is not ISO 8601 or Unix seconds |\n| 400 | `INVALID_PARAMS` | `limit` is less than 1 or is not a number |\n| 400 | `UNSUPPORTED_FILTER` | `filter` 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 |\n| 400 | `INVALID_FILTER` | A 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 |\n| 403 | `SCOPE_DENIED` | The API key does not have the `booking` scope |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not passed |\n| 401 | `TOKEN_MISSING` | The API key has no configured tokens |\n\nFull list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n**`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`.\n\n## See also\n\n- [Search bookings](\u002Fdocs\u002Fentities\u002Fbookings\u002Fsearch)\n- [Get a booking](\u002Fdocs\u002Fentities\u002Fbookings\u002Fget)\n- [Create a booking](\u002Fdocs\u002Fentities\u002Fbookings\u002Fcreate)\n- [Filtering syntax](\u002Fdocs\u002Ffiltering)\n- [Batch](\u002Fdocs\u002Fbatch)\n- [Limits and optimization](\u002Fdocs\u002Foptimization)\n","2026-10-16",{},1794739320026]