Get Task List tasks.task.list
Choose a tool for developing with an AI agent:
- use Alaio Vibecode to build an app for Bitrix24 from a task description without knowing any programming language. The agent writes the code and deploys the app to a server, with no manual hosting setup
- use the MCP server to develop a REST API integration in your own project. The agent refers to the official REST documentation
Scope:
taskWho can execute the method: any user
The method has a REST 3.0 version with the same name — tasks.task.list. It is called at an address with /rest/api/. It returns tasks in result.items instead of result.tasks and selects pages with the pagination parameter instead of start.
The method tasks.task.list retrieves a list of tasks with pagination. It replaces the deprecated method task.items.getlist.
Which tasks are included in the list depends on the user's permissions:
- administrator — all tasks
- manager — tasks of their employees
- others — only tasks available to them
Method Parameters
Required parameters are marked with *
All parameters are optional.
|
Name |
Description |
|
order |
An object for sorting the task list in the format The sorting direction can take the following values:
By default, it sorts in descending order by The field for sorting can take the following values:
|
|
filter |
An object for filtering the task list in the format
To get tasks from Favorites, pass You can specify the type of filtering before the name of the filterable field:
By default, records are not filtered |
|
select |
An array containing a list of fields to select. By default, the system returns only those fields stored in the record — without additional data calculated on the fly. Warning Always specify fields in |
|
params |
Field groups the method adds to each task: result, time spent, description for the mobile app (detailed description). By default, these fields are not returned |
|
start |
How many records to skip from the beginning of the list. A page contains no more than 50 records. To retrieve the second page, pass Default is |
Parameter params
Each key adds its own group of fields to the response. The fields are returned for any key value, even false or "N". To omit them, do not pass the key.
|
Name |
Description |
|
WITH_RESULT_INFO |
Adds fields about the task result: |
|
WITH_TIMER_INFO |
Adds fields about time spent: |
|
WITH_PARSED_DESCRIPTION |
Adds the |
The fields are described in detail in the Additional Task Fields section.
Code Examples
How to Use Examples in Documentation
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"order":{"DEADLINE":"asc","PRIORITY":"desc"},"filter":{"!STATUS":6,">=DEADLINE":"'"$(date +%Y-%m-%d)"'","RESPONSIBLE_ID":547,"::SUBFILTER-PARAMS":{"FAVORITE":"Y"}},"select":["ID","TITLE","DESCRIPTION","STATUS","subStatus","DEADLINE","CREATED_DATE","RESPONSIBLE_ID","ACCOMPLICES","AUDITORS","TAGS","COUNTERS","PRIORITY","MARK"],"params":{"WITH_TIMER_INFO":true,"WITH_RESULT_INFO":true,"WITH_PARSED_DESCRIPTION":true}}' \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/tasks.task.list
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"order":{"DEADLINE":"asc","PRIORITY":"desc"},"filter":{"!STATUS":6,">=DEADLINE":"'"$(date +%Y-%m-%d)"'","RESPONSIBLE_ID":547,"::SUBFILTER-PARAMS":{"FAVORITE":"Y"}},"select":["ID","TITLE","DESCRIPTION","STATUS","subStatus","DEADLINE","CREATED_DATE","RESPONSIBLE_ID","ACCOMPLICES","AUDITORS","TAGS","COUNTERS","PRIORITY","MARK"],"params":{"WITH_TIMER_INFO":true,"WITH_RESULT_INFO":true,"WITH_PARSED_DESCRIPTION":true},"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/tasks.task.list
// This snippet is an ES module: top-level await requires type="module" or a bundler.
// $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
import { Text } from '@bitrix24/b24jssdk'
import type { B24Frame, ISODate } from '@bitrix24/b24jssdk'
declare const $b24: B24Frame
// Shape of a single task in result.tasks. Only the fields read below are typed here;
// the request selects more — add them to this type as you start using them.
type TaskListItem = {
id: string
title: string
status: string
deadline: ISODate | null
responsibleId: string
}
try {
// tasks.task.list returns a single page (max 50 records). For the whole result set
// use a list helper: $b24.actions.v2.callList.make() returns every record as one
// array, $b24.actions.v2.fetchList.make() yields them in chunks (async generator).
// NOTE: the list helpers do not accept `order` (it is excluded from their params, so
// passing it is a TS error) — keep this call.make + `start` variant when sort matters.
const response = await $b24.actions.v2.call.make<{ tasks: TaskListItem[] }>({
method: 'tasks.task.list',
params: {
// Sorting: nearest deadline first, then higher priority
order: { DEADLINE: 'asc', PRIORITY: 'desc' },
filter: {
'!STATUS': 6, // exclude deferred tasks
'>=DEADLINE': new Date().toISOString().split('T')[0], // not overdue (UTC date; adjust to the account time zone if needed)
RESPONSIBLE_ID: 547, // tasks of a specific responsible person
'::SUBFILTER-PARAMS': { FAVORITE: 'Y' } // favorites only
},
// Request only the fields you need
select: [
'ID', 'TITLE', 'DESCRIPTION', 'STATUS', 'subStatus',
'DEADLINE', 'CREATED_DATE', 'RESPONSIBLE_ID',
'ACCOMPLICES', 'AUDITORS', 'TAGS', 'COUNTERS',
'PRIORITY', 'MARK'
],
// Extra computed data
params: {
WITH_TIMER_INFO: true,
WITH_RESULT_INFO: true,
WITH_PARSED_DESCRIPTION: true
},
// Page offset (not the page number): the page size is fixed at 50, so the
// Nth page is start = (N - 1) * 50.
start: 0
},
requestId: Text.getUuidRfc4122() // optional unique tracking id for this request
})
// The payload is available only on a successful response
if (!response.isSuccess) {
console.error(response.getErrorMessages().join('; '))
} else {
const tasks = response.getData()!.result.tasks
// getTotal() is deprecated (removed in SDK 2.0); for the full match count fetch
// everything via a list helper (see above) and read its length.
console.info(`Loaded ${tasks.length} tasks (one page)`)
for (const task of tasks) {
console.info(`#${task.id}: ${task.title}`)
}
}
} catch (error) {
// Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
console.error(error)
}
<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
<script>
async function listTasks() {
try {
// Initialize the SDK inside a Bitrix24 frame
const $b24 = await B24Js.initializeB24Frame()
// tasks.task.list returns a single page (max 50 records). For the whole result set
// use a list helper: $b24.actions.v2.callList.make() returns every record as one
// array, $b24.actions.v2.fetchList.make() yields them in chunks (async generator).
// NOTE: the list helpers do not accept `order` (it is excluded from their params, so
// passing it is a TS error) — keep this call.make + `start` variant when sort matters.
const response = await $b24.actions.v2.call.make({
method: 'tasks.task.list',
params: {
// Sorting: nearest deadline first, then higher priority
order: { DEADLINE: 'asc', PRIORITY: 'desc' },
filter: {
'!STATUS': 6, // exclude deferred tasks
'>=DEADLINE': new Date().toISOString().split('T')[0], // not overdue (UTC date; adjust to the account time zone if needed)
RESPONSIBLE_ID: 547, // tasks of a specific responsible person
'::SUBFILTER-PARAMS': { FAVORITE: 'Y' } // favorites only
},
// Request only the fields you need
select: [
'ID', 'TITLE', 'DESCRIPTION', 'STATUS', 'subStatus',
'DEADLINE', 'CREATED_DATE', 'RESPONSIBLE_ID',
'ACCOMPLICES', 'AUDITORS', 'TAGS', 'COUNTERS',
'PRIORITY', 'MARK'
],
// Extra computed data
params: {
WITH_TIMER_INFO: true,
WITH_RESULT_INFO: true,
WITH_PARSED_DESCRIPTION: true
},
// Page offset (not the page number): the page size is fixed at 50, so the
// Nth page is start = (N - 1) * 50.
start: 0
},
requestId: B24Js.Text.getUuidRfc4122() // optional unique tracking id for this request
})
// The payload is available only on a successful response
if (!response.isSuccess) {
console.error(response.getErrorMessages().join('; '))
return
}
const tasks = response.getData().result.tasks
// getTotal() is deprecated (removed in SDK 2.0); for the full match count fetch
// everything via a list helper (see above) and read its length.
console.info(`Loaded ${tasks.length} tasks (one page)`)
for (const task of tasks) {
console.info(`#${task.id}: ${task.title}`)
}
} catch (error) {
// Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
console.error(error)
}
}
document.addEventListener('DOMContentLoaded', listTasks)
</script>
from datetime import date
from b24pysdk.errors import BitrixAPIError, BitrixSDKException
order = {
"DEADLINE": "asc",
"PRIORITY": "desc",
}
filter = {
"!STATUS": 6,
">=DEADLINE": date.today().isoformat(),
"RESPONSIBLE_ID": 547,
"::SUBFILTER-PARAMS": {
"FAVORITE": "Y",
},
}
select = [
"ID",
"TITLE",
"DESCRIPTION",
"STATUS",
"subStatus",
"DEADLINE",
"CREATED_DATE",
"RESPONSIBLE_ID",
"ACCOMPLICES",
"AUDITORS",
"TAGS",
"COUNTERS",
"PRIORITY",
"MARK",
]
params = {
"WITH_TIMER_INFO": True,
"WITH_RESULT_INFO": True,
"WITH_PARSED_DESCRIPTION": True,
}
try:
bitrix_response = client.tasks.task.list(
order=order,
filter=filter,
select=select,
params=params,
start=0,
).response
result = bitrix_response.result
print(result)
except BitrixAPIError as error:
print(
"Bitrix API error",
f"error: {error.error}",
f"error_description: {error.error_description}",
sep="\n",
)
except BitrixSDKException as error:
print(f"Bitrix SDK error: {error.message}")
except Exception as error:
print(f"Unexpected error: {error}")
try {
$response = $b24Service
->core
->call(
'tasks.task.list',
[
'order' => [
'DEADLINE' => 'asc',
'PRIORITY' => 'desc'
],
'filter' => [
'!STATUS' => 6,
'>=DEADLINE' => date('Y-m-d'),
'RESPONSIBLE_ID' => 547,
'::SUBFILTER-PARAMS' => ['FAVORITE' => 'Y']
],
'select' => [
'ID', 'TITLE', 'DESCRIPTION', 'STATUS', 'subStatus',
'DEADLINE', 'CREATED_DATE', 'RESPONSIBLE_ID',
'ACCOMPLICES', 'AUDITORS', 'TAGS', 'COUNTERS',
'PRIORITY', 'MARK'
],
'params' => [
'WITH_TIMER_INFO' => true,
'WITH_RESULT_INFO' => true,
'WITH_PARSED_DESCRIPTION' => true,
],
]
);
$result = $response
->getResponseData()
->getResult();
echo 'Success: ' . print_r($result, true);
processData($result);
} catch (Throwable $e) {
error_log($e->getMessage());
echo 'Error fetching tasks: ' . $e->getMessage();
}
BX24.callMethod(
'tasks.task.list',
{
// Sorting
order: {
'DEADLINE': 'asc',
'PRIORITY': 'desc'
},
// Filtering
filter: {
'!STATUS': 6, // Exclude deferred tasks
'>=DEADLINE': new Date().toISOString().split('T')[0], // Not overdue
'RESPONSIBLE_ID': 547, // Tasks of a specific responsible person
'::SUBFILTER-PARAMS': { 'FAVORITE': 'Y' } // Favorite tasks only
},
// Fields to select
select: [
'ID',
'TITLE',
'DESCRIPTION',
'STATUS',
'subStatus',
'DEADLINE',
'CREATED_DATE',
'RESPONSIBLE_ID',
'ACCOMPLICES',
'AUDITORS',
'TAGS',
'COUNTERS',
'PRIORITY',
'MARK'
],
// Additional parameters
params: {
'WITH_TIMER_INFO': true,
'WITH_RESULT_INFO': true,
'WITH_PARSED_DESCRIPTION': true,
},
},
function(result){
console.info(result.data());
console.log(result);
}
);
require_once('crest.php');
$result = CRest::call(
'tasks.task.list',
[
'order' => [
'DEADLINE' => 'asc',
'PRIORITY' => 'desc'
],
'filter' => [
'!STATUS' => 6,
'>=DEADLINE' => date('Y-m-d'),
'RESPONSIBLE_ID' => 547,
'::SUBFILTER-PARAMS' => ['FAVORITE' => 'Y']
],
'select' => [
'ID', 'TITLE', 'DESCRIPTION', 'STATUS', 'subStatus',
'DEADLINE', 'CREATED_DATE', 'RESPONSIBLE_ID',
'ACCOMPLICES', 'AUDITORS', 'TAGS', 'COUNTERS',
'PRIORITY', 'MARK'
],
'params' => [
'WITH_TIMER_INFO' => true,
'WITH_RESULT_INFO' => true,
'WITH_PARSED_DESCRIPTION' => true,
],
]
);
echo '<PRE>';
print_r($result);
echo '</PRE>';
// client and ctx are already created — see the Go SDK section
res, err := client.Core().Call(ctx, "tasks.task.list", b24.Params{
"order": b24.Params{
"DEADLINE": "asc",
"PRIORITY": "desc",
},
"filter": b24.Params{
"!STATUS": 6,
">=DEADLINE": time.Now().Format("2006-01-02"),
"RESPONSIBLE_ID": 547,
"::SUBFILTER-PARAMS": b24.Params{
"FAVORITE": "Y",
},
},
"select": []string{"ID", "TITLE", "DESCRIPTION", "STATUS", "subStatus", "DEADLINE", "CREATED_DATE", "RESPONSIBLE_ID", "ACCOMPLICES", "AUDITORS", "TAGS", "COUNTERS", "PRIORITY", "MARK"},
"params": b24.Params{
"WITH_TIMER_INFO": true,
"WITH_RESULT_INFO": true,
"WITH_PARSED_DESCRIPTION": true,
},
}, b24.WithIdempotent())
if err != nil {
return fmt.Errorf("tasks.task.list: %w", err)
}
// The method wraps the response in an object with the "tasks" key.
raw, ok := b24.Unwrap(res.Result, "tasks")
if !ok {
return fmt.Errorf("no tasks key in the response")
}
var items []struct {
ID b24.ID `json:"id"`
Title string `json:"title"`
Description string `json:"description"`
Deadline string `json:"deadline"`
CreatedDate string `json:"createdDate"`
ResponsibleID b24.ID `json:"responsibleId"`
}
if err := json.Unmarshal(raw, &items); err != nil {
return fmt.Errorf("parse response: %w", err)
}
for _, it := range items {
fmt.Println(it.ID)
}
Response Handling
HTTP Status: 200
{
"result": {
"tasks": [
{
"id": "8017",
"title": "Task Example",
"description": "Task description with [B]formatting[/B]",
"deadline": "2025-10-24T19:00:00+02:00",
"createdDate": "2025-06-04T16:15:55+02:00",
"responsibleId": "547",
"priority": "2",
"mark": null,
"descriptionInBbcode": "Y",
"lengthDeadline": "1",
"status": "2",
"auditors": [
"13",
"103"
],
"accomplices": [],
"group": [],
"responsible": {
"id": "547",
"name": "Maria",
"link": "/company/personal/user/547/",
"icon": "/bitrix/images/tasks/default_avatar.png",
"workPosition": "Tester"
},
"accomplicesData": [],
"auditorsData": {
"13": {
"id": "13",
"name": "John Smith",
"link": "/company/personal/user/13/",
"icon": "https://mysite.com/b17053/resize_cache/209/c0120a8d7c10d63c83e32398d1ec4d9e/main/c8dd225a1c6ea0a25722d01644b90fe4/8b.jpg",
"workPosition": "System Administrator"
},
"103": {
"id": "103",
"name": "Samantha Johnson",
"link": "/company/personal/user/103/",
"icon": "https://mysite.com/b17053/resize_cache/8644/c0120a8d7c10d63c83e32398d1ec4d9e/main/45f/45fff10d17d398a5583184c8350cd197/buh.jpg",
"workPosition": "Accountant"
}
},
"taskRequireResult": "Y",
"taskHasOpenResult": "N",
"taskHasResult": "Y",
"timeElapsed": null,
"timerIsRunningForCurrentUser": "N",
"parsedDescription": "Task description with [B]formatting[/B]",
"counter": {
"counters": {
"expired": 0,
"newComments": 0,
"projectExpired": 0,
"projectNewComments": 0,
"mutedExpired": 0,
"mutedNewComments": 0
},
"color": "gray",
"value": 0
},
"tags": {
"35": {
"id": 35,
"title": "arpar"
}
},
"subStatus": "2"
}
]
},
"total": 1,
"time": {
"start": 1761054322,
"finish": 1761054322.348041,
"duration": 0.3480410575866699,
"processing": 0,
"date_start": "2025-10-21T16:45:22+02:00",
"date_finish": "2025-10-21T16:45:22+02:00",
"operating_reset_at": 1761054922,
"operating": 0
}
}
Returned Data
|
Name |
Description |
|
result |
An object containing the response data |
|
result.tasks |
An array of tasks. Each element is an object with task fields and additional fields. Which fields are returned depends on |
|
total |
Total number of records found |
|
time |
Information about the request execution time |
Additional Task Fields
Each field has its own condition, specified in its description: the required field in select, a key in params, or sorting by DEADLINE.
|
Name |
Description |
|
group |
The task's group: Returned as an empty array |
|
creator |
Creator data. Returned if |
|
responsible |
Responsible person data. Returned if |
|
accomplicesData |
Participant data. The key is the user ID, the value is user data. If there are no participants, an empty array |
|
auditorsData |
Observer data in the same format as |
|
subStatus |
Status that accounts for overdue and viewed state, for example |
|
lengthDeadline |
|
|
counter |
Task counters for the current user:
Returned if |
|
tags |
Task tags. The key is the tag ID, the value is an object with the |
|
taskRequireResult |
|
|
taskHasResult |
|
|
taskHasOpenResult |
|
|
timeElapsed |
Time spent in seconds. If the current user has a timer running for the task, the timer time is added to the time from the history. Returned with the |
|
timerIsRunningForCurrentUser |
|
|
parsedDescription |
Task description in BB code, prepared for the mobile app: tables, videos, and files are replaced with links; list and alignment markup is removed. Returned with the |
Error Handling
HTTP Status: 400
{
"error": "0",
"error_description": "Incorrect sort field"
}
|
Name |
Description |
|
error |
String error code. It consists of digits, Latin letters, and underscores. It may arrive empty — in that case only |
|
error_description |
Error message for the developer. Do not show it to the end user without processing |
Possible Error Codes
|
Status |
Code |
Description |
Value |
|
|
|
Incorrect sort field |
The |
Statuses and System Error Codes
HTTP Status: 4xx, 5xx
The errors described below are returned by the REST API itself, not by the logic of a specific method. They can arrive in response to any method.
|
Status |
Code |
Description |
|
|
|
An internal server error has occurred. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support |
|
|
|
The server returned an unexpected response. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support |
|
|
|
The request intensity limit has been exceeded |
|
|
|
The method is blocked because the request resource intensity limit has been exceeded. The block is lifted automatically once the accumulated execution time of the method no longer exceeds the limit |
|
|
|
The request contains no authorization data: neither an access token nor a webhook code was passed |
|
|
|
Methods are called over the HTTPS protocol only |
|
|
|
The REST API is blocked due to overload. This is a manual individual block. To have it lifted, contact Bitrix24 technical support |
|
|
|
REST API access is not active for this account. In Bitrix24 Cloud, check the current plan or trial status: Vibe+ plans include REST API access, while Essentials plans do not. A webhook receives a different error message — |
|
|
|
No active webhook with the specified user identifier and secret code was found |
|
|
|
No method with this name was found. The name is misspelled, the method does not exist in the REST API, or it is unavailable without the required scope |
|
|
|
The request requires broader permissions than the token has: for a webhook these are the permissions granted to it, for an application it is the scope. For an application, the error message ends with |
|
|
|
The access token has expired |
|
|
|
The application is installed, but the Bitrix24 administrator has granted access to it only to specific users |
|
|
|
The public part of the site is closed. To open it on an on-premise installation, disable the "Temporary closure of the public part of the site" option. Path to the setting: Desktop > Settings > Product Settings > Module Settings > Main Module > Temporary closure of the public part of the site |
Continue Learning
- Tasks: method overview
- Add Task tasks.task.add
- Update Task tasks.task.update
- Get Task by ID tasks.task.get
- Delete Task tasks.task.delete
- Get the List of Fields tasks.task.getFields
- Get Task List v 3.0 tasks.task.list
- How to Create a Comment in a Task and Attach a File
- How to Upload a File to a Task
- How to Create a Task with an Attached File