For AI agents: markdown of this page — /docs-content-en/entities/calendar-events/search.md documentation index — /llms.txt

Calendar event search

POST /v1/calendar-events/search

Returns the same events as GET /v1/calendar-events, but the parameters are passed in the request body. The search runs within a single calendar — type and ownerId are required.

Request fields (body)

Field Type Required Description
Fieldfilter Typeobject Requiredyes DescriptionSearch conditions: the keys type and ownerId are required; from, to, and section are optional. Key values are described below the table. A field outside this set returns 400 UNSUPPORTED_FILTER.
Filtering syntax. Example: { "type": "user", "ownerId": 1, "from": "2026-06-01T00:00:00" }
Fieldlimit Typenumber Requiredno DescriptionNumber of records, up to 5000. Defaults to 50
Fieldoffset Typenumber Requiredno DescriptionSkip N records
Fieldorder Typeobject Requiredno DescriptionSorting: { "from": "desc" }
Fieldselect Typestring[] Requiredno DescriptionField selection: ["id", "name", "from"]
Fieldinclude Typestring[] Requiredno DescriptionRelated employees: ["owner", "host", "attendee"] — the same relations and the same _included shape as in the event list, up to three names. The relation reads an employee, so the key needs the user scope in addition to calendar

filter.type — calendar type: user, group, company_calendar. filter.ownerId — calendar owner ID: for type=user, the employee ID from GET /v1/users; for type=group, the workgroup ID. filter.from and filter.to — start and end of the event selection period in ISO 8601 format. filter.section — calendar section ID from GET /v1/calendar-sections.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/calendar-events/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "type": "user",
      "ownerId": 1,
      "from": "2026-06-01T00:00:00",
      "to": "2026-07-01T00:00:00"
    },
    "order": { "from": "desc" },
    "limit": 20
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/calendar-events/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "type": "user",
      "ownerId": 1,
      "from": "2026-06-01T00:00:00",
      "to": "2026-07-01T00:00:00"
    },
    "order": { "from": "desc" },
    "limit": 20
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/calendar-events/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: {
      type: 'user',
      ownerId: 1,
      from: '2026-06-01T00:00:00',
      to: '2026-07-01T00:00:00',
    },
    order: { from: 'desc' },
    limit: 20,
  }),
})

const { success, data } = await res.json()
console.log('Found:', data.length)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/calendar-events/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: {
      type: 'user',
      ownerId: 1,
      from: '2026-06-01T00:00:00',
      to: '2026-07-01T00:00:00',
    },
    order: { from: 'desc' },
    limit: 20,
  }),
})

const { success, data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of events. For all fields see Event fields
Fieldmeta.total Typenumber DescriptionHow many records matched the filter
Fieldmeta.hasMore Typeboolean DescriptionWhether there are more records beyond limit
Fieldmeta.durationMs Typenumber DescriptionRequest duration in milliseconds

The meta fields sit next to data, not inside it. Page through the results using meta.hasMore: a data length equal to limit does not rule out the last page.

Response example

The main fields are shown. For the full list see Event fields.

JSON 
{
  "success": true,
  "data": [
    {
      "id": 7521,
      "type": "user",
      "ownerId": 1,
      "name": "Weekly standup",
      "from": "2026-06-15T14:00:00+00:00",
      "to": "2026-06-15T15:00:00+00:00",
      "skipTime": false,
      "durationSeconds": 3600,
      "importance": "normal",
      "accessibility": "busy",
      "isMeeting": true,
      "sectionId": 3
    }
  ],
  "meta": { "total": 1, "hasMore": false, "durationMs": 169 }
}

Error response example

400 — filter on an unsupported field:

JSON 
{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_FILTER",
    "message": "calendar-events search accepts only top-level parameters: type, ownerId, from, to, section. Filter keys received: NAME. For single-record lookup use GET /v1/calendar-events/:id."
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_PARAMS DescriptionThe required type and/or ownerId were not passed. message lists the missing fields
HTTP400 CodeUNSUPPORTED_FILTER DescriptionThe filter contains a field outside the set type, ownerId, from, to, section
HTTP400 CodeINVALID_INCLUDE Descriptioninclude contains a name outside the set owner, host, attendee. The response lists the available names
HTTP400 CodeINCLUDE_LIMIT_EXCEEDED Descriptioninclude contains more than three names
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the calendar scope
HTTP403 CodeSCOPE_DENIED Descriptioninclude requests a relation to an employee, and the key lacks the user scope. The response names the relation and the missing scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not passed
HTTP429 CodeRATE_LIMITED DescriptionRate limit exceeded: 300 requests per minute per portal. All API keys of the portal share one limit. The current limit is returned in the x-ratelimit-limit header. Retry after the delay in the Retry-After header

For the full list of common API errors see Errors.

Known specifics

The search is limited to a single calendar and period. The search filters only by type, ownerId, from, to, section — it does not cover event content (name, importance, accessibility and other fields). To select events by such fields, fetch the events for the required period and filter them on the application side.

See also