Retrieve tracks with access checks, filtering, sorting, pagination, public URL information, comment counters, and favorite labels.
By default, the method returns all native fields from the tracks table together with additional calculated and related fields. A limited response mode is available for requests that need only essential track information.
The number in the URL path (/1/) is the organization identifier — referred to as account_id.
This value must match the account associated with the provided session_id or token.
This endpoint supports both:
GET https://api.doboard.com/42/track_get?project_id=7&status=ACTIVE&length=25&order_column=step_number&order_dir=asc&session_id=abc123xyz
In this example:
42 is the organization/account ID.project_id=7 returns tracks from project 7.status=ACTIVE returns only active tracks.length=25 limits the response to 25 tracks.order_column=step_number sorts tracks by their step number.order_dir=asc uses ascending order.session_id=abc123xyz is used for authentication.If the account ID in the URL does not match the account tied to the session or token, the request will be rejected.
Required
The method requires a valid session or guest/public access context:
session_id – for authenticated userstoken – for guest/public accessAccess rules:
projects_users.When a single track_id is requested but is not present in the filtered result, the method performs an additional access check:
4603 is returned.tracks array.| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
session_id |
string | Yes* | – | Authenticated user session ID. |
token |
string | Yes* | – | Guest/public access token. |
project_id |
int | No | – | Filters tracks by project ID. |
track_id |
int / array / string | No | – | One or multiple track IDs. Accepts a single ID, an array, or comma-separated IDs. |
status |
string | No | – | Filters by track status. Allowed values: ACTIVE, REMOVED, DONE. |
type |
string | No | – | Filters by track type. Allowed values: REGULAR, TEMPLATE. |
task_status |
string | No** | – | Returns tracks containing a task with this status. Allowed values: ACTIVE, REMOVED, DONE. |
task_user_id |
int | No** | – | User ID assigned to the task used by the task_status filter. |
limited_mode |
int / boolean | No | – | Enables the reduced response format and allows a page size of 1000. |
start |
int | No | 0 |
Offset for pagination. |
length |
int | No | 100*** |
Page size. Allowed values: 10, 25, 50, 100. Limited mode also allows 1000. |
order_column |
string | No | track_id |
Sorting column. Allowed values: track_id, step_number, name. |
order_dir |
string | No | DESC |
Sort direction. Allowed values: lowercase asc or desc. |
* Either session_id or token is required.
** task_status and task_user_id must both be supplied for the task filter to be applied.
*** The default length is 1000 when limited_mode is enabled.
The task-based filter is applied only when:
task_status is non-empty;task_user_id is non-empty; andtask_status is one of ACTIVE, REMOVED, or DONE.When active, the filter returns tracks containing at least one task that has both:
If either parameter is missing, or if task_status is unsupported, this filter is not applied. An unsupported task_status does not produce a validation error.
{
"data": {
"operation_status": "SUCCESS",
"tracks": [
{
"track_id": 123,
"project_id": 7,
"created": "2026-05-01 09:00:00",
"updated": "2026-05-12 14:30:00",
"due_date": "2026-09-30 18:00:00",
"name": "Development",
"description": "Development tasks for the current release.",
"status": "ACTIVE",
"type": "REGULAR",
"step_number": 2,
"hours_estimated": 120,
"hours_worked": 48,
"hours_avaible": 72,
"tasks_total": 15,
"tasks_opened": 9,
"tasks_closed": 6,
"attachments_count": 3,
"comments_count": 4,
"comments_viewers": [5, 8, 12],
"favorite_labels": [10, 11],
"favorite_label_groups": [3],
"page_id": 501,
"URL_PATH": "/products/security/"
}
],
"records_filtered": 1
}
}
records_filtered contains the total number of tracks matching the access rules and filters before pagination is applied.
An empty result is returned as:
{
"data": {
"operation_status": "SUCCESS",
"tracks": [],
"records_filtered": 0
}
}
{
"data": {
"operation_status": "FAILED",
"operation_message": "status must be in ('ACTIVE','REMOVED','DONE')"
},
"error_message": "status must be in ('ACTIVE','REMOVED','DONE')",
"error_no": 4601
}
By default, each object in tracks[] contains every native field from the tracks table.
| Field | Type | Description |
|---|---|---|
track_id |
int | Unique track identifier. |
project_id |
int | ID of the project containing the track. |
created |
datetime | Date and time when the track was created. |
updated |
datetime/null | Date and time when the track was last updated. |
due_date |
datetime/null | Optional track due date. |
name |
string | Track name, up to 128 characters. |
description |
string | Track description, up to 1024 characters. |
status |
enum | Track status: ACTIVE, REMOVED, or DONE. |
type |
enum | Track type: REGULAR or TEMPLATE. |
step_number |
int | Numeric track step/order value. |
hours_estimated |
int/null | Estimated-hours value stored for the track. |
hours_worked |
int/null | Worked-hours value stored for the track. |
hours_avaible |
int/null | Available-hours value stored for the track. The field name is returned with this spelling. |
tasks_total |
int/null | Total number of tasks in the track. |
tasks_opened |
int/null | Number of open tasks in the track. |
tasks_closed |
int/null | Number of closed tasks in the track. |
attachments_count |
int | Number of attachments associated with the track. |
In the standard response mode, every track also contains the following calculated or related fields:
| Field | Type | Description |
|---|---|---|
comments_count |
int | Number of active comments added directly to the track. Comments linked to tasks are not counted. |
comments_viewers |
int[]/null | Distinct user IDs associated with the track’s comment viewers. |
favorite_labels |
int[]/null | Distinct favorite label IDs associated with the track. |
favorite_label_groups |
int[]/null | Distinct favorite label-group IDs associated with the track. |
page_id |
int/null | ID of the public page associated with the track. |
URL_PATH |
string/null | Public URL path associated with the track. |
When comments_viewers, favorite_labels, or favorite_label_groups contain values, they are returned as arrays of integers.
When no values exist, the corresponding field may be null or empty, depending on the database result.
When limited_mode contains a non-empty value, each track contains only:
| Field | Type | Description |
|---|---|---|
track_id |
int | Unique track identifier. |
created |
datetime | Date and time when the track was created. |
name |
string | Track name. |
step_number |
int | Numeric track step/order value. |
tasks_closed |
int/null | Number of closed tasks in the track. |
project_id |
int | ID of the project containing the track. |
Example:
{
"data": {
"operation_status": "SUCCESS",
"tracks": [
{
"track_id": 123,
"created": "2026-05-01 09:00:00",
"name": "Development",
"step_number": 2,
"tasks_closed": 6,
"project_id": 7
}
],
"records_filtered": 1
}
}
Limited mode does not return:
page_idURL_PATHIn limited mode:
10, 25, 50, 100, and 1000.1000.Filters can be combined. All active filters are joined using AND.
For example:
GET https://api.doboard.com/42/track_get?project_id=7&status=ACTIVE&type=REGULAR&task_status=ACTIVE&task_user_id=15&session_id=abc123xyz
This request returns regular active tracks from project 7 that contain at least one active task assigned to user 15.
track_id accepts:
Duplicate IDs are removed from multi-value input.
Use numeric track IDs. Malformed values may be removed from a multi-value list or produce an empty result for a single-value request.
If normalization leaves no usable IDs in a multi-value list, the track_id filter may not be applied.
If status is supplied, it must be one of:
ACTIVEREMOVEDDONEIf type is supplied, it must be one of:
REGULARTEMPLATEThere is no default status or type filter. When these parameters are omitted, tracks of all statuses and types may be returned.
Default sorting:
track_id DESC
Allowed sorting columns:
track_idstep_numbernameAllowed sort directions:
ascdescIf order_column is missing or unsupported, track_id is used.
If order_dir is missing or unsupported, DESC is used. Sort-direction values are checked in lowercase.
For standard mode, valid page sizes are:
102550100If length is missing or unsupported, 100 is used.
For limited mode, 1000 is also accepted and becomes the default.
start defines the result offset and defaults to 0.
| HTTP Code | error_no |
Message | Description |
|---|---|---|---|
401 |
– | Unauthorized |
Missing or invalid session/token. |
200 |
4601 |
status must be in ('ACTIVE','REMOVED','DONE') |
Invalid status value. |
200 |
4602 |
type must be in ('REGULAR','TEMPLATE') |
Invalid type value. |
200 |
4603 |
Access is denied |
A single requested track exists, but the user is not linked to its project. |
200 |
0 |
Internal API Error |
The track query failed. |
This is a read-only method.
It does not create, update, or delete tracks and does not publish WebSocket events.
projects_users.records_filtered is calculated before pagination.track_id DESC.100, or 1000 in limited mode.comments_count includes only active comments added directly to the track where no task is linked.page_id and URL_PATH are returned only in standard mode.hours_avaible is returned exactly as defined in the track table.4603.task_status and task_user_id work only as a pair.task_status is ignored rather than returned as a validation error.