## List events

`GET /v1/calendar-events`

Returns calendar events for a fixed period around the current date: from one month back to three months ahead.

## Parameters

| Parameter | Type | Req. | Default | Description |
|----------|-----|:-----:|-----------|---------|
| `type` (query) | string | yes | — | Calendar type: `user`, `group`, `company_calendar` |
| `ownerId` (query) | number | yes | — | Calendar owner ID: employee (`GET /v1/users`) or workgroup |
| `limit` (query) | number | no | `50` | Number of records (up to 5000). When `limit > 50`, Vibecode automatically requests multiple pages from Bitrix24 |
| `offset` (query) | number | no | `0` | Skip N records. When `offset > 0`, `limit ≤ 500` is recommended |

## Examples

### curl — personal key

```bash
curl "https://vibecode.bitrix24.com/v1/calendar-events?type=user&ownerId=1&limit=10" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl "https://vibecode.bitrix24.com/v1/calendar-events?type=user&ownerId=1&limit=10" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — personal key

```javascript
const params = new URLSearchParams({ type: 'user', ownerId: '1', limit: '10' })
const res = await fetch(`https://vibecode.bitrix24.com/v1/calendar-events?${params}`, {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
console.log(`Found ${meta.total} events`)
```

### JavaScript — OAuth application

```javascript
const params = new URLSearchParams({ type: 'user', ownerId: '1', limit: '10' })
const res = await fetch(`https://vibecode.bitrix24.com/v1/calendar-events?${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 events (all fields — see [Event fields](./fields.md)) |
| `meta.total` | number | Total number of events in the selection |
| `meta.hasMore` | boolean | Whether there are more records beyond `limit` |

The card URL of any event from the `data` array depends on the calendar type:

| `type` | URL |
|---|---|
| `user` | `https://<portal>.bitrix24.com/company/personal/user/<ownerId>/calendar/?EVENT_ID=<id>&EVENT_DATE=<dd.mm.yyyy>` |
| `group` | `https://<portal>.bitrix24.com/workgroups/group/<ownerId>/calendar/?EVENT_ID=<id>&EVENT_DATE=<dd.mm.yyyy>` |
| `company_calendar` | `https://<portal>.bitrix24.com/calendar/?EVENT_ID=<id>&EVENT_DATE=<dd.mm.yyyy>` |

`<dd.mm.yyyy>` — the event start date (the `from` field) in "day.month.year" format separated by dots. `<portal>` — your Bitrix24 account domain. Access is limited by the employee's permissions in Bitrix24.

## Response example

```json
{
  "success": true,
  "data": [
    {
      "id": 7773,
      "parentId": 7773,
      "active": true,
      "deleted": false,
      "type": "user",
      "ownerId": 1,
      "name": "Team call",
      "from": "2026-06-10T10:00:00+00:00",
      "to": "2026-06-10T11:00:00+00:00",
      "skipTime": false,
      "durationSeconds": 3600,
      "createdBy": 1,
      "dateCreate": "06/05/2026 09:12:00 am",
      "updatedAt": "06/05/2026 09:12:00 am",
      "description": "Weekly sync",
      "accessibility": "busy",
      "importance": "normal",
      "isMeeting": false,
      "meetingStatus": "H",
      "meetingHost": 1,
      "sectionId": 3,
      "attendeeList": [
        { "id": 1, "entryId": "7773", "status": "H" }
      ]
    }
  ],
  "meta": {
    "total": 1,
    "hasMore": false
  }
}
```

## Error response example

400 — required `type` and `ownerId` were not passed:

```json
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_PARAMS",
    "message": "GET /v1/calendar-events requires query parameters: type, ownerId. Example: GET /v1/calendar-events?type=...&ownerId=..."
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `MISSING_REQUIRED_PARAMS` | `type` and/or `ownerId` were not passed |
| 403 | `SCOPE_DENIED` | The API key does not have the `calendar` scope |
| 401 | `TOKEN_MISSING` | The API key has no configured tokens |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

**Auto-pagination.** When `limit > 50`, Vibecode automatically requests multiple pages from Bitrix24 and assembles them into a single response. If the total number of events is greater than `limit`, `meta.hasMore` will be `true`.

**Recurring events.** An event with the `rrule` field is returned in the list as a separate item for each occurrence of the series that falls within the selection window. All items share a common `id` and `parentId`, differing only in `from` / `to`.

## See also

- [Create event](./create.md)
- [Get event](./get.md)
- [Event fields](./fields.md)