- Created by Emre Toptancı, last modified on 20.02.2024
GET /rest/list
POST /rest/list
Returns a list report as text (CSV or JSON)
GET and POST methods provide the exact same functionality but POST method allows a much larger request size.
If your query parameters are too long to be used with a GET method (because you have a very long JQL or have too many statuses/fields selected) use POST method to access this endpoint.
If you have more than a few hundred issues, you're recommended to use file export endpoints rather than this one since getting the data as a single export file will produce much faster results, will create a much smaller load on your Jira instance, and can be implemented with less complexity.
Request
The request takes all parameters you select on the screen for a report as query parameters.
Do not let the long text scare you. Not all parameters are always required and some are required based on filterType. See the params table below.
Basic:
<service_url>/rest/list?filterType=<filterType>&(user=<user> | projectKey=<projectKey> | jqlFilterID=<jqlFilterID> | customjql=<customjql> | sprintID=<sprintID> )&columnsBy=<columnsBy>&calendar=<calendar>
With all parameters:
<service_url>/rest/list?filterType=<filterType>&(user=<user> | projectKey=<projectKey> | jqlFilterID=<jqlFilterID> | customjql=<customjql> | sprintID=<sprintID> )&columnsBy=<columnsBy>&fields=<fields>&statuses=<statuses>&groups=<groups>&includeDeletedStatuses=<includeDeletedStatuses>&startDate=<startDate>&endDate=<endDate>&dateRangeField=<dateRangeField>&trimHistoryStartDate=<trimHistoryStartDate>&trimHistoryEndDate=<trimHistoryEndDate>&calendar=<calendar>&dayLength=<dayLength>&viewFormat=<viewFormat>&outputType=<outputType>&pageSize=<pageSize>&startIssueIndex=<startIssueIndex>
Parameters
Parameter | Description | Required | Value Samples |
|---|---|---|---|
| outputType | The output format of the report. Possible options are:
If not provided, "json" will be used. |
| |
| filterType | Defines how the issues to be included in the report will be selected. Possible options are:
| Yes |
|
| user | If filterType is user, system expects a user name in the form user=<some_user_name> | Only when filterType = user |
|
| projectkey | If filterType is project, system expects a project key in the form projectKey=<project_key> | Only when filterType = project |
|
| jqlfilterID | If filterType is jqlfilter, system expects a JQL filter ID in the form jqlFilterID=<jqlFilterID> | Only when filterType = jqlfilter |
|
| customjql | If filterType is customjql, system expects a JQL Query in the form customjql=<customJQL> | Only when filterType = customjql |
|
| sprintID | If filterType is sprint, system expects a Sprint ID in the form sprintID=<sprintID> | Only when filterType = sprint |
|
| columnsBy | Defines the column structure of the report. Possible options are:
| Yes |
|
| timePeriod | The time period to use for statusDurationByTimePeriod and timePeriodDurationByStatus report types. Has no effect on other report types. Possible values are:
If not defined, Month will be used as the default value. |
| |
| multiVisitBehavior | Defines the behavior of reporting individual status visits. Only effective for Status Duration reports. If not provided, default behavior "total" will be used. |
| |
| pageSize | The maximum number of issues in a page. (1-100) The default is 100 and values greater than 100 or less than 0 will be processed as 100. | 50 | |
| startIssueIndex | The issue index to start at. The default value is 0. | 10 | |
| fields | The IDs of fields (separated by commas) on JIRA Issue that will be added to report output as columns. Both system and custom fields are supported. For more information see TiS Cloud - Field Names for REST Reports | assignee,customfield_10020,customfield_10007,description,duedate, fixVersions | |
| historyFields | The IDs of fields (separated by commas) on JIRA Issues that will be used for Any Field reports. For details about Any Field report types please see: TiS Cloud - Report Types Both system and custom fields are supported. For more information see TiS Cloud - Field Names for REST Reports | only when columnsBy = anyfieldDuration or anyFieldCount | assignee,customfield_10020,customfield_10007,fixVersions |
| statuses | A JSON array listing statuses for which the durations will be included in the report. If not provided or left empty, the report will include all statuses in selected issues' histories. For assignee based reports, durations of unselected statuses will be excluded from durations of assignee columns. Supports two formats: Basic and Advanced Basic: Basic format is a comma separated list of status ID's to be included in the report. Advanced: Advanced format is a JSON text that contains status definitions. Advanced format must be employed if you want to use the Consolidated Columns feature. Typetypeattribute of each column defines whether the column is a Standard(std) orConsolidated(cons) column. Forstandardcolumns,idis the id of the status. For consolidatedcolumns, the statuses array contains the IDs of statuses to be included in the column. For more information on status selection and column consolidation, please see TiS Cloud - Status. Other parameters may be included in the URL as a query parameter but statuses parameter is expected to be sent in request body encoded as "application/x-www-form-urlencoded" Note: You can get the list of statuses and their IDs, directly from your Jira. Please check Statuses part of the documentation. | Basic 1,3,4,5,10001,10234 Advanced [
{
"id":"6",
"type":"std"
},
{
"id":"2",
"type":"std"
},
{
"name":"cons. status 1",
"type":"cons",
"statuses":[
"10008",
"3",
"10007"
]
}
]
| |
| assignees | Comma-separated list of IDs of users that will be included in the report. If not provided or empty, the report will include all the assignees found in issues' histories. Please refer to Jira Cloud REST API Documentation to get the IDs of your users |
| |
| groups | The names of user groups (separated by commas) that will be included in Group reports. If not provided or empty, the report will included all durations in a column named "Not a member of selected groups" |
| |
| dbsMetrics | The list of metrics that will be showed as columns in Duration Between Statuses reports. The parameter must be provided as JSON text. The maximum number of metrics allowed is 10. Each metric will report the duration between two statuses (or status sets) and consists of the following parameters: name: (required) Name of the metric. Can only include alphanumeric characters and space. from: The starting status(es) that the duration will be calculated from. Its format should be a JSON object contains id and order (first/last) of the status(es). Not defining this parameter means that the starting point will be "issue creation". to: (required) The target status(es) that the duration will be calculated until. Its format should be a JSON object contains id and order (first/last) of the status(es). excluded: List of status ids that will be excluded from the calculations. Time spent on these statuses will not be added to total time. Note: You can get the list of statuses and their IDs, directly from your Jira. Please check Statuses part of the documentation. | only when columnsBy = durationBetweenStatuses | [
{
"name":"Resolution time",
"to":{
"id":["5", "7"],
"order":"first"
}
},
{
"name":"Development time",
"from":{
"id":["1", "2", "3"],
"order":"first"
},
"to":{
"id":["6"],
"order":"last"
},
"excluded":[
"10008",
"10003"
]
}
]
|
| includeDeletedStatuses | Sets whether included statuses in issues' histories will be included in the report or not: Possible options are:
If not provided, "true" is assumed. |
| |
| startDate | The start date of report filter. When provided, only issues created/resolved/updated (based on dateRangeField value) after the given date will be included in the report. Must be provided in "yyyy-MM-dd" or "yyyy-MM-dd hh:mm" format. If time parameter is not provided, default time "00:00" will be used | 2017-07-01 00:00 | |
| endDate | The end date of report filter. When provided, only issues created/resolved/updated (based on dateRangeField value) before the given date will be included in the report. Must be provided in "yyyy-MM-dd" or "yyyy-MM-dd hh:mm" format. If time parameter is not provided, default time "00:00" will be used | 2017-08-31 23:59 | |
| dateRangeField | The system date field of the Jira issue that startDate and endDate parameters will be based on. Possible options are:
| Only when either startDate or endDate is provided |
|
| trimHistoryStartDate | The start date of history trim for issues. When provided, only activities in each issue's history after the given date will be processed for the report. Must be provided in "yyyy-MM-dd" or "yyyy-MM-dd hh:mm" format. If time parameter is not provided, default time "00:00" will be used | 2017-07-01 00:00 | |
| trimHistoryEndDate | The end date of history trim for issues. When provided, only activities in each issue's history before the given date will be processed for the report. Must be provided in "yyyy-MM-dd" or "yyyy-MM-dd hh:mm" format. If time parameter is not provided, default time "00:00" will be used | 2017-08-31 23:59 | |
calendar | The calendar that report durations will be calculated based on. Possible options are:
Tip: You can get the IDs of calendars using the Calendars endpoint. | Required for Duration reports |
|
| dayLength |
| Required for Duration reports |
|
| viewFormat | The format of duration data in the report. Possible options are:
If not provided, "minutes" will be used. |
| |
| dateFormat | The string format to use for displaying values of fields of type Date If empty or missing, the date format defined in TiS Cloud - Format Settings page is used. If Format Settings date format is also empty, the default date format set for Jira is used. You can refer to the Java Documentation for more information about Date Format Strings. |
| |
| dateTimeFormat | The string format to use for displaying values of fields of type DateTime If empty or missing, the datetime format defined in TiS Cloud - Format Settings page is used. If Format Settings datetime format is also empty, the default datetime format set for Jira is used. You can refer to the Java Documentation for more information about Date Format Strings. |
| |
| emptyValueToken | The token to use for empty values in the report (for example when an issue has never visited a status) Selecting a custom token might make it easier for the requesting system to process the data. Possible options are:
|
|
Examples
https://tis.obss.io/rest/list?filterType=user&user=admin&columnsBy=statusDuration&startDate=2017-09-01 00:00&endDate=2017-10-31 00:00&dateRangeField=created&calendar=normalHours&viewFormat=minutes&pageSize=20 https://tis.obss.io/rest/list?filterType=user&user=admin&columnsBy=statusDuration&fields=assignee&statuses=3,10000,10001&includeDeletedStatuses=true&startDate=2017-09-01 00:00&endDate=2017-10-31 00:00&dateRangeField=created&calendar=normalHours&dayLength=24HourDays&viewFormat=minutes&outputType=csv&startIssueIndex=75 https://tis.obss.io/rest/list?filterType=project&projectKey=PMP&columnsBy=statusDuration&startDate=2017-09-01 00:00&endDate=2017-10-31 00:00 &dateRangeField=created&calendar=0&dayLength=24HourDays&viewFormat=minutes&outputType=json&pageSize=90&startIssueIndex=5 https://tis.obss.io/rest/list?filterType=jqlfilter&jqlFilterID=10004&columnsBy=statusDuration&startDate=2017-09-01 00:00&endDate=2017-10-31 00:00&dateRangeField=created&calendar=1&dayLength=businessDays&viewFormat=minutes&outputType=csv https://tis.obss.io/rest/list?filterType=customjql&customjql=project=ABC&columnsBy=statusDuration&multiVisitBehavior=first&startDate=2017-09-01 00:00&endDate=2017-10-31 00:00&dateRangeField=created&calendar=1&dayLength=businessDays&viewFormat=minutes https://tis.obss.io/rest/list?filterType=sprint&sprintID=2&columnsBy=statusDuration&startDate=2017-09-01 00:00&endDate=2017-10-31 00:00&dateRangeField=created&calendar=1&dayLength=businessDays&viewFormat=minutes&outputType=json&pageSize=5
Responses
Success
HTTP 200
Returns a list report as text (CSV or JSON)
{
"startIssueIndex":0,
"endIssueIndex":2,
"pageSize":100,
"total":2,
"dateTimeFormat":"dd/MMM/yy h:mm a",
"dateFormat":"dd/MMM/yy",
"timeZone":"Europe/Istanbul",
"locale":"en-US",
"viewFormat":"minutes",
"isComposite":false,
"columnsBy":"Status Duration",
"multiVisitBehavior":"total",
"calendar":{
"allWorkingDaysHaveEqualLengths": true,
"calendarSuccessfullyLoaded": true,
"clientKey": null,
"dailyWorkingHours": 24.0,
"holidays": [],
"id": null,
"is7x24Calendar": true,
"isDefault": null,
"name": "normalHours",
"timeZone": "UTC",
"workingTimes": [
{
"end": 86400000,
"start": 0,
"weekday": "SUNDAY"
},
{
"end": 86400000,
"start": 0,
"weekday": "MONDAY"
},
{
"end": 86400000,
"start": 0,
"weekday": "TUESDAY"
},
{
"end": 86400000,
"start": 0,
"weekday": "WEDNESDAY"
},
{
"end": 86400000,
"start": 0,
"weekday": "THURSDAY"
},
{
"end": 86400000,
"start": 0,
"weekday": "FRIDAY"
},
{
"end": 86400000,
"start": 0,
"weekday": "SATURDAY"
}
]
},
"dayLength": "24HourDays",
"query":" project = 'ABC'",
"trimHistoryStartDate":null,
"trimHistoryEndDate":null,
"reportDate":"03/Dec/20 1:56 PM",
"version":"1.29.0.1",
"includedStatuses":[
{
"id":"10000",
"name":"To Do",
"statusCategory":{
"id":"2",
"name":"To Do",
"key":"new",
"colorName":"blue-gray"
},
"deleted":false
},
{
"id":"10002",
"name":"Done",
"statusCategory":{
"id":"3",
"name":"Done",
"key":"done",
"colorName":"green"
},
"deleted":false
},
{
"id":"3",
"name":"In Progress",
"statusCategory":{
"id":"4",
"name":"In Progress",
"key":"indeterminate",
"colorName":"yellow"
},
"deleted":false
}
],
"excludedStatuses":[],
"deletedStatuses":[],
"isAggregationType":false,
"isOverall":false,
"isAverage":false,
"isSum":false,
"isMedian":false,
"isStddev":false,
"table":{
"header":{
"headerColumns":[
{
"id":"issuekey",
"value":"Key"
},
{
"id":"summary",
"value":"Summary"
}
],
"groupByColumns":[
],
"fieldColumns":[
],
"valueColumns":[
{
"id":"10000",
"value":"To Do",
"isConsolidated":false
},
{
"id":"10002",
"value":"Done",
"isConsolidated":false
},
{
"id":"3",
"value":"In Progress",
"isConsolidated":false
}
]
},
"body":{
"rows":[
{
"headerColumns":[
{
"id":"issuekey",
"value":"ABC-1"
},
{
"id":"summary",
"value":"Example 1"
}
],
"groupByColumns":[
],
"fieldColumns":[
],
"valueColumns":[
{
"id":"10000",
"value":"375967.9103666667",
"raw":"22558074622",
"count":"1"
},
{
"id":"10002",
"value":"-"
},
{
"id":"3",
"value":"-"
}
],
"currentState":[
{
"id":"10000",
"value":"375967.9103666667",
"raw":"22558074622"
}
]
},
{
"headerColumns":[
{
"id":"issuekey",
"value":"ABC-2"
},
{
"id":"summary",
"value":"Example 2"
}
],
"groupByColumns":[
],
"fieldColumns":[
],
"valueColumns":[
{
"id":"10000",
"value":"177492.9968833333",
"raw":"10649579813",
"count":"2"
},
{
"id":"10002",
"value":"266267.9513666667",
"raw":"15976077082",
"count":"1"
},
{
"id":"3",
"value":"0.1736166667",
"raw":"10417",
"count":"1"
}
],
"currentState":[
{
"id":"10002",
"value":"266267.8819",
"raw":"15976072914"
}
]
}
]
}
}
}
"Key","Summary","To Do","Done","In Progress" "ABC-1","Example 1","375974.8215666667","-","-" "ABC-2","Example 2","177492.9968833333","266274.8629333333","0.1736166667"
Invalid Parameter
HTTP 400
When one or more of the required parameters are missing or one or more of the supplied parameter values are invalid.
messages array contains the error messages for invalid parameters.
{
"status": 400,
"message": "Invalid report parameters",
"messages": [
"ERROR: columnsBy parameter is required. Possible values are assigneeduration, statusduration, groupduration, transitioncount, statuscount, firsttransitionfromstatusdate, firsttransitiontostatusdate, lasttransitionfromstatusdate, lasttransitiontostatusdate, assigneedurationbystatus, statusdurationbyassignee",
"ERROR: Invalid outputType value: 'xls'. Possible values are 'csv' and 'json'",
"ERROR: calendar parameter is required. Possible values are normalHours or ID of a custom defined calendar"
],
"pluginVersion": "1.18.0.1",
"time": "2020-05-22 07:04:20"
}
- No labels