#Search tasks

POST /v1/tasks/search

Search tasks with filters and sorting. The equivalent of GET /v1/tasks, but parameters are passed in the request body — suitable for long and complex filters. Additionally supports automatic splitting of the request into time windows for selections over 5000 records.

#Request fields (body)

Parameter Type Default Description
filter object — Filtering by GET /v1/tasks/fields fields.
Filtering syntax. Example: {"status": 2, "responsibleId": 1}
select string[] — Field selection: ["id", "title", "status", "responsibleId"]
order object id desc Sorting: { "createdDate": "desc" }
limit number 50 Number of records (up to 5000)
offset number 0 Skip N records
autoWindow boolean false Split the request into time windows — bypassing the Bitrix24 limit of 5000 records per call
windowFrom datetime — Start of the range for time-window splitting (ISO 8601)
windowTo datetime — End of the range for time-window splitting (ISO 8601)

#Examples

#curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/tasks/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "status": 2, "responsibleId": 1 },
    "select": ["id", "title", "status", "deadline"],
    "order": { "id": "desc" },
    "limit": 50
  }'

#curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/tasks/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "status": 2, "responsibleId": 1 },
    "select": ["id", "title", "status", "deadline"],
    "order": { "id": "desc" },
    "limit": 50
  }'

#JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/tasks/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { status: 2, responsibleId: 1 },
    select: ['id', 'title', 'status', 'deadline'],
    order: { id: 'desc' },
    limit: 50,
  }),
})

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

#JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/tasks/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { status: 2, responsibleId: 1 },
    select: ['id', 'title', 'status', 'deadline'],
    order: { id: 'desc' },
    limit: 50,
  }),
})

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

#Response fields

Field Type Description
success boolean Always true on success
data array Array of tasks (all fields — see Task fields)
meta.total number Total number of records matching the filter
meta.hasMore boolean Whether there are more records beyond limit
meta.durationMs number Request execution duration in milliseconds
meta.autoWindowed boolean true if the request was split into time windows
meta.windowCount number Number of windows (only with autoWindowed: true)
meta.batchWaves number How many waves of parallel requests were needed (only with autoWindowed: true)

The card URL of any task from the data array is built from its id and the employee ID:

https://<portal>.bitrix24.com/company/personal/user/<responsibleId>/tasks/task/view/<id>/

<responsibleId> — the responsible person's ID (the responsibleId field of each element): the task opens in their personal workspace. The user/<...> segment defines whose workspace shows the tasks page — substitute the desired employee's ID, for example the current one. <portal> — the portal domain. Access is limited by the employee's permissions in Bitrix24.

#Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": "289",
      "title": "Prepare the quarterly report",
      "status": "2",
      "deadline": "2026-05-19T18:00:00+03:00"
    },
    {
      "id": "311",
      "title": "Reconcile with accounting",
      "status": "2",
      "deadline": "2026-05-15T17:00:00+03:00"
    }
  ],
  "meta": {
    "total": 182,
    "hasMore": true,
    "durationMs": 1226
  }
}

With autoWindow: true, autoWindowed, windowCount, batchWaves additionally appear:

JSON 
{
  "success": true,
  "data": [ /* ... */ ],
  "meta": {
    "total": 50,
    "hasMore": false,
    "autoWindowed": true,
    "windowCount": 157,
    "batchWaves": 4,
    "durationMs": 4357
  }
}

#Error response example

403 — no scope:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'tasks' scope"
  }
}

#Errors

HTTP Code Description
403 SCOPE_DENIED The API key does not have the tasks scope
401 TOKEN_MISSING The API key has no configured tokens
502 WINDOWED_SEARCH_FAILED With autoWindow: true, all sub-windows returned an error — retry the request with a narrower date range

The full list of common API errors — Errors.

#Known specifics

When to choose search over list. GET /v1/tasks is suitable for short filters in the URL. POST /v1/tasks/search is used when there are many conditions — nested objects, arrays, date ranges: parameters in the body are easier to read and assemble than a long query string.

Time-window splitting. If there are more than 5000 tasks, pass autoWindow: true together with the windowFrom/windowTo range. The request is automatically split into windows, executed in parallel waves, and meta returns the number of windows (windowCount) and waves (batchWaves). This bypasses the Bitrix24 limit of 5000 records per call.

Numeric values as strings. Identifier fields and numeric enumerations (id, status, priority, responsibleId, createdBy, groupId) come as strings. For arithmetic and comparisons, convert via Number(value).

#See also