Use the Data Export API

To begin using your data, first access the qTest Data Export API to download your data as flat parquet files.

The first set of data you download from the API is your historical data. After this, each download is a delta data update, which is a set of CRUD operations in a flat parquet file. You need to apply these operations to your historical data each day to update it.

The endpoints in this API return two separate items:

• A list of the filepaths for the parquet files you want to download.

• Flat parquet files that contain your data.

Before you start

Before you can access your data, you need to do a few prerequisite items.

Do you have your API key?

Request Tricentis Analytics Viewer permissions from your admin to access the API.

Set up authentication with the qTest API.

And maybe check out our Swagger to learn more about individual calls or to test out the API.

Get your parquet files from the API

The API sends a new delta data update in a parquet file each day. Because you need to get your delta data updates from the API before they expire, we suggest that you automate the process to download and store your data.

To download your parquet files from the API, follow these steps:

1. Build a request to call the API with your URI and your API key.

   Your base URI depends on your AWS Region:

   • US-East: https://dataexport-1.qtestnet.com/uta/api/v1/

   • US-West: https://dataexport-2.qtestnet.com/uta/api/v1/

   • EMEA: https://dataexport-3.qtestnet.com/uta/api/v1/

   • APAC: https://dataexport-4.qtestnet.com/uta/api/v1/

2. Call GET /files to get a list of filepaths to the parquet files that contain the data you want to download.

   Here's what this call can look like:

   objectsUri = baseURI + "files?directoryFilter=" + filter + "pageToken=" + str(urllib.parse.quote(pageToken, safe='')) 
   
   response = requests.get(objectsUri, headers={"apikey":apikey, "Authorization":bearerToken})

   Keep these things in mind:

   • You must format the directoryFilter parameter qTest/yyyy-MM-dd/tablename. For example, to retrieve all files for the Builds table on January 15, 2024, enter qTest/2024-01-15/builds as the value for directoryFilter.

   • You must URL quote filepath and pageToken values in your code, or the API returns an error.

   • You can use the pageSize parameter to limit the number of results the API returns per pageed by the API. By derfault, the API returns, this parameter is set to the maximum: value of 1000 entries per page.

   • You don't need the pageToken parameter in your first request. Subsequent calls use this parameter when the initial API call can't return all objects because the pulled data exceeds the maximum page size.

3. Check your results. The API returns a list of your requested filepaths in the following format: YYYY-MM-DD/<table_name>/<MajorChunkId>_part_<MinorChunkId>.parquet.

   • YYYY-MM-DD: date the data is loaded into the API, not the date the data was created in qTest.

   • <MajorChunkId>: four-digit identification number.

   • <MinorChunkId>: two-digit update identification number.

   For example, 2022-12-04/builds/0000_part_00.parquet.

4. If the result doesn't contain all of your requested filepaths, the lastPage parameter in the API response is False.

   To retrieve the remaining filepaths, use the pageToken value you get from the response in your next API call.

5. To get the data, call GET /file/{filepath the API returned} and download your data to your request client.

   Here's what this call can look like:

   filesURL = baseURI + "/file/" + str(urllib.parse.quote(filepath, safe=''))
   response = requests.get(filesURL, headers={"apikey":apikey, "Authorization":bearerToken})

   Please note that outputs with a string data type have a 21,000 character limit. If your data output contains more characters, we truncate your data to the first 21,000 characters.

For more information about how to use the qTest API, check out the qTest API documentation (opens in new tab).

What's next

You have your raw data. Now you need to update it, so you can join it to external data, create views, or import it into your BI tool.