WORKSECTION

Costs

Getting time and finanсial costs of tasks through API: get_costs

Sample get_costs request

?action=get_costs
Returns individual costs added for selected or all tasks

Optional parameters:
  • id_project — project ID (costs of all tasks of a particular project)
  • id_task — task ID (costs of a particular task)
  • datestart and dateend — searching data range in DD.MM.YYYY format (inclusive)
  • is_timer — time costs type, possible values:
    1 — received from the timer
    0 — entered manually
  • filter — additional searching parameter (see search_tasks for a list of operators to work with data used in filter)

Possible data for use in filter (for the get_costs method):
  • id=TASK_ID — costs of a particular task (Integer field)
  • project=PROJECT_ID — costs on tasks of a particular project (Integer field)
  • comment — user comment to a separate cost line (String field)
  • dateadd — date, when the costs were added in the 'DD.MM. YYYY' format (String field)
Returned data:
  • id — cost line ID
  • comment — user comment to a separate cost line
  • time — time cost value
  • money — financial cost value
  • date — date, when the costs were added
  • is_timer — time costs type
    • true — received from the timer
    false — entered manually
    • user_from — user, who added an individual cost line
    • task — task, where costs are added (see get_task method for details on returned parameters meaning)
    • total — total time and financial costs of all cost lines

Sample JSON response
If the request succeeds, the response will contain ok status and the following data:

{
    "status": "ok",
    "data": [
        {
            "id": "COSTS_ID_1",
            "comment": "COSTS_COMMENT",
            "time": "10:00",
            "money": "100.00",
            "date": "YYYY—MM—DD",
            "is_timer": false,
            "user_from": {
                "id": "USER_ID",
                "email": "USER_EMAIL",
                "name": "USER_NAME"
            },
            "task": {
                "id": "TASK_ID",
                "name": "TASK_NAME",
                "page": "/project/PROJECT_ID/TASK_ID/",
                "status": "active",
                "priority": "0..10",
                "user_from": {
                    "id": "USER_ID",
                    "email": "USER_EMAIL",
                    "name": "USER_NAME"
                },
                "user_to": {
                    "id": "USER_ID",
                    "email": "USER_EMAIL",
                    "name": "USER_NAME"
                },
                "project": {
                    "id": "PROJECT_ID",
                    "name": "PROJECT_NAME",
                    "page": "/project/PROJECT_ID/"
                }, 
                "date_added": "YYYY—MM—DD HH:II",
                "date_start": "YYYY—MM—DD",
                "date_end": "YYYY—MM—DD",
                "time_end": "HH:II",
                "max_time": 20,
                "max_money": 500,
                "tags": {
                    "TAG_ID": "TAG_NAME_1",
                    "TAG_ID": "TAG_NAME_2",
                }
            },
   
        },
        {
            "id": "COSTS_ID_2",
            "comment": "COMMENT_COSTS",
            ... ... ...
        }
    ],
    "total": {
        "time": "HH:II",
        "money": "10.01"
    }
}
Was this article helpful? Yes, thank you! No

Getting total time and financial costs API: get_costs_total

Sample get_costs_total request

?action=get_costs_total
Returns total time and cost data for projects or for a specific task

Optional parameters:
  • id_project — project ID (total costs of a particular project)
  • id_task — task ID (total costs of a particular  task)
  • datestart and dateend — searching data range in DD.MM.YYYY format (inclusive)
  • is_timer — time costs type, possible values:
      • 1 — received from the timer
      0 — entered manually
    • filter — filter for fetching data across multiple projects (see details below)
    • extra=projects — adds aggregated and monthly costs for each project in the selection (for a specific project or multiple projects when using id_project or filter, or for all projects when no project-selection parameters are provided). The parameter is ignored when id_task is used
    Available values for filter (for get_costs_total method)

    Filter by ID
    project=2456
    Filter by ID range
    project in (1234, 1240)
    Combining filters
    *use parentheses ( ) and logical operators and, or (must be lowercase)
(project=2456 and project=2464) or project in (2450, 2470)
Sample JSON response
If the request succeeds, the response will contain ok status and the following data:

*without extra=projects
{
    "status": "ok",
    "total": {
        "time": "30:00",
        "money": "300.00",
    }
}
*with extra=projects
{
    "status": "ok",
    "projects": {
        "PROJECT_ID_1": {
            "time": "10:00",
            "money": "100.00",
            "monthly": {
                "2024-04": {
                    "time": "2:00",
                    "money": "20.00"
                },
                "2024-03": {
                    "time": "8:00",
                    "money": "80.00"
                },
 ... ... ...
            },
            "id": "PROJECT_ID_1",
            "name": "PROJECT_NAME_1",
            "page": "/project/PROJECT_ID_1/"
        },
        "PROJECT_ID_2": {
            "time": "20:00",
            "money": "200.00",
            "monthly": {
                "2024-02": {
                    "time": "4:00",
                    "money": "40.00"
                },
                "2024-01": {
                    "time": "16:00",
                    "money": "160.00"
                },
 ... ... ...
            },
            "id": "PROJECT_ID_2",
            "name": "PROJECT_NAME_2",
            "page": "/project/PROJECT_ID_2/"
        },
 ... ... ...
    },
    "total": {
        "time": "30:00",
        "money": "300.00"
    }
}
Was this article helpful? Yes, thank you! No

Adding time and financial costs in task through API: add_costs

Sample add_costs request

?action=add_costs&id_task=TASK_ID&time=TIME
Creates individual costs for selected task

Required parameters:
  • id_task — task ID

Conditional parameters:
*at least one of parameters required: time, money
  • time — time costs in one of the following formats: 0.15 / 0,15 / 0:09
  • money — financial costs in account currency (if it needs to be specified without reference to an hourly rate)

Optional parameters:
  • email_user_from — cost author email (will be set automatically if using access token)
    required if using admin token 
  • is_rate=1 — financial costs are calculated on an hourly rate (money parameter is ignored)
  • comment — cost log comment
  • date — cost log date in DD.MM.YYYY format
Sample JSON response
If the request succeeds, the response will contain ok status and id of the cost line:

{
    "status": "ok",
    "id": "COSTS_ID"
}
Was this article helpful? Yes, thank you! No

Updating time and financial costs of task through API: update_costs

Sample update_costs request

?action=update_costs&id=ID_COSTS&time=2
Updates selected individual costs of task

Required parameters:
  • id_costs — cost ID (can be obtained through get_costs method)

Optional parameters:
  • time — time costs in one of the following formats: 0.15 / 0,15 / 0:09
  • money — financial costs in account currency (if it needs to be specified without reference to an hourly rate)
  • is_rate=1 — financial costs are calculated on an hourly rate, if new time value is specified (money parameter is ignored)
  • comment — cost log comment
  • date — cost log date in DD.MM.YYYY format

Parameters unavailable for updating:
  • email_user_from — cost author email
Sample JSON response
If the request succeeds, the response will contain ok status

{
    "status": "ok",
}
Was this article helpful? Yes, thank you! No

Deleting time and financial costs of task through API: delete_costs

Sample delete_costs request

?action=delete_costs&id=COSTS_ID
Deletes selected individual costs of task

Required parameters:
  • id — cost ID (can be obtained through get_costs method)
Sample JSON response
If the request succeeds, the response will contain ok status

{
    "status": "ok",
}
Was this article helpful? Yes, thank you! No
esc
или
Print