Get a list of upcoming events calendar.event.get.nearest

If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the MCP server so that the assistant can utilize the official REST documentation.

Scope: calendar

Who can execute the method: any user

This method retrieves a list of upcoming events.

Method Parameters

Name `type`	Description
type `string`	Calendar type: `user` — user calendar `group` — group calendar `company_calendar` — company calendar
ownerId `integer`	Identifier of the calendar owner. For the company calendar, the `ownerId` parameter is `0`
days `integer`	Number of days to retrieve. Default is `60`
forCurrentUser `boolean`	Output the list of events for the current user. Default is `true`
maxEventsCount `integer`	Maximum number of events to display
detailUrl `string`	URL link to the calendar

Code Examples

How to Use Examples in Documentation

Get events for the current user for the next 10 days.

cURL (Webhook)

cURL (OAuth)

PHP

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"type":"user","ownerId":2,"days":10,"forCurrentUser":true,"maxEventsCount":100,"detailUrl":"/company/personal/user/#user_id#/calendar/"}' \
        https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/calendar.event.get.nearest

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"type":"user","ownerId":2,"days":10,"forCurrentUser":true,"maxEventsCount":100,"detailUrl":"/company/personal/user/#user_id#/calendar/","auth":"**put_access_token_here**"}' \
        https://**put_your_bitrix24_address**/rest/calendar.event.get.nearest

BX24.callMethod(
            'calendar.event.get.nearest',
            {
                type: 'user',
                ownerId: 2,
                days: 10,
                forCurrentUser: true,
                maxEventsCount: 100,
                detailUrl: '/company/personal/user/#user_id#/calendar/'
            }
        );

require_once('crest.php');
        
        $result = CRest::call(
            'calendar.event.get.nearest',
            [
                'type' => 'user',
                'ownerId' => 2,
                'days' => 10,
                'forCurrentUser' => true,
                'maxEventsCount' => 100,
                'detailUrl' => '/company/personal/user/#user_id#/calendar/'
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';

Get events from the company calendar.

cURL (Webhook)

cURL (OAuth)

PHP

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"type":"company_calendar","ownerId":"","forCurrentUser":false}' \
        https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/calendar.event.get

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"type":"company_calendar","ownerId":"","forCurrentUser":false,"auth":"**put_access_token_here**"}' \
        https://**put_your_bitrix24_address**/rest/calendar.event.get

BX24.callMethod(
            'calendar.event.get',
            {
                type: 'company_calendar',
                ownerId: 0, // ownerId is not specified when retrieving events from the company calendar. It is empty for all events of this type.
                forCurrentUser: false
            }
        );

