Retrieve time records with access checks, filters, sorting, pagination, and optional worked-time totals.
The method returns estimated time, worked time, and available capacity records from projects accessible to the current user.
Time values are stored and returned in seconds.
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, token, or project_token.
This endpoint supports both:
GET https://api.doboard.com/42/hours_get?project_id=7&show_only=hours_worked&submitted_begin=2026-09-01%2000:00:00&length=100&order_column=submitted&order_dir=desc&session_id=abc123xyz
In this example:
42 is the organization/account ID.project_id=7 returns time records from project 7.show_only=hours_worked returns only worked-time records.submitted_begin sets the inclusive beginning of the reporting period.length=100 limits the response to 100 records.order_column=submitted sorts records by their submission time.order_dir=desc returns the newest records first.session_id=abc123xyz is used for authentication.Required
Provide one of:
session_id – for an authenticated usertoken – for public task guest accessproject_token – for public project guest accessAdmin users can retrieve time records from all projects in the account.
Non-admin users can retrieve time records only from projects where they are linked through projects_users.
This project-membership restriction is applied automatically before the requested filters.
This method does not define a separate public-task or public-project visibility rule for time records.
A guest can retrieve records only when the guest has a user ID linked to the corresponding project through projects_users.
An anonymous task or project token can authenticate the request, but does not by itself provide access to time records without a matching project-user association.
The method does not return an Access denied error when a record belongs to an inaccessible project.
Inaccessible records are excluded from the result. If no accessible records match, the endpoint returns a successful response with an empty hours array.
If the account ID in the URL does not match the account tied to the session or token, the request will be rejected.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
session_id |
string | Yes* | – | Authenticated user session ID. |
token |
string | Yes* | – | Public task guest-access token. |
project_token |
string | Yes* | – | Public project guest-access token. |
hour_id |
int | No | – | Filters by a specific time-record ID. |
task_id |
int | No | – | Filters records by task ID. |
project_id |
int | No | – | Filters records by project ID. |
track_id |
int | No | – | Filters records by track ID. |
comment_id |
int | No | – | Filters records by comment ID. |
user_id |
int | No | – | Filters records by the user associated with the time record. |
show_only |
string | No | – | Returns only records where the selected time field is not null. Allowed values: hours_estimated, hours_worked, hours_avaible. |
submitted_begin |
datetime | No | – | Inclusive beginning of the submission period. Expected format: Y-m-d H:i:s. |
submitted_end |
datetime | No | – | Inclusive end of the submission period. Expected format: Y-m-d H:i:s. |
start |
int | No | 0 |
Result offset for pagination. |
length |
int | No | 1000 |
Page size. Allowed values: 10, 25, 50, 100, 1000. |
order_column |
string | No | hour_id |
Sorting column. Allowed values: hour_id, submitted, comment_id, task_id, track_id, project_id, hours_worked. |
order_dir |
string | No | DESC |
Sort direction. Allowed values: lowercase asc or desc. |
* One of session_id, token, or project_token is required.
All time values are returned as integer seconds:
hours_estimatedhours_workedhours_avaibletotal_hours_workedExamples:
| Returned value | Duration |
|---|---|
900 |
15 minutes |
1800 |
30 minutes |
3600 |
1 hour |
7200 |
2 hours |
The API does not convert these values to decimal hours or formatted time strings.
All active filters are combined using AND.
For example:
GET https://api.doboard.com/42/hours_get?project_id=7&track_id=12&user_id=5&show_only=hours_worked&submitted_begin=2026-09-01%2000:00:00&submitted_end=2026-09-30%2023:59:59&session_id=abc123xyz
This request returns accessible records that:
hours_worked value.The following filters accept one ID each:
hour_idtask_idproject_idtrack_idcomment_iduser_idMulti-value arrays and comma-separated ID lists are not supported by this method.
submitted_begin applies:
submitted >= submitted_begin
submitted_end applies:
submitted <= submitted_end
Both boundaries are inclusive.
Dates are parsed and normalized by the server. A value that cannot be parsed returns a validation error.
show_only FilterThe show_only parameter accepts:
hours_estimatedhours_workedhours_avaibleIt returns records where the selected field is not null.
For example:
GET https://api.doboard.com/42/hours_get?show_only=hours_estimated&session_id=abc123xyz
returns records satisfying:
hours_estimated IS NOT NULL
A value of 0 is included because it is not null.
If show_only contains an unsupported value, the filter is ignored. The method does not return a validation error.
The field name is
hours_avaible, with this exact spelling.
When:
show_only=hours_worked
the response contains an additional field:
{
"total_hours_worked": 14400
}
total_hours_worked is the sum of hours_worked across all accessible records matching the active filters.
The total:
0 when no matching worked-time value exists.No equivalent total is returned for:
show_only=hours_estimatedshow_only=hours_avaibleshow_onlyDefault sorting:
hour_id DESC
Allowed sorting columns:
hour_idsubmittedcomment_idtask_idtrack_idproject_idhours_workedThe method does not support sorting directly by:
user_idupdatedhours_estimatedhours_avaibleAllowed sort directions:
ascdescThe direction must be lowercase. If order_dir is missing, uppercase, or unsupported, DESC is used.
If order_column is missing or unsupported, hour_id is used.
Allowed page sizes:
1025501001000If length is missing or unsupported, 1000 is used.
start defines the result offset and defaults to 0.
{
"data": {
"records_filtered": 2,
"hours": [
{
"hour_id": 901,
"user_id": 5,
"comment_id": 501,
"task_id": 101,
"track_id": 12,
"project_id": 7,
"submitted": "2026-09-18 10:15:00",
"updated": "2026-09-18 10:16:00",
"hours_estimated": null,
"hours_worked": 7200,
"hours_avaible": null
},
{
"hour_id": 900,
"user_id": 5,
"comment_id": 498,
"task_id": 101,
"track_id": 12,
"project_id": 7,
"submitted": "2026-09-17 15:00:00",
"updated": "2026-09-17 15:00:00",
"hours_estimated": null,
"hours_worked": 3600,
"hours_avaible": null
}
],
"total_hours_worked": 10800,
"operation_status": "SUCCESS"
}
}
total_hours_worked is included only when show_only=hours_worked.
{
"data": {
"records_filtered": 0,
"hours": [],
"operation_status": "SUCCESS"
}
}
When show_only=hours_worked, an empty response also contains:
{
"total_hours_worked": 0
}
{
"data": {
"operation_status": "FAILED",
"operation_message": "submitted_begin wrong format, expected format: Y-m-d H:i:s"
},
"error_message": "submitted_begin wrong format, expected format: Y-m-d H:i:s",
"error_no": 6501
}
Each object in hours[] contains:
| Field | Type | Description |
|---|---|---|
hour_id |
int | Unique time-record identifier. |
user_id |
int/null | ID of the user associated with the record. |
comment_id |
int/null | ID of the related comment. Typically used by worked-time records. |
task_id |
int/null | ID of the related task. |
track_id |
int/null | ID of the related track. |
project_id |
int | ID of the related project. |
submitted |
datetime | Date and time associated with the time record. |
updated |
datetime/null | Date and time when the record was last updated. |
hours_estimated |
int/null | Estimated task time in seconds. |
hours_worked |
int/null | Worked time in seconds. |
hours_avaible |
int/null | Available user capacity in seconds. |
The endpoint does not include related names such as:
Use the corresponding API methods when those related objects are required.
| HTTP Code | error_no |
Message | Description |
|---|---|---|---|
401 |
– | Unauthorized |
Missing or invalid session_id, token, or project_token. |
200 |
7 |
limit reached |
Too many failed session-validation attempts from the same IP address. |
200 |
6501 |
submitted_begin wrong format, expected format: Y-m-d H:i:s |
submitted_begin could not be parsed. |
200 |
6502 |
submitted_end wrong format, expected format: Y-m-d H:i:s |
submitted_end could not be parsed. |
200 |
– | Internal API Error |
The time-record query failed. No method-specific error number is assigned in this case. |
This is a read-only method.
It does not create, update, or delete time records and does not publish WebSocket events.
hours_avaible is returned with this exact spelling.projects_users.AND.submitted_begin and submitted_end are inclusive.show_only values are ignored.show_only checks for non-null values, so zero values are included.total_hours_worked is returned only for show_only=hours_worked.total_hours_worked is calculated across all matching records before pagination.hour_id DESC.1000.order_dir accepts lowercase asc and desc.records_filtered contains the total number of accessible matching records before pagination.