The File Export endpoints allow you to generate and download a complete Timepiece report as a file (in CSV, XLS, or XLSX format) through the REST API. Unlike the JSON/CSV response endpoints which return data inline, file exports are designed to package an entire dataset into a single downloadable file, making them ideal for feeding data into spreadsheets, BI tools, or automated pipelines.
File exports accept the same report parameters as the other Timepiece REST endpoints (filter type, report type, statuses, calendars, date ranges, fields, sorting, and filtering) giving you full control over what the exported file contains.
Two export modes are available depending on the size of your dataset and the requirements of your integration. File exports can work Synchronously or Asynchronously.
Synchronous File Export (Small Export)
GET /rest/smallexport POST /rest/smallexport
The synchronous export is the simpler of the two options. You make a single request, the export is processed, and the completed file is returned directly in the response. No polling or follow-up requests are needed.
This mode works well for smaller to medium-sized datasets. However, it operates within the standard HTTP 60-second timeout limit. If processing your request takes longer than 60 seconds the request will time out and return a 408 response. Under normal conditions, synchronous exports can handle 10,000+ issues without hitting this limit, though this varies depending on your Jira instance's capacity and current load.
See Synchronous File Export for the full parameter reference and example requests.
Asynchronous File Export
The asynchronous export removes all timeout constraints and is the recommended approach for large datasets. Instead of waiting for the file to be generated within a single request, the export is queued as a background process on the server the moment you call the Start an Export endpoint. An export ID is returned immediately and the connection is closed, so there is no timeout risk regardless of how many issues need to be processed.
Once the export is running, you track its progress. When the export is complete, you retrieve the generated file using the Download an Export File endpoint. If you need to cancel a running export before it finishes, the Abort an Export endpoint handles that.
See Asynchronous File Export for the full guide covering all five async endpoints.
Which Mode Should I Use?
Use Synchronous when your dataset is small to medium, your integration expects an immediate file response, and you want the simplest possible implementation.
Use Asynchronous when your dataset is large or unpredictable in size, you have been experiencing 408 timeout errors from the synchronous endpoint, or your integration can handle a polling loop. The async mode has no issue count limit and is the recommended approach for production integrations dealing with large Jira projects.