require_once('crest.php');
        
        $result = CRest::call(
            'calendar.event.get',
            [
                'type' => 'company_calendar',
                'ownerId' => '',
                'forCurrentUser' => false
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';

Response Handling

HTTP status: 200

{
            "result": [
                {
                    "ID": "1265",
                    "PARENT_ID": "1265",
                    "DELETED": "N",
                    "CAL_TYPE": "user",
                    "OWNER_ID": "1",
                    "NAME": "Event Name",
                    "DATE_FROM": "12/11/2024 05:59:00 pm",
                    "DATE_TO": "12/11/2024 06:59:00 pm",
                    "ORIGINAL_DATE_FROM": null,
                    "TZ_FROM": "Europe/Riga",
                    "TZ_TO": "Europe/Riga",
                    "TZ_OFFSET_FROM": "7200",
                    "TZ_OFFSET_TO": "7200",
                    "DATE_FROM_TS_UTC": "1733932740",
                    "DATE_TO_TS_UTC": "1733936340",
                    "DT_SKIP_TIME": "N",
                    "DT_LENGTH": 3600,
                    "EVENT_TYPE": null,
                    "CREATED_BY": "1",
                    "DATE_CREATE": "12/05/2024 01:48:41 pm",
                    "TIMESTAMP_X": "12/05/2024 01:48:41 pm",
                    "DESCRIPTION": "Description for event",
                    "PRIVATE_EVENT": "",
                    "ACCESSIBILITY": "free",
                    "IMPORTANCE": "normal",
                    "IS_MEETING": true,
                    "MEETING_STATUS": "H",
                    "MEETING_HOST": "1",
                    "MEETING": {
                        "HOST_NAME": "User Name",
                        "NOTIFY": false,
                        "REINVITE": false,
                        "ALLOW_INVITE": false,
                        "HIDE_GUESTS": false,
                        "MEETING_CREATOR": 1,
                        "LANGUAGE_ID": "de",
                        "MAIL_FROM": ""
                    },
                    "LOCATION": "test location",
                    "REMIND": [
                        {
                            "type": "min",
                            "count": 50
                        }
                    ],
                    "COLOR": "#9dcf00",
                    "RRULE": {
                        "FREQ": "WEEKLY",
                        "BYDAY": {
                            "MO": "MO",
                            "WE": "WE"
                        },
                        "INTERVAL": 1,
                        "UNTIL": "12/24/2024",
                        "~UNTIL": "12/24/2024",
                        "UNTIL_TS": 1734998400
                    },
                    "EXDATE": "11/28/2024;12/05/2024;12/12/2024;12/19/2024;12/26/2024",
                    "DAV_XML_ID": "20241211T155900Z-534185204b362e9be7e261e92ccd9078@b24evo.lan",
                    "G_EVENT_ID": "",
                    "DAV_EXCH_LABEL": "",
                    "CAL_DAV_LABEL": "",
                    "VERSION": "1",
                    "ATTENDEES_CODES": [
                        "U1"
                    ],
                    "RECURRENCE_ID": 1272,
                    "RELATIONS": {
                        "ORIGINAL_RECURSION_ID": 1271,
                        "COMMENT_XML_ID": "EVENT_1271_12/23/2024"
                    },
                    "SECTION_ID": "4",
                    "SYNC_STATUS": null,
                    "UF_CRM_CAL_EVENT": [
                        "CO_1",
                        "L_5"
                    ],
                    "UF_WEBDAV_CAL_EVENT": false,
                    "SECTION_DAV_XML_ID": null,
                    "DATE_FROM_FORMATTED": "Wed Dec 11 2024 17:59:00",
                    "DATE_TO_FORMATTED": "Wed Dec 11 2024 18:59:00",
                    "SECT_ID": "4",
                    "ATTENDEE_LIST": [
                        {
                            "id": 1,
                            "entryId": "1265",
                            "status": "H"
                        }
                    ],
                    "COLLAB_ID": null,
                    "~RRULE_DESCRIPTION": "every week on: Mon, Wed, from 12/11/2024 to 12/24/2024",
                    "attendeesEntityList": [
                        {
                            "entityId": "user",
                            "id": 1
                        }
                    ],
                    "~DESCRIPTION": "Description for event",
                    "~USER_OFFSET_FROM": 7200,
                    "~USER_OFFSET_TO": 7200
                },
                {
                    "ID": "1221",
                    ...
                }
            ],
            "time": {
                "start": 1733411636.753706,
                "finish": 1733411637.040975,
                "duration": 0.28726911544799805,
                "processing": 0.05995798110961914,
                "date_start": "2024-12-05T15:13:56+00:00",
                "date_finish": "2024-12-05T15:13:57+00:00"
            }
        }

Returned Data

Name `type`	Description
result `object`	Object with event fields
ID `string`	Event identifier
PARENT_ID `string`	Identifier of the parent event
DELETED `string`	Flag indicating whether the event is deleted. Possible values: `Y` — event is deleted `N` — event is not deleted
CAL_TYPE `string`	Type of calendar in which the event is located
OWNER_ID `string`	Identifier of the calendar owner: `id` of the user for the calendar type `user` `id` of the group for the calendar type `group`
NAME `string`	Event name
DATE_FROM `datetime`	Start date of the event
DATE_TO `datetime`	End date of the event
ORIGINAL_DATE_FROM `datetime`	Start date of the original event for recurring events
TZ_FROM `string`	Timezone of the event start date
TZ_TO `string`	Timezone of the event end date
TZ_OFFSET_FROM `string`	Time offset of the event start time relative to UTC in seconds
TZ_OFFSET_TO `string`	Time offset of the event end time relative to UTC in seconds
DATE_FROM_TS_UTC `string`	Start date and time of the event in UTC in timestamp format
DATE_TO_TS_UTC `string`	End date and time of the event in UTC in timestamp format
DT_SKIP_TIME `string`	Flag indicating that the event lasts all day. Possible values: `Y` — all day `N` — not all day
DT_LENGTH `integer`	Duration of the event in seconds
EVENT_TYPE `string`	Type of event
CREATED_BY `string`	Identifier of the user who created the event
DATE_CREATE `datetime`	Date the event was created
TIMESTAMP_X `datetime`	Date the event was modified
DESCRIPTION `string`	Description of the event
PRIVATE_EVENT `string`	Mark indicating that the event is private. Possible values: `Y` — private `N` — not private
ACCESSIBILITY `string`	Availability of event participants
IMPORTANCE `string`	Importance of the event
IS_MEETING `boolean`	Indicator of a meeting with event participants. Possible values: `Y` — meeting with participants `N` — meeting without participants
MEETING_STATUS `string`	Status of participation in the event. Possible values: `Y` — accepted `N` — declined `Q` — invited but not yet responded `H` — event organizer
MEETING_HOST `string`	Identifier of the user hosting the event
MEETING `object`	Object describing meeting settings
LOCATION `string`	Identifier or name of the event location
REMIND `array`	Array of objects describing event reminders
COLOR `string`	Background color of the event
RRULE `object`	Recurrence of the event in the form of an object in terms of the iCalendar standard
EXDATE `string`	List of exception dates from the recurrence rule
DAV_XML_ID `string`	Synchronization identifier
G_EVENT_ID `string`	Synchronization identifier
CAL_DAV_LABEL `string`	Synchronization identifier
VERSION `string`	Version of event changes
ATTENDEES_CODES `array`	Identifiers of event participants
RECURRENCE_ID `string`	Identifier of the original event when editing only the current one
RELATIONS `object`	Object for recurring events with information about relationships to the original event
SECTION_ID `string`	Identifier of the calendar in which the event is located
SYNC_STATUS `string`	Synchronization status of the event
UF_CRM_CAL_EVENT `array`	Array of identifiers of CRM entities linked to the event
UF_WEBDAV_CAL_EVENT `array`	Array of identifiers of files linked to the event
SECTION_DAV_XML_ID `array`	Synchronization identifier of the event calendar
DATE_FROM_FORMATTED `string`	Formatted start date of the event
DATE_TO_FORMATTED `string`	Formatted end date of the event
SECT_ID `string`	Identifier of the calendar in which the event is located
ATTENDEE_LIST `array`	Array of objects describing event participants and their participation statuses. The structure of the object is described below
COLLAB_ID `integer`	Identifier of the collaboration in which the event was created
~RRULE_DESCRIPTION `string`	Text description of the event recurrence rule
attendeesEntityList `array`	Array of objects describing users — event participants
~DESCRIPTION `string`	Description of the event
~USER_OFFSET_FROM `integer`	Time offset of the event start time relative to the current user's timezone
~USER_OFFSET_TO `integer`	Time offset of the event end time relative to the current user's timezone

MEETING Object

Name `type`	Description
HOST_NAME `string`	Name of the user hosting the event
NOTIFY `boolean`	Flag for notifying about confirmation or decline of participants
REINVITE `boolean`	Flag for requesting re-confirmation of participation when editing the event
ALLOW_INVITE `boolean`	Flag allowing participants to invite others to the event
HIDE_GUESTS `boolean`	Flag for hiding the list of participants
MEETING_CREATOR `integer`	Identifier of the event creator
LANGUAGE_ID `string`	Language identifier for event notifications
MAIL_FROM `string`	Sender's address for notifications

REMIND Object

Name
type

Description

type
string

Time type of the reminder

min — minutes
hour – hours
day — days

count
integer

Numerical value of the time interval

RRULE Object

Name `type`	Description
FREQ `string`	Frequency of recurrence `DAILY` — daily `WEEKLY` — weekly `MONTHLY` — monthly `YEARLY` — yearly
BYDAY `object`	Days of the week `SU` — Sunday `MO` — Monday `TU` — Tuesday `WE` — Wednesday `TH` — Thursday `FR` — Friday `SA` — Saturday
INTERVAL `integer`	Interval between recurrences
UNTIL `date`	End date of recurrences
~UNTIL `date`	End date of recurrences. Technical field
UNTIL_TS `integer`	End date of recurrences in timestamp format

RELATIONS Object

Name `type`	Description
ORIGINAL_RECURSION_ID `integer`	Identifier of the original event for recurring events created when editing
COMMENT_XML_ID `string`	Identifier of the original event for single events created when editing from recurring ones

ATTENDEE_LIST Objects

Name `type`	Description
id `integer`	Identifier of the user
entryId `string`	Identifier of the event
status `string`	Status of the event participant. Possible values: `Y` — accepted `N` — declined `Q` — invited but not yet responded `H` — event organizer

attendeesEntityList Object

Name `type`	Description
entityId `string`	Type of the entity of the event participant
id `integer`	Identifier of the event participant

Error Handling

HTTP status: 400

{
          "error": "",
          "error_description": "Access denied"
        }

Name `type`	Description
error `string`	String error code. It may consist of digits, Latin letters, and underscores
error_description `error_description`	Textual description of the error. The description is not intended to be shown to the end user in its raw form

Possible Error Codes

Code	Error Message	Description
Empty string	Access denied	Access to the calendar type is restricted or the user has not activated the calendar functionality

Statuses and System Error Codes

HTTP Status: 20x, 40x, 50x

The errors described below may occur when calling any method.

Status	Code Error Message	Description
`500`	`INTERNAL_SERVER_ERROR` Internal server error	An internal server error has occurred. Please contact the server administrator or Bitrix24 technical support
`500`	`ERROR_UNEXPECTED_ANSWER` Server returned an unexpected response	An internal server error has occurred. Please contact the server administrator or Bitrix24 technical support
`503`	`QUERY_LIMIT_EXCEEDED` Too many requests	The request intensity limit has been exceeded
`405`	`ERROR_BATCH_METHOD_NOT_ALLOWED` Method is not allowed for batch usage	The current method is not permitted for calls using batch
`400`	`ERROR_BATCH_LENGTH_EXCEEDED` Max batch length exceeded	The maximum length of parameters passed to the batch method has been exceeded
`401`	`NO_AUTH_FOUND` Wrong authorization data	Invalid access token or webhook code
`400`	`INVALID_REQUEST` Https required	The HTTPS protocol is required for method calls
`503`	`OVERLOAD_LIMIT` REST API is blocked due to overload	The REST API is blocked due to overload. This is a manual individual block; please contact Bitrix24 technical support to lift it
`403`	`ACCESS_DENIED` REST API is available only on commercial plans	The REST API is only available on commercial plans
`403`	`INVALID_CREDENTIALS` Invalid request credentials	The user associated with the access token or webhook used to call the method lacks the necessary permissions
`404`	`ERROR_MANIFEST_IS_NOT_AVAILABLE` Manifest is not available	The manifest is not available
`403`	`insufficient_scope` The request requires higher privileges than provided by the webhook token	The request requires higher privileges than those provided by the webhook token
`401`	`expired_token` The access token provided has expired	The provided access token has expired
`403`	`user_access_error` The user does not have access to the application	The user does not have access to the application. This means that the application is installed, but the portal administrator has restricted access to this application to specific users only
`500`	`PORTAL_DELETED` Portal was deleted	The public part of the site is closed. To open the public part of the site on an on-premise installation, disable the "Temporary closure of the public part of the site" option. Path to the setting: Desktop > Settings > Product Settings > Module Settings > Main Module > Temporary closure of the public part of the site

Get List of Calendar Events

Delete Event

Get a list of upcoming events calendar.event.get.nearest

Method ParametersMethod Parameters

Code ExamplesCode Examples

Response HandlingResponse Handling

Returned DataReturned Data

MEETING ObjectMEETING Object

REMIND ObjectREMIND Object

RRULE ObjectRRULE Object

RELATIONS ObjectRELATIONS Object

ATTENDEE_LIST ObjectsATTENDEE_LIST Objects

attendeesEntityList ObjectattendeesEntityList Object

Error HandlingError Handling

Possible Error CodesPossible Error Codes

Statuses and System Error CodesStatuses and System Error Codes