Holistics Docs - End-to-End Business Intelligence Platform

Holistics Documentation

Welcome to the Holistics Documentation page. You'll find comprehensive guides and documentation to help you start working with Holistics as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started

Working with Data via API

There are several ways for working with APIs in Holistics, you can refer to the full documentation here.

For getting data via API, you can use our HTTP API methods and Python package.

Reports API

This is useful especially if you need to pass live data to your other applications. For example, you may want to feed a live CSV endpoint of your user segmentation list into your email marketing application so that you can always get fresh data upon retrieving them.


Please see guide to setup your API key.

Submit Report Query

To submit a report query job, you will need to use the following HTTP endpoint:

GET /queries/<report_id>/submit_query.json?<filter_param1>=<filter_value1>...

If successful, this endpoint will return the job ID of the job created. To get the result, you will need to poll for the job status with

GET /queries/get_query_results.json?&job_id=<job_id>

Do note that the results are paginated, look into the paginated section of the response JSON for more information. To fetch the next page of data, append &_page=<page_number> to the URL.


  • _page_size: (optional) set the page size of the response
  • _page: (optional) set the page number of data to fetch

Submit Report Export Job

In order to download the CSV or Excel for a report's result set, you will need to use the following:

GET /queries/<report_id>/submit_export.<format>?<filter_param1>=<filter_value1>...
  • Supported format: csv/json/xlsx

Or if your query string is too long (> 500 letters), you can consider using a POST request:

POST /queries/<report_id>/submit_export.<format>

In the request body, specify the filter values in JSON format:

  "customer_ids": [1, 2, 3],
  "status": "active"
  • Supported format: csv/json

If successful, the endpoint will return the job ID for the export job created. To get the result, you will need to poll for the job status with either of these endpoints:

GET /queries/get_export_results.json?job_id=<job_id>

or this endpoint:

GET /jobs/<job_id>/get_results.json

Once the job status is 'success', you can download the result file via exports/download endpoint

GET /exports/download?job_id=<job_id>

Pushing CSV data back into Holistics via CLI

For more details on setting up the Holistics gem for command line tools, you can refer to our Holistics CLI documentation.

Once you have setup the Holistics gem for your CLI tool, authenticate your API token in your CLI.

$ holistics login <token>
Authenticating token...
Authentication successful. Info:
- ID: 1
- Email: [email protected]

Type holistics help for a full list of CLI commands. For example, you can re-import CSV data that you have worked on into Holistics, using the following command:

holistics import csv -d, --dest-ds-id=DEST_DS_ID -f, --filepath=FILEPATH -t, --dest-table-name=DEST_TABLE_NAME  # Import a local CSV file to destination server
More details on importing via CLI can be found using `help`:
[![Holistics CLI import](https://cdn.holistics.io/docs-images/cli-import.png)](https://cdn.holistics.io/docs-images/cli-import.png)

# Package for Python

Our package ([**Holistics Package for Python**](https://github.com/holistics/holistics-python)) allow Python's user export report's data by inputting:
- Your API-key
- Report's ID
- Dictionary of filters applied to that report

  "type": "info",
  "body": "**Supported output format**: DataFrame object, .CSV\n**Python version**: >= 3, < 4",
  "title": "Notes"


Package can be installed with `pip`:
pip install holistics
Alternatively, you can grab the latest source code from GitHub:
git clone git://github.com/holistics/holistics-python.git
cd holistics-python
python setup.py install

How to export data

Beginning by import holistics package

from holistics import HolisticsAPI

Next, creating an object of HolisticsAPI class with your API-key and Holistics server's url

obj = HolisticsAPI(api_key = 'aerg454hoiaKJGlgku', url = 'demo.holistics.io')


Finally, call export_data function with specific syntax:
export_data (report_id, path, filters, page_size, page)

my_dataframe = obj.export_data(report_id='123456', path='C:/output.csv', 
                              filters={'date': '2017-04-28', 'vat': 1.1}, 
                              page_size = 12, page = 5)


  • report_id (str): ID of report. Get from URL.
  • path (str) (optional): If you want to store export data to local path, set path variable.
    • Default value: None
    • Ex: 'D:/Data/output.csv'
  • filters (dict) (optional): dictionary of filters that would be applied to report.
    • Default value: None
    • Ex: {'tenant': 'holistics', 'date': '2017-04-28'}
  • page_size (int) (optional): Set the page size of the response.
    • Default value: 10000000
  • page (int) (optional): Set the page number of data to fetch.
    • Default value: 10000000

A DataFrame object. If path is not None, save object as .csv file at that path.


  • HTTPError: If the program can't connect to target site and get data.
    • You should check your API-key, url of Holistics and internet connection.
  • RuntimeError: If return status is Failure.
    • It could be caused by wrong SQL of your QueryReport.
  • ParserError: If program can't parse downloaded data as DataFrame object.
    • It could be caused when downloaded data is None.

Finding your Source ID and Source Type

The Source ID and Type could get easily by viewing on the URL: https://secure.holistics.io//-sample-name. The type is mapped to Source Type by this table below:


For example, we have an URL: https://secure.holistics.io/queries/11111-table-with-dropdown-filter. 11111 is the Source ID, and the type is QueryReport (mapped from queries)

Updated 8 months ago

Working with Data via API

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.