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. It also automatically splits the result set into weekly windows when filtering by a date range wider than 14 days — this bypasses the ceiling of 5000 records per Bitrix24 call.

Request fields (body)

status vs realStatus. filter.status in Bitrix24 is a virtual (meta) filter (−1 overdue, −2 unviewed, −3 almost overdue), not the number from the status field of the response: {"filter": {"status": 2}} will not return tasks with status 2. To filter/sort by the actual status use realStatus: {"filter": {"realStatus": 2}}, {"sort": {"realStatus": "asc"}}.

meta.total does not arrive on every call. When limit is at most 50 and offset is zero, the count does not have to be requested: if the page came back shorter than limit, meta.total still arrives with the exact number (an empty result gives 0); on a full page the field is absent. When limit is above 50 meta.total arrives — the count runs only where it cannot be avoided — and an explicit withTotal=false removes it there too. When the result set is split into windows (autoWindowed: true) the count is requested as before and withTotal is ignored. Check whether the field is present in a given response, and page by meta.hasMore.

Examples

curl — personal key

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

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

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

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

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 determines whose workspace the tasks page is shown in — substitute the ID of the employee you need, for example the current one. <portal> — the Bitrix24 account domain. Access is limited by the employee's permissions in Bitrix24.

Response example

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

With a date-range filter wider than 14 days, meta additionally returns autoWindowed, windowCount, and batchWaves:

{
  "success": true,
  "data": [ /* ... */ ],
  "meta": {
    "total": 179,
    "hasMore": true,
    "autoWindowed": true,
    "windowCount": 131,
    "batchWaves": 3,
    "durationMs": 1543
  }
}

Error response example

403 — no scope:

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

Errors

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. A date-range filter wider than 14 days is automatically split into weekly windows executed in parallel waves, so the result set bypasses the ceiling of 5000 records per call. meta then returns autoWindowed: true, the number of windows windowCount, and the number of waves batchWaves. The autoWindow: false parameter disables splitting. While splitting is active, an offset greater than zero is rejected with UNSTABLE_OFFSET_PAGINATION.

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

• List tasks
• Task fields
• Aggregate tasks
• Filtering syntax
• Batch requests
• Limits and optimization