GitLab Time Tracking: Estimates, Spent Time & API

GitLab’s time tracking lets you set time estimates on issues and merge requests, log the time you spend on them, and pull both numbers through the REST API for reports or dashboards. You enter an estimate and then add spent time via quick actions or the API, and GitLab stores them as seconds, returning them as seconds in API responses and as human-readable strings in the UI. This article explains how estimates and spent time work, how to use the API to retrieve them, and how to build a report from that data.

How GitLab Time Tracking Works

GitLab’s time tracking is per-issue and per-merge-request. You can set a time estimate and log spent time using quick actions in the issue description or comment box:

• /estimate 1w 2d 3h 4m — sets the estimate (weeks, days, hours, minutes).
• /spend 30m — adds 30 minutes of spent time.
• /spend -15m — subtracts 15 minutes (useful for corrections).
• /remove_estimate and /remove_time_spent — clears the values.

GitLab stores time in seconds. A day is 8 hours, a week is 5 days (40 hours). So 1w = 288,000 seconds, 1d = 28,800 seconds, 1h = 3,600 seconds, and 1m = 60 seconds. The UI shows these as “1w 2d 3h 4mâ€� but the API returns raw seconds.

Retrieving Estimates and Spent Time via the API

The GitLab REST API exposes time tracking fields on issues and merge requests. For a single issue, use:

GET /projects/:id/issues/:issue_iid

The response includes time_estimate (seconds) and total_time_spent (seconds). For example, a response snippet might look like:

"time_estimate": 288000,
"total_time_spent": 3600

To get all issues in a project (useful for reports), use the list endpoint:

GET /projects/:id/issues?scope=all

Each issue in the list carries the same fields. For merge requests, the endpoints are /projects/:id/merge_requests and /projects/:id/merge_requests/:iid, with identical time fields.

Building a Time Report from API Data

To create a report, you’ll typically fetch all issues or merge requests in a project or group, then sum the total_time_spent values. Since the API returns seconds, convert to hours or days as needed. A common pattern is:

1. Call GET /projects/:id/issues?per_page=100&page=1 (and loop through pages).
2. For each issue, read time_estimate and total_time_spent.
3. Sum the spent times, optionally grouping by assignee, milestone, or label.
4. Compare total spent vs. total estimate to see over/under-budget.

You can also use the updated_after and updated_before parameters to filter by date range, or milestone and labels to narrow down the set. For group-level reports, use GET /groups/:id/issues to get issues from all projects in the group.

Common Pitfalls and Misconceptions

One frequent confusion is the difference between time_estimate and total_time_spent in API responses. The estimate is a single value you set; the spent time is cumulative. There is no “remainingâ€� field — you compute it as time_estimate - total_time_spent.

Another pitfall: GitLab’s /spend quick action adds to the existing total; it does not overwrite. If you log 30m twice, the total becomes 1h. To correct, you must subtract the overcounted amount.

Also note that the API returns seconds as integers, not strings. If you’re writing a script, ensure you parse them as numbers. And the “human-readable� format (e.g., “2h 30m�) is not available via the API — you must convert yourself.

Comparing with Other Time Tracking Methods

GitLab’s built-in time tracking is lightweight. It doesn’t have a separate timesheet module or approval workflow. Alternatives include:

• Using the API to sync data to an external tool like Toggl or Harvest (via their APIs).
• Using GitLab’s “Time Tracking Reportâ€� in the project’s “Analyticsâ€� section, which shows a simple bar chart of time spent per issue.
• Using third-party GitLab integrations that add more detailed reporting, but those often require extra configuration.

For most teams, the built-in fields plus a small script that pulls from the API is sufficient. The main advantage of the API is that you can combine estimate and spent data with other fields (assignee, milestone) to create custom reports.

Costs and Limits

Time tracking is available on all GitLab tiers, including the free tier. The API is also available on all tiers, but rate limits apply. For GitLab.com, the default rate limit is 600 requests per minute for authenticated requests (subject to change). For self-managed, the admin can set limits. If you’re pulling a large number of issues, you’ll need to paginate (per_page max is 100) and handle rate limits gracefully.

Practical Example: Summing Spent Time via API

Here’s a simple Python example that fetches all issues in a project and sums the spent time (you’ll need a personal access token with read_api scope):

import requests

project_id = 123
private_token = 'YOUR_TOKEN'
url = f'https://gitlab.com/api/v4/projects/{project_id}/issues'
headers = {'PRIVATE-TOKEN': private_token}
params = {'per_page': 100, 'scope': 'all'}

total_spent = 0
total_estimate = 0
page = 1
while True:
    params['page'] = page
    r = requests.get(url, headers=headers, params=params)
    data = r.json()
    if not data:
        break
    for issue in data:
        total_spent += issue['total_time_spent']
        total_estimate += issue['time_estimate']
    page += 1
    if page > 10:  # safety break for demo
        break

print(f'Total spent: {total_spent} seconds ({total_spent/3600:.2f} hours)')
print(f'Total estimate: {total_estimate} seconds ({total_estimate/3600:.2f} hours)')

This script loops through pages, sums the seconds, and prints the totals. Note that it doesn’t handle rate limiting or errors, but it shows the core logic.

Frequently Asked Questions

How do I get the total time spent on a single issue via API?

Call GET /projects/:id/issues/:issue_iid and read the total_time_spent field in the response. It’s in seconds.

Can I log time via the API?

Yes, you can add time with the POST /projects/:id/issues/:issue_iid/add_spent_time endpoint, passing a duration parameter like 2h30m. Similarly, you can set an estimate with POST /projects/:id/issues/:issue_iid/time_estimate.

Why does the API return seconds but the UI shows “2h 30m�?

The API is designed for machine readability, so it returns raw integers. The UI converts seconds to a human-friendly format. You’ll need to convert in your own code.

Does time tracking work on epics?

No, GitLab’s built-in time tracking is only available on issues and merge requests, not on epics. You can, however, sum the time from child issues of an epic via the API.

Can I export a CSV of time spent?

Not directly from the UI. You can use the API to fetch the data and then generate a CSV yourself. Some third-party tools offer this, but GitLab doesn’t have a native CSV export for time tracking.

What happens if I change the estimate after logging time?

The spent time remains unchanged. The estimate is just a number; changing it doesn’t affect the logged time. You can always adjust either independently.

Related

• Triangle Area Dentists in Clementi: Full Guide
• How to Root HTC One M8 Eye
• Lenovo Yoga Mini X7 Ports, Performance & Limits