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
filter object yes Search conditions. type and ownerId are required. Additionally — from, to, section. A field outside this set returns 400 UNSUPPORTED_FILTER
filter.type string yes Calendar type: user, group, company_calendar
filter.ownerId number yes Calendar owner ID. For type=user — the employee ID from GET /v1/users, for type=group — the workgroup ID
filter.from string no Start of the event selection period (ISO 8601)
filter.to string no End of the event selection period (ISO 8601)
filter.section number no Calendar section ID
limit number no Number of records up to 5000. Defaults to 50
offset number no Skip N records
order object no Sorting: { "from": "desc" }
select string[] no Field selection: ["id", "name", "from"]

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
success boolean Always true on success
data array Array of events. For all fields see Event fields
meta.total number How many records matched the filter
meta.hasMore boolean Whether there are more records beyond limit
meta.durationMs number Request duration in milliseconds

The meta fields sit next to data, not inside it. Pages must be walked 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
400 MISSING_REQUIRED_PARAMS The required type and/or ownerId were not passed. message lists the missing fields
400 UNSUPPORTED_FILTER The filter contains a field outside the set type, ownerId, from, to, section
403 SCOPE_DENIED The key lacks the calendar scope
401 MISSING_API_KEY The X-Api-Key header was not passed

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