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

Examples

curl — personal key

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

curl — OAuth application

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

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

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

The card URL for any event in the data array depends on the calendar type:

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

Related data

To retrieve related employees with the event list, pass the include parameter in the GET request:

GET /v1/calendar-events?type=user&ownerId=1&include=owner,host

Available include values — up to three names per request:

The employee card is the same as in the GET /v1/users/:id response. Since these relations load employee data, the API key needs the user scope in addition to calendar. Each employee is loaded once per response. The result is in the _included field of every data element:

{
  "success": true,
  "data": [
    {
      "id": 7773,
      "name": "Team call",
      "ownerId": 1,
      "meetingHost": 1,
      "_included": {
        "owner": { "id": 1, "name": "John", "lastName": "Brown", "email": "john.brown@example.com", "active": true },
        "host": { "id": 1, "name": "John", "lastName": "Brown", "email": "john.brown@example.com", "active": true }
      }
    }
  ],
  "meta": { "total": 1, "hasMore": false }
}

The main fields of the event and the employee are shown. For all card fields, see Employee fields. If the response holds more than 200 occurrences, relations are not loaded and meta carries includeSkipped: true — reduce limit.

Response example

{
  "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 — the required type and ownerId parameters are missing:

{
  "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

For the full list of common API errors, see Errors.

Known specifics

The whole range comes as one set. Bitrix24 delivers the requested period as a single unpaginated array. The platform sorts it deterministically — by the event start from, ties broken by id, then by occurrenceIndex — and returns the window from offset to offset + limit. The element order is reproducible across requests. Windows with different offset values do not overlap and together cover the whole set.

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 the same id and parentId, differing in from / to and occurrenceIndex — the id + occurrenceIndex pair uniquely identifies a row of the set.

Timezone offset across the set. The instant in from and to is exact in every row, but the offset suffix is not the same across all rows of the response — occurrences of a recurring series carry the offset in effect at the start of the series. Parse the values into instants and convert them to the timezone you need. Hours and minutes read straight from the string can differ from the time the employee sees in the calendar.

Change tracking. The version field is a monotonic counter of changes to the event, independent of the account's regional settings. Request the list with select=id,version, compare the pairs against your snapshot and re-read the changed events. Both fields are described in Event fields.

See also

• Create event
• Get event
• Event fields
• Related data