Time Reports

REST API Reports are similar to custom Tabular Reports. They allow you to extract data from the system in the XML or JSON format. Both formats are not very visual and readable for the human eye, but they can be used as valuable input for your custom integration scripts and standalone applications. Fortunately enough, MS Excel accepts XML files as a data source as well.

REST API Report by Time Spent

Here are some samples of REST API queries that will help you to build the report for Time. You are welcome to combine or modify each of the samples to better fit your requirements.

GET /api/v1/Times

Extracts all Times posted in the system, contains the first 25 items by default, and has XML format by default. Records in the output are not sorted.

GET /api/v1/Times?take=1000

Takes the first 1000 items at a time. 1000 is the limit here, it is not possible to extract more at a time.

GET /api/v1/Times?take=25&skip=25

Takes the second page of the output: skips the first 25 entries and takes the next 25.

GET /api/v1/Times?where=(Date gte '2017-08-01') and (Date lte '2017-09-01')

Filters Time records by date range: date is between Aug 1, 2017 to Sep 1, 2017 inclusively.

GET /api/v1/Times?where=Description contains 'refactoring'

Filters Time records by a given word in the Time record Description field.

GET /api/v1/Times?where=Project.Name eq 'TP3'

Filters Time records by the Name of a Project. You can filter by any other attribute of the Project object as well.

GET /api/v1/Times?where=User.LastName eq 'Brown'

Filters Time records posted by a specific User. You can filter by any other attribute of the User object as well.

GET /api/v1/Times?where=Role.Name eq 'Developer'

Filters Time records posted by Users with a specific Role. You can filter by any other attribute of the Role object as well.

GET /api/v1/Times?where=Assignable.Id eq '110'

Filters Time records added against the Assignable with the specified ID. You can filter by any other attribute of the Assignable object as well.

GET /api/v1/Times?include=[User[FirstName,LastName],Date,Spent,Assignable[Id,Name,EntityType]]

Specifies fields to be included in the report.

GET /api/v1/Times?orderBy=CreateDate
GET /api/v1/Times?orderByDesc=CreateDate

Sorts data output by a specific field forwards or backwards.

GET /api/v1/Times?format=json

Provides JSON-formatted output instead of default XML format.

REST API Report by Time with Summary Columns

Below you will find several sample API queries for data aggregation:

GET /api/v1/UserStories?include=[Id,Name,Effort,EffortCompleted,EffortToDo,TimeSpent,TimeRemain]

Gives you the list of all User Stories including Id, Name, and totals by Effort (in Points or Ideal hours) and Time (in real Hours). If your Report is based on a User Story entity, the Time Spent column is always a sum of Times Spent for the User Story itself plus Times Spent for all child Tasks.

GET /api/v1/Iterations?include=[Id,Name,StartDate,EndDate,Velocity,UserStories-TimeSpent-Sum,Bugs-TimeSpent-Sum,UserStories-EffortCompleted-Sum,Bugs-EffortCompleted-Sum]

Filters the list of all Iterations, includes Id, Name, Start and End date, Planned Velocity for each Iteration and calculates the following summary values:

• Sum of Time Spent for all User Stories in the Iteration
• Sum of Time Spent for all Bugs in the Iteration
• Sum of Completed Effort for all User Stories in the Iteration (sums for child Tasks are included there!)
• Sum of Completed Effort for all Bugs in the Iteration

Sums of Effort Completed give you real velocity (in Ideal Hours or Points) achieved in the Iteration, while sums of Time Spent show the amount of real hours spent. It allows you to compare the values and report Estimation Accuracy.

You are welcome to build similar REST API reports using the following objects: Releases, TeamIterations, Assignables, Projects, Teams.