Timepiece - Time in Status for Jira exposes its report data through a REST API, allowing you to programmatically access the same time-in-status data that is available on the Timepiece reporting screen. This makes it possible to feed Timepiece data into external tools, build custom dashboards, automate reporting workflows, and integrate with business intelligence platforms such as Power BI, Google Sheets, Microsoft Excel, and eazyBI.
The REST API parameters mirror the on-screen Timepiece report parameters, if you know how to configure a report in the Timepiece UI, you already understand the building blocks of a REST request.
Service URL
All REST requests must be directed to the Timepiece cloud service at:
https://tis.obss.io/
Only HTTPS communication is supported. All requests must use SSL. In the REST documentation, this address is referenced as <service_url>.
See Service URL for details.
Authorization
Every REST request requires a valid tisjwt token for authorization. Tokens are created and managed from the API Settings page under Jira Administration. Each token is tied to the permissions of the Jira user who created it — the API will only return data that user is authorised to see in Jira.
The token can be supplied in two ways. The recommended method is to include it in the HTTP request header using the Authorization key with the value TISJWT <your_token>. It can also be passed as a query parameter named tisjwt, though this is not recommended for production use as it exposes the token in URLs and access logs.
The API returns HTTP 401 responses for missing, invalid, expired, or deactivated tokens, and also when the Timepiece license on the instance is not valid.
See Authorization for the full details including request header format and error response examples.
Endpoints
The Timepiece REST API provides the following endpoints, grouped by purpose:
Report Endpoints return issue-level or aggregated time-in-status data:
-
Single Issue — returns Timepiece report data for one specific issue by its issue key.
-
Single Issue Expanded — returns the full status history breakdown for a single issue.
-
Issue List — returns report data for a list of issues matching a filter, with pagination support.
-
Issue List v2 — an updated version of the Issue List endpoint with enhanced parameter support.
-
Issue Aggregation — returns aggregated (Sum, Average, Median, Standard Deviation) report data across a set of issues.
-
File Export — generates and downloads a Timepiece report as a CSV, XLS, or XLSX file. Supports both synchronous (small export) and asynchronous (large export) modes.
Administration Endpoints allow programmatic management of Timepiece configuration:
-
Statuses — retrieves the list of Jira workflow statuses available on the instance.
-
Custom Calendars — allows reading and managing Timepiece custom calendar definitions via the API.
-
Parameter Sets — allows listing and retrieving saved Timepiece parameter sets, which can then be used as the basis for REST report requests.
-
Format Settings API — allows reading and updating Timepiece date format settings via the API.
See Endpoints for the full reference.
Field Names for REST Reports
When building REST requests, Jira issue fields are referenced by specific field name strings rather than their display labels. Timepiece supports a wide range of system fields — such as assignee, project, issuetype, priority, status, created, resolutiondate, and many others — as well as any custom field using the format customfield_xxxxx.
Date fields can also be used in parts for grouping purposes, allowing you to group issues by the year, quarter, month, week, or day of a date field. For example, date:month:created groups issues by the month of their creation date.
To find the field IDs of custom fields on your Jira Cloud instance, call the standard Jira API endpoint at <your_jiracloud_url>/rest/api/3/field.
See Field Names for REST Reports for the complete reference table.
Getting Reports with Parameter Sets
Most REST API endpoints support using a saved Timepiece parameter set as the basis for a request. Instead of specifying every report parameter individually in the API call, you can reference the ID of a saved parameter set and the report will be built from those saved settings.
Any parameters you include explicitly in the request will override the corresponding values from the parameter set, giving you the flexibility to reuse a saved configuration while varying specific parameters — such as the date range or filter — on each call.
Parameter set IDs can be retrieved via the Parameter Sets endpoint.
See Getting Reports with Parameter Sets for full details including how parameter overriding works and how the same parameter set behaves differently across list vs aggregation endpoints.
Spreadsheet Automation
If you want to pull Timepiece data directly into Google Sheets or Microsoft Excel without writing custom code from scratch, ready-to-use template files are available. These templates include built-in scripts that connect to the Timepiece REST API and populate the spreadsheet automatically. See Sample Spreadsheet Integration Files for the files and setup instructions.
Rate Limiting
The Timepiece REST API is subject to rate limits to ensure service stability. See Rate Limit for the current limits and how to handle rate limit responses in your integration.