## 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

```bash
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

```bash
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](/docs/entities/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](/docs/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

- [Search bookings](/docs/entities/bookings/search)
- [Get a booking](/docs/entities/bookings/get)
- [Create a booking](/docs/entities/bookings/create)
- [Filtering syntax](/docs/filtering)
- [Batch](/docs/batch)
- [Limits and optimization](/docs/optimization)