Список задач

GET /v1/tasks

Возвращает список задач портала с поддержкой фильтрации, сортировки и авто-пагинации.

Параметры

Какие даты фильтруются. B24 tasks.task.list поддерживает фильтры по createdDate, changedDate, closedDate, deadline, dateStart. Поля statusChangedDate и activityDate не фильтруются на стороне Bitrix24 (их нет в списке фильтруемых полей метода) — такой фильтр будет молча проигнорирован. Используйте changedDate как ближайшую замену. Так же молча игнорируется фильтр по timeSpentInLogs — фактически затраченное время отбором не сужается, сумму по выборке даёт агрегация. Соисполнители/наблюдатели фильтруются по одному пользователю: ?filter[accomplices]=25, ?filter[auditors]=25. Метки — ?filter[tags]=метка.

status vs realStatus. filter[status] в Битрикс24 — виртуальный (мета-)фильтр: значения −1 (просрочена), −2 (не просмотрена), −3 (почти просрочена), а не число из поля status ответа — поэтому filter[status]=2 вернёт не все задачи со статусом 2: этот виртуальный фильтр присваивает каждой задаче ровно одно значение, и помеченные −1, −2 или −3 под условие не попадут. Для фильтра и сортировки по фактическому статусу используйте realStatus: ?filter[realStatus]=2 (ждёт выполнения), ?filter[realStatus]=5 (завершена), ?sort=realStatus. Значение realStatus совпадает с полем status в ответе.

meta.total приходит не на каждый вызов. При limit не больше 50 и offset, равном нулю, подсчёт можно не заказывать: если страница пришла короче limit, meta.total всё равно придёт с точным числом — коллекция на такой странице закончилась (пустой результат даёт 0). Если страница пришла полной, поля не будет. При limit больше 50 meta.total приходит — подсчёт платформа выполняет, только когда без него не обойтись, — и убрать его оттуда можно явным withTotal=false. Проверяйте наличие поля в конкретном ответе, а листайте по meta.hasMore.

Примеры

curl — личный ключ

curl "https://vibecode.bitrix24.tech/v1/tasks?limit=10&filter[status]=2&order[id]=desc" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth-приложение

curl "https://vibecode.bitrix24.tech/v1/tasks?limit=10&filter[status]=2&order[id]=desc" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — личный ключ

const url = 'https://vibecode.bitrix24.tech/v1/tasks?limit=10&filter[status]=2&order[id]=desc'
const res = await fetch(url, {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
console.log(`Получено ${data.length} из ${meta.total} задач`)

JavaScript — OAuth-приложение

const url = 'https://vibecode.bitrix24.tech/v1/tasks?limit=10&filter[status]=2&order[id]=desc'
const res = await fetch(url, {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Поля ответа

URL карточки любой задачи из массива data строится из её id и ID сотрудника:

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

<responsibleId> — ID ответственного (поле responsibleId каждого элемента): задача откроется в его личном кабинете. Сегмент user/<...> задаёт, в чьём кабинете отображается страница задач — подставьте ID нужного сотрудника, например текущего. <portal> — домен портала. Доступ ограничен правами сотрудника в Битрикс24.

Пример ответа

{
  "success": true,
  "data": [
    {
      "id": 289,
      "title": "Подготовить отчёт за квартал",
      "status": 2,
      "priority": 1,
      "responsibleId": 79,
      "createdBy": 99,
      "createdDate": "2026-05-12T06:11:18.000Z",
      "deadline": "2026-05-19T15:00:00.000Z",
      "groupId": 0,
      "accomplices": [],
      "auditors": [],
      "tags": {},
      "notViewed": false,
      "chatId": 3567,
      "creator": {
        "id": "99",
        "name": "Анна Соколова",
        "link": "/company/personal/user/99/"
      },
      "responsible": {
        "id": "79",
        "name": "Дмитрий Орлов",
        "link": "/company/personal/user/79/"
      }
    }
  ],
  "meta": {
    "total": 184,
    "hasMore": true
  }
}

Пример ответа при ошибке

403 — нет скоупа:

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

Ошибки

Полный список общих ошибок API — Ошибки.

Известные особенности

Когда переходить на POST /v1/tasks/search. Если у запроса много условий фильтра или нужна выгрузка по большому диапазону дат, выбирайте POST /v1/tasks/search — параметры передаются в body, плюс доступно автоматическое разбиение запроса по временны́м окнам для выборок свыше 5000 записей. См. Поиск задач.

Приведение типов работает на верхнем уровне, внутрь объектов не заходит. Поля-карточки (creator, responsible, group, accomplicesData, auditorsData) объявлены объектами и приходят от Битрикс24 как есть — значения внутри них остаются в том виде, в каком их отдал портал, в том числе creator.id строкой ("99"). Это не то же самое, что верхнеуровневый createdBy, который приходит числом. Для арифметики по вложенному идентификатору приводите через Number().

Типы значений соответствуют схеме. Поля, объявленные в схеме числами (id, status, priority, responsibleId, createdBy, groupId, chatId и подобные), приходят числами. Признаки «да/нет» приходят значениями true/false. Пустые tags, group, accomplicesData, auditorsData — пустым объектом {}. Приведение через Number(value) больше не требуется. Раньше эти значения приходили строками — если ваш код сравнивает их со строкой (status === "2"), его нужно поправить.

Смотрите также

• Получить задачу
• Поиск задач
• Поля задачи
• Агрегация задач
• Синтаксис фильтрации
• Batch
• Лимиты и оптимизация