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.

You will not receive a notification when your data is about to expire. Each data upload is available for 90 days before it expires. If you miss a single data point in a table, it will corrupt your data. If this happens, contact our support, so we can help you replace your missing data points.

Before you start

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

Do you have your API key?

Ask your admin to add you to the Tricentis Analytics Viewer user group to access the API.

Set up authentication with the qTest API.

You can also view API documentation in Download qTest Resources 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.

Currently, you will not receive a notification if your daily delta sync fails to update. For this reason, we recommend that you add an automated check to your pipeline to verify that a new file for the current date appears by the defined time each morning. If it doesn't appear, please contact Support.

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-1: https://dataexport-1.qtestnet.com/uta/api/v1/

    • US-East-2: https://dataexport-5.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 in Download qTest Resources.

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.