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.

API Key

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.

Params:

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

Legacy Syntax

This API is deprecated. Please use the async way to get data.

You can also use this endpoint to fetch the query result:

GET /queries/[report_id].json?job_id=<job_id>

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>

Small dataset (< 10K rows)

This API is deprecated. Please use the asynchronous submit_export API instead.

For a small dataset (less than 10 thoudsands rows), you can use just this endpoint to download the data:

GET https://secure.holistics.io/queries/<report_id>.<format>?<filter_param1>=<filter_value1>...

How often does these API data refresh?

This is based on your report cache duration that you set in the report.